> ## Documentation Index > Fetch the complete documentation index at: https://glasser.ai/docs/llms.txt > Use this file to discover all available pages before exploring further. # Pesquisa de SEO > Pesquise volume e dificuldade de palavras-chave, posições nos resultados de busca, backlinks, auditorias de sites e visibilidade em respostas de IA em vários provedores de dados com uma única saída normalizada. Escolha uma ação e forneça palavras-chave ou um domínio. Cada ação retorna `output` normalizado. A saída nativa do Provedor não é repetida ali; ela permanece no Run e pode ser lida com [Get Run](https://glasser.ai/docs/pt/api-reference/runs/get.md). As ações de listagem expõem `output.items[]` com campos fixos por linha; as ações de visão geral expõem campos fixos no nível superior. Um valor que o Provedor selecionado não informa é `null`; o Glasser não converte nem preenche valores. Os valores monetários são sempre em USD (`cpc_usd`, `organic_traffic_value_usd`). `volume`, `traffic` e `cpc_usd` são estimativas próprias do Provedor que responde. Compare-os somente dentro de um mesmo Provedor (`runs[].provider`), não entre Provedores. Leia `result_status` separadamente de `status`: `success`, `no_result`, `error` ou `pending`. Uma resposta vazia, mas válida, é `no_result` e mantém o formato da ação: `items` é `[]`, ou todos os campos de nível superior são `null`. `error` com `error.code` significa que a saída do Provedor não pôde ser entregue. `charge_usd` totaliza os `runs` desta resposta, incluindo resultados vazios cobrados, e é nulo até que todos os Runs sejam concluídos. Com `provider: auto`, o fallback pode criar vários Runs, cada um listado em `runs[]` com sua própria cobrança. Para um rastreamento pendente (`site_audit`, HTTP 202), siga o [result\_url](https://glasser.ai/docs/pt/api-reference/solutions/gtm/seo_research/result.md) autenticado. [Get Run](https://glasser.ai/docs/pt/api-reference/runs/get.md) continua sendo nativo e informa uma cobrança individual. Consulte [Seleção de Provedor e cobranças](https://glasser.ai/docs/pt/api-reference/solutions/overview.md#how-provider-selection-works). ## Saída por ação Cada campo está presente em todas as linhas; um valor que o Provedor não informa é `null`. Os campos seguem as [convenções de campos](https://glasser.ai/docs/pt/api-reference/solutions/overview.md#field-conventions): os valores monetários terminam em `_usd`, os registros de data e hora terminam em `_at` (UTC ISO 8601), e `domain` é um nome de host simples, sem `www.` nem porta. As pontuações de autoridade mantêm a métrica e o nome próprios de cada Provedor e nunca são convertidas: `ahrefs_domain_rating` (Domain Rating da Ahrefs, 0–100, pode ter casas decimais), `semrush_authority_score` (Authority Score da Semrush, 0–100), `dataforseo_rank` (classificação da DataForSEO, 0–1000) e `serpstat_domain_rank` (Domain Rank da Serpstat, 0–100). A dificuldade de palavras-chave é dividida da mesma forma: `semrush_keyword_difficulty`, `serpstat_keyword_difficulty`, `dataforseo_keyword_difficulty` e `ahrefs_keyword_difficulty` são cada uma de 0–100 no modelo próprio do Provedor; portanto, a mesma palavra-chave pode receber pontuações muito diferentes entre eles. `dataforseo_onpage_score` é a pontuação própria de página da DataForSEO. Somente o campo do Provedor que respondeu é preenchido; os demais são `null`. `position` é a posição orgânica: 1 é o primeiro resultado orgânico, e recursos da SERP, como anúncios ou caixas de resposta, não são contabilizados. | `action` | `output` | | - | - | | `keyword_overview` | `items[]`: `keyword`, `volume`, `cpc_usd`, `semrush_keyword_difficulty`, `serpstat_keyword_difficulty`, `dataforseo_keyword_difficulty`, `ahrefs_keyword_difficulty`, `intent` (uma linha por `keyword`) | | `keyword_ideas` | `items[]`: mesma linha que `keyword_overview` | | `serp` | `items[]`: `position`, `url`, `domain`, `title`, `snippet` (`results` orgânico somente) | | `domain_overview` | `organic_keywords`, `organic_traffic`, `organic_traffic_value_usd`, `paid_keywords`, `paid_traffic` | | `ranked_keywords` | `items[]`: `keyword`, `position`, `url`, `volume`, `cpc_usd`, `traffic` | | `organic_competitors` | `items[]`: `domain`, `common_keywords`, `organic_keywords` (`total` do concorrente), `organic_traffic`. O `domain` de destino e seus subdomínios são excluídos. | | `backlinks_overview` | `backlinks`, `referring_domains`, `semrush_authority_score`, `dataforseo_rank`, `serpstat_domain_rank`, `dofollow_backlinks`, `nofollow_backlinks` | | `backlinks` | `items[]`: `source_url`, `target_url`, `anchor`, `source_ahrefs_domain_rating`, `source_semrush_authority_score`, `source_dataforseo_rank`, `dofollow`, `first_seen_at`. Uma linha por link de cada Provedor. | | `referring_domains` | `items[]`: `domain`, `ahrefs_domain_rating`, `semrush_authority_score`, `dataforseo_rank`, `backlinks`, `dofollow_backlinks`, `first_seen_at` | | `domain_rating` | `ahrefs_domain_rating` | | `site_audit` | `dataforseo_task_id` (`input` para os Endpoints do relatório OnPage da DataForSEO), `crawl_progress`, `crawl_stop_reason` (vocabulário da DataForSEO), `pages_crawled`, `dataforseo_onpage_score`, `broken_links`, `non_indexable`, `duplicate_title`, `duplicate_description`, `duplicate_content` | | `keyword_gap` | `items[]`: `keyword`, `volume`, `cpc_usd`, `semrush_keyword_difficulty`, `dataforseo_keyword_difficulty`, `positions` `{domain: position}` (`null` = não está entre os 100 primeiros), indexados pelos domínios enviados por você | | `backlink_gap` | `items[]`: `domain`, `dataforseo_rank`, `backlinks_per_target` `{competitor domain: count}` | | `page_audit` | `url`, `status_code`, `title`, `description`, `canonical`, `dataforseo_onpage_score`, `internal_links`, `external_links` | | `visibility_history` | `items[]`: `month`, `organic_keywords`, `organic_traffic`, `organic_traffic_value_usd`, `paid_keywords`, `paid_traffic` | | `ai_citations` | `items[]`: `url`, `platform`, `mentions`, `ai_search_volume`, `is_target_domain`. Páginas mais citadas em respostas de IA que mencionam o `domain`, de qualquer site. | | `ai_visibility` | `ahrefs_ai_citations`, `ahrefs_ai_cited_pages`, `ahrefs_ai_citations_by_platform` `{platform: citations}`, `dataforseo_ai_mentions_by_platform` `{platform: mentions}`, `dataforseo_ai_search_volume_by_platform` `{platform: AI search volume}` | As linhas de `keyword_gap` diferem conforme o Provedor: a Semrush retorna palavras-chave para as quais qualquer um dos domínios aparece no ranking (uma união), enquanto a DataForSEO retorna palavras-chave para as quais o concorrente aparece no ranking e você não. `ai_visibility` informa duas métricas diferentes: a Ahrefs contabiliza citações das páginas do domínio em respostas de IA, enquanto a DataForSEO contabiliza menções do domínio por LLMs. Cada Provedor preenche somente seus próprios campos, e não há um total entre Provedores. O `first_seen_at` da Semrush não contém fuso horário (a Semrush não informa nenhum), portanto não possui o sufixo `Z`. ```json { "action": "ranked_keywords", "provider": "dataforseo", "status": "COMPLETED", "result_status": "success", "output": { "items": [ { "keyword": "zero interest business loan", "position": 1, "url": "https://stripe.com/resources/more/zero-interest-business-loans", "volume": 1600, "cpc_usd": 14.54, "traffic": 486.4 } ] }, "charge_usd": "0.01236", "runs": [{ "provider": "dataforseo", "status": "COMPLETED", "charge_usd": "0.01236" }], "result_url": "/v1/solutions/gtm/seo_research/result?token=…" } ``` ## OpenAPI ````yaml /openapi.pt.json post /v1/solutions/gtm/seo_research openapi: 3.1.0 info: title: Glasser version: 0.0.1 description: >- Uma chave, sem contrato, pagamento por chamada, para todas as APIs pagas adquiridas no atacado. Cada resposta contém x-request-id; cada corpo de erro contém o mesmo envelope. servers: - url: https://api.glasser.ai security: [] tags: - name: Solutions - name: Endpoints - name: Runs - name: Balance paths: /v1/solutions/gtm/seo_research: post: tags: - Solutions summary: Pesquisa de SEO description: >- Pesquise volume e dificuldade de palavras-chave, posições nos resultados, backlinks, lacunas de palavras-chave e backlinks em relação aos concorrentes, histórico de posições, rastreamentos de sites, verificações de páginas individuais e citações em respostas de IA. Escolha uma ação e forneça palavras-chave, um domínio ou uma URL de página. Toda ação retorna uma saída normalizada com o id, o provedor de dados e o status do ciclo de vida do último Run. As ações de lista (keyword_ideas, serp, ranked_keywords, organic_competitors, backlinks, referring_domains, keyword_gap, backlink_gap, visibility_history, ai_citations e keyword_overview com uma linha por palavra-chave) expõem output.items[] com campos fixos por linha; as ações de visão geral (domain_overview, backlinks_overview, domain_rating, ai_visibility, page_audit, site_audit) expõem campos fixos no nível superior. A saída nativa do provedor de dados não é repetida em output; ela permanece no Run e pode ser lida com GET /v1/runs/:id. Um valor que o provedor de dados selecionado não informa é null. Os valores são as próprias métricas do provedor de dados que responde (volume, tráfego e cpc são estimativas dele; compare-os apenas dentro de um mesmo provedor de dados). As pontuações do modelo próprio de um provedor de dados mantêm o nome desse provedor de dados, como ahrefs_domain_rating ou semrush_keyword_difficulty, e nunca são convertidas entre provedores de dados. Os valores monetários são sempre USD. Leia result_status separadamente de status: success, no_result, error ou pending. COMPLETED significa que o Run final foi concluído com uma resposta de um provedor de dados; uma resposta vazia, mas válida, é no_result e mantém o formato da ação (items é [], ou todos os campos são null). output é null em caso de erro ou enquanto estiver pending. charge_usd é a cobrança total dos Runs desta resposta, incluindo resultados vazios e falhas cobrados, e é null até que todos os Runs listados sejam concluídos. runs[] contém a cobrança e o charge_basis de cada Run, sem os corpos; um total de vários Runs tem charge_basis=null. GET /v1/runs/:id continua nativo, com a cobrança individual. provider=auto seleciona o primeiro provedor de dados elegível e tenta o próximo somente em PROVIDER_ERROR, TIMED_OUT ou 503 na admissão. Runs sem resultado e em andamento não acionam o fallback. Um provedor de dados nomeado nunca usa fallback. Cada fallback admitido é um Run separado; use task_id para encontrar os Runs relacionados. Para QUEUED/RUNNING (HTTP 202, atualmente apenas site_audit), consulte a result_url autenticada na origem da API. Essa leitura retorna o mesmo contrato normalizado e o total, não cria Runs e não retoma o fallback. Reutilize a mesma Idempotency-Key e os mesmos parâmetros de execução para uma nova tentativa intencional. operationId: gtm-seo-research parameters: - name: idempotency-key in: header schema: type: string minLength: 1 description: >- Gere um valor exclusivo para cada execução pretendida (recomenda-se um UUID). Tente novamente com a mesma chave e os mesmos parâmetros de execução para recuperar o Run original sem uma segunda cobrança. Alterar os parâmetros de execução com a mesma chave retorna 409; alterar task_id ou metadata não atualiza o Run original. required: true requestBody: content: application/json: schema: type: object properties: use_case: anyOf: - type: string description: >- Uma breve descrição desta tarefa de SEO, incluindo seu assunto. Com task_id, salva a descrição do Task para revisar os resultados e avaliar se atendem à solicitação. Inclua apenas informações relevantes para esta tarefa, não o histórico da conversa nem detalhes pessoais não relacionados. Omita em chamadas posteriores para manter a descrição salva. - type: 'null' action: anyOf: - type: string enum: - keyword_overview - keyword_ideas - serp - domain_overview - ranked_keywords - organic_competitors - backlinks_overview - backlinks - referring_domains - domain_rating - site_audit - ai_visibility - keyword_gap - backlink_gap - page_audit - visibility_history - ai_citations description: >- Padrão: keyword_overview. - keyword_overview: forneça uma ou mais palavras-chave. - keyword_ideas ou serp: forneça exatamente uma palavra-chave em keywords. - site_audit: forneça o domínio; limit é o número de páginas a rastrear (padrão 20, no máximo 100). O rastreamento é executado de forma assíncrona. - keyword_gap e backlink_gap: forneça o domínio e de um a quatro concorrentes. - page_audit: forneça url (uma página). - visibility_history: forneça o domínio; limit é o número de meses (padrão 12, no máximo 24). - Todas as outras ações: forneça o domínio. organic_competitors encontra domínios classificados para as mesmas palavras-chave; ai_visibility: visibilidade nas respostas de IA na métrica própria do provedor de dados que responde (Ahrefs: citações das páginas do domínio; DataForSEO: menções do domínio por LLM); ai_citations: páginas mais citadas em respostas de IA que mencionam o domínio, de qualquer site. - As linhas de keyword_gap variam conforme o provedor de dados: o Semrush retorna palavras-chave para as quais qualquer um dos domínios está classificado (união); o DataForSEO retorna palavras-chave para as quais o concorrente está classificado e você não está. - type: 'null' provider: anyOf: - type: string enum: - auto - semrush - serpstat - dataforseo - ahrefs - serper description: >- Padrão auto: seleciona o primeiro provedor de dados elegível na ordem de preferência da Glasser. Um provedor de dados nomeado deve aceitar a solicitação e ser permitido pela sua Key; não há fallback para outro provedor de dados. Os valores disponíveis estão listados abaixo. - type: 'null' keywords: anyOf: - type: array items: type: string minLength: 1 maxLength: 200 minItems: 1 maxItems: 20 - type: 'null' domain: anyOf: - type: string minLength: 3 maxLength: 253 description: >- Um domínio de site, como stripe.com. Uma URL completa é aceita e reduzida ao host. - type: 'null' competitors: anyOf: - type: array items: type: string minLength: 3 maxLength: 253 description: >- Um domínio de site, como stripe.com. Uma URL completa é aceita e reduzida ao host. minItems: 1 maxItems: 4 description: >- Domínios concorrentes para keyword_gap e backlink_gap, de um a quatro. URLs completas são reduzidas ao host. - type: 'null' url: anyOf: - type: string minLength: 1 maxLength: 2048 description: >- Uma URL de página para page_audit, como https://stripe.com/pricing. - type: 'null' country: anyOf: - type: string minLength: 2 maxLength: 60 description: >- País como código ISO de duas letras ou nome do país, por exemplo, us, gb, de, Germany. Padrão us. Códigos de país compatíveis: us, gb, ca, au, nz, ie, in, sg, de, at, ch, fr, be, es, mx, ar, it, nl, pt, br, jp, kr, cn, hk, tw, ru, pl, se, no, dk, fi, tr, id, th, vn, ph, my, za, ae, il, sa, eg, ng, ua, cz, gr, hu, ro, co, cl, pe, lu. A disponibilidade também depende da ação e do provedor de dados. Um país não compatível é recusado antes da criação de um Run. Não altere o país para contornar um erro; isso altera os dados solicitados. - type: 'null' limit: anyOf: - type: integer minimum: 1 maximum: 100 description: >- Linhas a retornar. Mantenha um número pequeno: a regra de cobrança do endpoint roteado pode ler esse valor. Cada capacidade pode limitá-lo ainda mais. - type: 'null' task_id: anyOf: - type: string description: >- Agrupe Runs relacionados, incluindo o fallback automático, em um único Task. Reutilize uma string estável e filtre a lista de Runs por task para recuperá-los. - type: 'null' metadata: anyOf: - anyOf: - type: object additionalProperties: type: string minLength: 1 maxLength: 500 maxProperties: 20 propertyNames: type: string pattern: ^[a-z][a-z0-9_]{0,39}$ - {} description: >- Campos opcionais de acompanhamento, retornados no Run e disponíveis como filtros. Eles nunca são enviados ao provedor de dados nem afetam o roteamento, o Price ou a idempotência. - Até 20 chaves: letras minúsculas, dígitos e sublinhados; comece com uma letra; no máximo 40 caracteres. - Valores: strings de 1–500 caracteres. - user_id: o ID opaco do seu usuário final, nunca o endereço de e-mail ou o nome dele. Entradas inválidas são descartadas por inteiro, não truncadas. A solicitação continua, e o Run retorna os campos que foram armazenados. - type: 'null' additionalProperties: false required: true responses: '200': description: Success content: application/json: schema: anyOf: - $ref: '#/components/schemas/SeoResearchResult' '202': description: Success content: application/json: schema: anyOf: - $ref: '#/components/schemas/SeoResearchResult' '400': description: ValidationFailed | IdempotencyKeyRequired content: application/json: schema: anyOf: - $ref: '#/components/schemas/ValidationFailedEncoded' - $ref: '#/components/schemas/IdempotencyKeyRequiredEncoded' - $ref: '#/components/schemas/ValidationFailedEncoded' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/UnauthorizedEncoded' '402': description: InsufficientBalance content: application/json: schema: $ref: '#/components/schemas/InsufficientBalanceEncoded' '403': description: EndpointNotPermitted | Forbidden content: application/json: schema: anyOf: - $ref: '#/components/schemas/EndpointNotPermittedEncoded' - $ref: '#/components/schemas/ForbiddenEncoded' '409': description: IdempotencyConflict content: application/json: schema: $ref: '#/components/schemas/IdempotencyConflictEncoded' '429': description: RateLimited content: application/json: schema: $ref: '#/components/schemas/RateLimitedEncoded' '503': description: ServiceUnavailable content: application/json: schema: $ref: '#/components/schemas/ServiceUnavailableEncoded' security: - bearer: [] components: schemas: SeoResearchResult: type: object properties: id: type: string run_url: type: string description: Abra este Run no console. Requer associação ao Workspace. provider: type: string pattern: ^[a-z0-9][a-z0-9-]*$ endpoint: type: string pattern: ^\/.+$ endpoint_version: type: integer exclusiveMinimum: 0 status: type: string enum: - QUEUED - RUNNING - COMPLETED - FAILED - STOPPED description: >- QUEUED ou RUNNING: ainda em andamento. COMPLETED: uma resposta do provedor de dados está disponível, incluindo respostas não 2xx. FAILED: consulte `failure`. STOPPED: interrompido antes do dispatch. Leia charge_usd separadamente de status. failure: anyOf: - type: object properties: kind: type: string enum: - TIMED_OUT - INTERNAL message: type: string required: - kind - message additionalProperties: false - type: 'null' description: Motivo da falha do Run. Não nulo somente quando o status for FAILED. input: type: object output: anyOf: - anyOf: - type: object properties: items: type: array items: type: object properties: keyword: anyOf: - type: string - type: 'null' volume: anyOf: - type: integer - type: 'null' cpc_usd: anyOf: - anyOf: - type: number - type: string enum: - Infinity - '-Infinity' - NaN - type: 'null' semrush_keyword_difficulty: anyOf: - type: integer - type: 'null' serpstat_keyword_difficulty: anyOf: - type: integer - type: 'null' dataforseo_keyword_difficulty: anyOf: - type: integer - type: 'null' ahrefs_keyword_difficulty: anyOf: - type: integer - type: 'null' intent: anyOf: - type: string - type: 'null' required: - keyword - volume - cpc_usd - semrush_keyword_difficulty - serpstat_keyword_difficulty - dataforseo_keyword_difficulty - ahrefs_keyword_difficulty - intent additionalProperties: false required: - items additionalProperties: false - type: object properties: items: type: array items: type: object properties: position: anyOf: - type: integer - type: 'null' url: anyOf: - type: string - type: 'null' domain: anyOf: - type: string - type: 'null' title: anyOf: - type: string - type: 'null' snippet: anyOf: - type: string - type: 'null' required: - position - url - domain - title - snippet additionalProperties: false required: - items additionalProperties: false - type: object properties: organic_keywords: anyOf: - type: integer - type: 'null' organic_traffic: anyOf: - anyOf: - type: number - type: string enum: - Infinity - '-Infinity' - NaN - type: 'null' organic_traffic_value_usd: anyOf: - anyOf: - type: number - type: string enum: - Infinity - '-Infinity' - NaN - type: 'null' paid_keywords: anyOf: - type: integer - type: 'null' paid_traffic: anyOf: - anyOf: - type: number - type: string enum: - Infinity - '-Infinity' - NaN - type: 'null' required: - organic_keywords - organic_traffic - organic_traffic_value_usd - paid_keywords - paid_traffic additionalProperties: false - type: object properties: items: type: array items: type: object properties: keyword: anyOf: - type: string - type: 'null' position: anyOf: - type: integer - type: 'null' url: anyOf: - type: string - type: 'null' volume: anyOf: - type: integer - type: 'null' cpc_usd: anyOf: - anyOf: - type: number - type: string enum: - Infinity - '-Infinity' - NaN - type: 'null' traffic: anyOf: - anyOf: - type: number - type: string enum: - Infinity - '-Infinity' - NaN - type: 'null' required: - keyword - position - url - volume - cpc_usd - traffic additionalProperties: false required: - items additionalProperties: false - type: object properties: items: type: array items: type: object properties: domain: anyOf: - type: string - type: 'null' common_keywords: anyOf: - type: integer - type: 'null' organic_keywords: anyOf: - type: integer - type: 'null' organic_traffic: anyOf: - anyOf: - type: number - type: string enum: - Infinity - '-Infinity' - NaN - type: 'null' required: - domain - common_keywords - organic_keywords - organic_traffic additionalProperties: false required: - items additionalProperties: false - type: object properties: backlinks: anyOf: - type: integer - type: 'null' referring_domains: anyOf: - type: integer - type: 'null' semrush_authority_score: anyOf: - type: integer - type: 'null' dataforseo_rank: anyOf: - type: integer - type: 'null' serpstat_domain_rank: anyOf: - type: integer - type: 'null' dofollow_backlinks: anyOf: - type: integer - type: 'null' nofollow_backlinks: anyOf: - type: integer - type: 'null' required: - backlinks - referring_domains - semrush_authority_score - dataforseo_rank - serpstat_domain_rank - dofollow_backlinks - nofollow_backlinks additionalProperties: false - type: object properties: items: type: array items: type: object properties: source_url: anyOf: - type: string - type: 'null' target_url: anyOf: - type: string - type: 'null' anchor: anyOf: - type: string - type: 'null' source_ahrefs_domain_rating: anyOf: - anyOf: - type: number - type: string enum: - Infinity - '-Infinity' - NaN - type: 'null' source_semrush_authority_score: anyOf: - type: integer - type: 'null' source_dataforseo_rank: anyOf: - type: integer - type: 'null' dofollow: anyOf: - type: boolean - type: 'null' first_seen_at: anyOf: - type: string - type: 'null' required: - source_url - target_url - anchor - source_ahrefs_domain_rating - source_semrush_authority_score - source_dataforseo_rank - dofollow - first_seen_at additionalProperties: false required: - items additionalProperties: false - type: object properties: items: type: array items: type: object properties: domain: anyOf: - type: string - type: 'null' ahrefs_domain_rating: anyOf: - anyOf: - type: number - type: string enum: - Infinity - '-Infinity' - NaN - type: 'null' semrush_authority_score: anyOf: - type: integer - type: 'null' dataforseo_rank: anyOf: - type: integer - type: 'null' backlinks: anyOf: - type: integer - type: 'null' dofollow_backlinks: anyOf: - type: integer - type: 'null' first_seen_at: anyOf: - type: string - type: 'null' required: - domain - ahrefs_domain_rating - semrush_authority_score - dataforseo_rank - backlinks - dofollow_backlinks - first_seen_at additionalProperties: false required: - items additionalProperties: false - type: object properties: ahrefs_domain_rating: anyOf: - anyOf: - type: number - type: string enum: - Infinity - '-Infinity' - NaN - type: 'null' required: - ahrefs_domain_rating additionalProperties: false - type: object properties: dataforseo_task_id: anyOf: - type: string - type: 'null' crawl_progress: anyOf: - type: string - type: 'null' crawl_stop_reason: anyOf: - type: string - type: 'null' pages_crawled: anyOf: - type: integer - type: 'null' dataforseo_onpage_score: anyOf: - anyOf: - type: number - type: string enum: - Infinity - '-Infinity' - NaN - type: 'null' broken_links: anyOf: - type: integer - type: 'null' non_indexable: anyOf: - type: integer - type: 'null' duplicate_title: anyOf: - type: integer - type: 'null' duplicate_description: anyOf: - type: integer - type: 'null' duplicate_content: anyOf: - type: integer - type: 'null' required: - dataforseo_task_id - crawl_progress - crawl_stop_reason - pages_crawled - dataforseo_onpage_score - broken_links - non_indexable - duplicate_title - duplicate_description - duplicate_content additionalProperties: false - type: object properties: items: type: array items: type: object properties: keyword: anyOf: - type: string - type: 'null' volume: anyOf: - type: integer - type: 'null' cpc_usd: anyOf: - anyOf: - type: number - type: string enum: - Infinity - '-Infinity' - NaN - type: 'null' semrush_keyword_difficulty: anyOf: - type: integer - type: 'null' dataforseo_keyword_difficulty: anyOf: - type: integer - type: 'null' positions: type: object additionalProperties: anyOf: - type: integer - type: 'null' required: - keyword - volume - cpc_usd - semrush_keyword_difficulty - dataforseo_keyword_difficulty - positions additionalProperties: false required: - items additionalProperties: false - type: object properties: items: type: array items: type: object properties: domain: anyOf: - type: string - type: 'null' dataforseo_rank: anyOf: - type: integer - type: 'null' backlinks_per_target: type: object additionalProperties: anyOf: - type: integer - type: 'null' required: - domain - dataforseo_rank - backlinks_per_target additionalProperties: false required: - items additionalProperties: false - type: object properties: url: anyOf: - type: string - type: 'null' status_code: anyOf: - type: integer - type: 'null' title: anyOf: - type: string - type: 'null' description: anyOf: - type: string - type: 'null' canonical: anyOf: - type: string - type: 'null' dataforseo_onpage_score: anyOf: - anyOf: - type: number - type: string enum: - Infinity - '-Infinity' - NaN - type: 'null' internal_links: anyOf: - type: integer - type: 'null' external_links: anyOf: - type: integer - type: 'null' required: - url - status_code - title - description - canonical - dataforseo_onpage_score - internal_links - external_links additionalProperties: false - type: object properties: items: type: array items: type: object properties: month: anyOf: - type: string - type: 'null' organic_keywords: anyOf: - type: integer - type: 'null' organic_traffic: anyOf: - anyOf: - type: number - type: string enum: - Infinity - '-Infinity' - NaN - type: 'null' organic_traffic_value_usd: anyOf: - anyOf: - type: number - type: string enum: - Infinity - '-Infinity' - NaN - type: 'null' paid_keywords: anyOf: - type: integer - type: 'null' paid_traffic: anyOf: - anyOf: - type: number - type: string enum: - Infinity - '-Infinity' - NaN - type: 'null' required: - month - organic_keywords - organic_traffic - organic_traffic_value_usd - paid_keywords - paid_traffic additionalProperties: false required: - items additionalProperties: false - type: object properties: items: type: array items: type: object properties: url: anyOf: - type: string - type: 'null' platform: anyOf: - type: string - type: 'null' mentions: anyOf: - type: integer - type: 'null' ai_search_volume: anyOf: - type: integer - type: 'null' is_target_domain: anyOf: - type: boolean - type: 'null' required: - url - platform - mentions - ai_search_volume - is_target_domain additionalProperties: false required: - items additionalProperties: false - type: object properties: ahrefs_ai_citations: anyOf: - type: integer - type: 'null' ahrefs_ai_cited_pages: anyOf: - type: integer - type: 'null' ahrefs_ai_citations_by_platform: anyOf: - type: object additionalProperties: anyOf: - type: integer - type: 'null' - type: 'null' dataforseo_ai_mentions_by_platform: anyOf: - type: object additionalProperties: anyOf: - type: integer - type: 'null' - type: 'null' dataforseo_ai_search_volume_by_platform: anyOf: - type: object additionalProperties: anyOf: - type: integer - type: 'null' - type: 'null' required: - ahrefs_ai_citations - ahrefs_ai_cited_pages - ahrefs_ai_citations_by_platform - dataforseo_ai_mentions_by_platform - dataforseo_ai_search_volume_by_platform additionalProperties: false - type: 'null' description: >- Campos normalizados por ação. A saída nativa do provedor de dados não é repetida aqui; ela permanece no Run (GET /v1/runs/:id). Os valores que um provedor de dados não informar serão nulos. Valores monetários estão em USD. As pontuações de autoridade mantêm a métrica e o nome próprios do provedor de dados que respondeu e nunca são convertidas: ahrefs_domain_rating (Ahrefs Domain Rating, 0–100), semrush_authority_score (Semrush Authority Score, 0–100), dataforseo_rank (classificação da DataForSEO, 0–1000), serpstat_domain_rank (Serpstat Domain Rank, 0–100). A dificuldade de palavras-chave é dividida da mesma forma (semrush_keyword_difficulty, serpstat_keyword_difficulty, dataforseo_keyword_difficulty, ahrefs_keyword_difficulty, cada uma de 0–100 em seu próprio modelo). Somente o campo do provedor de dados que respondeu é preenchido; os demais são nulos. volume, traffic e cpc são estimativas do provedor de dados que respondeu; compare-as somente dentro de um mesmo provedor de dados (runs[].provider). Uma resposta vazia (result_status no_result) mantém o formato da ação: items é [], ou todos os campos são nulos. - keyword_overview: items[]: keyword, volume, cpc_usd, semrush_keyword_difficulty, serpstat_keyword_difficulty, dataforseo_keyword_difficulty, ahrefs_keyword_difficulty, intent - keyword_ideas: items[]: mesma linha de keyword_overview - serp: items[]: position (posição orgânica: 1 = primeiro resultado orgânico; recursos da SERP não são contabilizados), url, domain, title, snippet (somente resultados orgânicos) - domain_overview: organic_keywords, organic_traffic, organic_traffic_value_usd, paid_keywords, paid_traffic - ranked_keywords: items[]: keyword, position (posição orgânica: 1 = primeiro resultado orgânico; recursos da SERP não são contabilizados), url, volume, cpc_usd, traffic - organic_competitors: items[]: domain, common_keywords, organic_keywords (total do concorrente), organic_traffic (o domínio-alvo e seus subdomínios são excluídos) - backlinks_overview: backlinks, referring_domains, semrush_authority_score, dataforseo_rank, serpstat_domain_rank, dofollow_backlinks, nofollow_backlinks - backlinks: items[]: source_url, target_url, anchor, source_ahrefs_domain_rating, source_semrush_authority_score, source_dataforseo_rank, dofollow, first_seen_at (ISO 8601 UTC; Semrush: fuso não informado, sem sufixo Z). Uma linha por link de cada provedor de dados - referring_domains: items[]: domain, ahrefs_domain_rating, semrush_authority_score, dataforseo_rank, backlinks, dofollow_backlinks, first_seen_at (ISO 8601 UTC; Semrush: fuso não informado, sem sufixo Z) - domain_rating: ahrefs_domain_rating - site_audit: dataforseo_task_id (entrada para os endpoints de relatório OnPage da DataForSEO), crawl_progress, crawl_stop_reason (vocabulário da DataForSEO), pages_crawled, dataforseo_onpage_score, broken_links, non_indexable, duplicate_title, duplicate_description, duplicate_content - keyword_gap: items[]: keyword, volume, cpc_usd, semrush_keyword_difficulty, dataforseo_keyword_difficulty, positions `{domain: posição orgânica; null = não está entre os 100 primeiros}`, indexado pelos domínios enviados. As linhas da Semrush são palavras-chave para as quais qualquer um dos domínios está classificado (união); as linhas da DataForSEO são palavras-chave para as quais o concorrente está classificado e você não - backlink_gap: items[]: domain, dataforseo_rank, backlinks_per_target `{domínio concorrente: contagem}` - page_audit: url, status_code, title, description, canonical, dataforseo_onpage_score, internal_links, external_links - visibility_history: items[]: month, organic_keywords, organic_traffic, organic_traffic_value_usd, paid_keywords, paid_traffic - ai_citations: items[]: url, platform, mentions, ai_search_volume, is_target_domain (páginas mais citadas em respostas de IA que mencionam o domínio, de qualquer site) - ai_visibility: ahrefs_ai_citations, ahrefs_ai_cited_pages, ahrefs_ai_citations_by_platform `{platform: citations}`, dataforseo_ai_mentions_by_platform `{platform: mentions}`, dataforseo_ai_search_volume_by_platform `{platform: volume de pesquisa de IA}`. Cada provedor de dados preenche somente seus próprios campos; não há total entre provedores provider_response: anyOf: - type: object properties: http_status: type: integer minimum: 100 maximum: 599 description: >- Status HTTP retornado pelo provedor de dados. Verifique-o mesmo quando o Run estiver COMPLETED. error: anyOf: - {} - type: 'null' required: - http_status additionalProperties: false - type: 'null' description: >- Não nulo somente quando o status for COMPLETED. - Para respostas 2xx, output contém o JSON nativo do provedor de dados (qualquer formato) ou null para um corpo vazio. - Para respostas não 2xx, error contém o corpo de erro do provedor de dados e output é null. Os campos confidenciais são removidos de ambos os corpos. charge_usd: anyOf: - type: string pattern: ^(0|[1-9]\d*)\.(\d{2}|\d{2}\d{0,3}[1-9])$ description: >- String decimal exata em USD (mínimo de 2 e máximo de 6 casas decimais, com uma única grafia canônica). Some usando aritmética decimal ou multiplique por 10^6 — nunca use números de ponto flutuante. - type: 'null' description: >- Cobrança total dos Runs nesta resposta de Solution. Nulo até que todos os Runs listados sejam finalizados. Cada Run mantém sua própria cobrança; falhas também podem ser cobradas. charge_basis: anyOf: - type: object properties: clause: type: string enum: - rule - NO_RESULT - PROVIDER_ERROR - TIMED_OUT - INTERNAL quantity: anyOf: - type: integer minimum: 0 - type: 'null' required: - clause - quantity additionalProperties: false - type: 'null' description: >- Base de cobrança de um único Run ou nulo para um total de vários Runs. Leia runs[].charge_basis para cada cobrança. stoppable: type: boolean description: >- Indica se uma solicitação de parada pode ser aceita no momento. Isso não garante que o Run possa ser interrompido antes do dispatch. stop_requested_at: anyOf: - type: string description: Timestamp UTC no formato ISO-8601 format: date-time - type: 'null' description: >- Quando uma parada foi solicitada. O Run ainda pode continuar se o dispatch já tiver começado. created_at: type: string description: Timestamp UTC no formato ISO-8601 format: date-time started_at: anyOf: - type: string description: Timestamp UTC no formato ISO-8601 format: date-time - type: 'null' completed_at: anyOf: - type: string description: Timestamp UTC no formato ISO-8601 format: date-time - type: 'null' task_id: anyOf: - type: string - type: 'null' metadata: type: object additionalProperties: type: string minLength: 1 maxLength: 500 maxProperties: 20 propertyNames: type: string pattern: ^[a-z][a-z0-9_]{0,39}$ description: >- Seus campos de rastreamento armazenados. Use-os para filtrar Runs. Eles nunca são enviados ao provedor de dados nem afetam o roteamento, o Price ou a idempotência. - Até 20 chaves: letras minúsculas, dígitos e sublinhados; devem começar com uma letra; no máximo 40 caracteres. - Valores: strings de 1 a 500 caracteres. - user_id: o ID opaco do seu usuário final, nunca o endereço de e-mail ou o nome dele. action: type: string enum: - keyword_overview - keyword_ideas - serp - domain_overview - ranked_keywords - organic_competitors - backlinks_overview - backlinks - referring_domains - domain_rating - site_audit - ai_visibility - keyword_gap - backlink_gap - page_audit - visibility_history - ai_citations result_status: type: string enum: - success - no_result - error - pending description: >- Status de entrega comercial, independente do ciclo de vida final do Run em status. no_result é uma resposta vazia, mas válida; error significa que não foi possível entregar a saída do provedor de dados. error: anyOf: - type: object properties: code: type: string message: type: string required: - code - message additionalProperties: false - type: 'null' runs: type: array items: type: object properties: id: type: string run_url: type: string description: Abra este Run no console. Requer associação ao Workspace. provider: type: string pattern: ^[a-z0-9][a-z0-9-]*$ endpoint: type: string pattern: ^\/.+$ endpoint_version: type: integer exclusiveMinimum: 0 status: type: string enum: - QUEUED - RUNNING - COMPLETED - FAILED - STOPPED description: >- QUEUED ou RUNNING: ainda em andamento. COMPLETED: uma resposta do provedor de dados está disponível, incluindo respostas não 2xx. FAILED: consulte `failure`. STOPPED: interrompido antes do despacho. Leia charge_usd separadamente de status. failure: anyOf: - type: object properties: kind: type: string enum: - TIMED_OUT - INTERNAL message: type: string required: - kind - message additionalProperties: false - type: 'null' description: >- Motivo da falha do Run. Não nulo somente quando status é FAILED. input: type: object properties: omitted: type: boolean enum: - true required: - omitted additionalProperties: false output: type: object properties: omitted: type: boolean enum: - true required: - omitted additionalProperties: false provider_response: anyOf: - type: object properties: http_status: type: integer minimum: 100 maximum: 599 description: >- Status HTTP retornado pelo provedor de dados. Verifique-o mesmo quando o Run estiver COMPLETED. required: - http_status additionalProperties: false - type: 'null' charge_usd: anyOf: - type: string pattern: ^(0|[1-9]\d*)\.(\d{2}|\d{2}\d{0,3}[1-9])$ description: >- String decimal exata em USD (mínimo de 2 e máximo de 6 casas decimais, com uma única grafia canônica). Some usando aritmética decimal ou multiplique por 10^6 — nunca use números de ponto flutuante. - type: 'null' description: >- Cobrança final como uma string decimal exata em USD. Nulo enquanto estiver QUEUED ou RUNNING. Um Run FAILED pode ter uma cobrança diferente de zero conforme o Price do endpoint. charge_basis: anyOf: - type: object properties: clause: type: string enum: - rule - NO_RESULT - PROVIDER_ERROR - TIMED_OUT - INTERNAL quantity: anyOf: - type: integer minimum: 0 - type: 'null' required: - clause - quantity additionalProperties: false - type: 'null' description: >- Cláusula de Price usada para calcular a cobrança. Nulo antes da liquidação ou quando nenhuma tentativa com o provedor de dados foi feita. stoppable: type: boolean description: >- Indica se uma solicitação de interrupção pode ser aceita atualmente. Isso não garante que o Run possa ser interrompido antes do despacho. stop_requested_at: anyOf: - type: string description: Timestamp UTC no formato ISO-8601 format: date-time - type: 'null' description: >- Quando uma interrupção foi solicitada. O Run ainda pode continuar se o despacho já tiver começado. created_at: type: string description: Timestamp UTC no formato ISO-8601 format: date-time started_at: anyOf: - type: string description: Timestamp UTC no formato ISO-8601 format: date-time - type: 'null' completed_at: anyOf: - type: string description: Timestamp UTC no formato ISO-8601 format: date-time - type: 'null' task_id: anyOf: - type: string - type: 'null' metadata: type: object additionalProperties: type: string minLength: 1 maxLength: 500 maxProperties: 20 propertyNames: type: string pattern: ^[a-z][a-z0-9_]{0,39}$ description: >- Seus campos de rastreamento armazenados. Use-os para filtrar Runs. Eles nunca são enviados ao provedor de dados nem afetam o roteamento, o Price ou a idempotência. - Até 20 chaves: letras minúsculas, dígitos e sublinhados; devem começar com uma letra; no máximo 40 caracteres. - Valores: strings de 1 a 500 caracteres. - user_id: o ID opaco do seu usuário final, nunca o endereço de e-mail ou o nome dele. required: - id - run_url - provider - endpoint - endpoint_version - status - failure - input - output - provider_response - charge_usd - charge_basis - stoppable - stop_requested_at - created_at - started_at - completed_at - task_id - metadata additionalProperties: false result_url: type: string description: >- Caminho de URL autenticado e somente leitura para consultar este resultado normalizado e a cobrança total. Use-o com a origem da API. Não cria Runs nem retoma o fallback. GET /v1/runs/:id ainda retorna o Run individual nativo. required: - id - run_url - provider - endpoint - endpoint_version - status - failure - input - output - provider_response - charge_usd - charge_basis - stoppable - stop_requested_at - created_at - started_at - completed_at - task_id - metadata - action - result_status - error - runs - result_url additionalProperties: false ValidationFailedEncoded: type: object properties: error: type: object properties: code: type: string enum: - validation_failed message: type: string reason: anyOf: - type: string - type: 'null' control: anyOf: - type: string - type: 'null' retry_after_ms: anyOf: - anyOf: - type: integer - type: 'null' - type: 'null' details: anyOf: - type: object - type: 'null' required: - code - message additionalProperties: false request_id: type: string required: - error - request_id additionalProperties: false IdempotencyKeyRequiredEncoded: type: object properties: error: type: object properties: code: type: string enum: - idempotency_key_required message: type: string reason: anyOf: - type: string - type: 'null' control: anyOf: - type: string - type: 'null' retry_after_ms: anyOf: - anyOf: - type: integer - type: 'null' - type: 'null' details: anyOf: - type: object - type: 'null' required: - code - message additionalProperties: false request_id: type: string required: - error - request_id additionalProperties: false UnauthorizedEncoded: type: object properties: error: type: object properties: code: type: string enum: - unauthorized message: type: string reason: anyOf: - type: string - type: 'null' control: anyOf: - type: string - type: 'null' retry_after_ms: anyOf: - anyOf: - type: integer - type: 'null' - type: 'null' details: anyOf: - type: object - type: 'null' required: - code - message additionalProperties: false request_id: type: string required: - error - request_id additionalProperties: false InsufficientBalanceEncoded: type: object properties: error: type: object properties: code: type: string enum: - insufficient_balance message: type: string reason: anyOf: - type: string - type: 'null' control: anyOf: - type: string - type: 'null' retry_after_ms: anyOf: - anyOf: - type: integer - type: 'null' - type: 'null' details: anyOf: - type: object - type: 'null' required: - code - message additionalProperties: false request_id: type: string required: - error - request_id additionalProperties: false EndpointNotPermittedEncoded: type: object properties: error: type: object properties: code: type: string enum: - endpoint_not_permitted message: type: string reason: anyOf: - type: string - type: 'null' control: anyOf: - type: string - type: 'null' retry_after_ms: anyOf: - anyOf: - type: integer - type: 'null' - type: 'null' details: anyOf: - type: object - type: 'null' required: - code - message additionalProperties: false request_id: type: string required: - error - request_id additionalProperties: false ForbiddenEncoded: type: object properties: error: type: object properties: code: type: string enum: - forbidden message: type: string reason: anyOf: - type: string - type: 'null' control: anyOf: - type: string - type: 'null' retry_after_ms: anyOf: - anyOf: - type: integer - type: 'null' - type: 'null' details: anyOf: - type: object - type: 'null' required: - code - message additionalProperties: false request_id: type: string required: - error - request_id additionalProperties: false IdempotencyConflictEncoded: type: object properties: error: type: object properties: code: type: string enum: - idempotency_conflict message: type: string reason: anyOf: - type: string - type: 'null' control: anyOf: - type: string - type: 'null' retry_after_ms: anyOf: - anyOf: - type: integer - type: 'null' - type: 'null' details: anyOf: - type: object - type: 'null' required: - code - message additionalProperties: false request_id: type: string required: - error - request_id additionalProperties: false RateLimitedEncoded: type: object properties: error: type: object properties: code: type: string enum: - rate_limited message: type: string reason: anyOf: - type: string - type: 'null' control: anyOf: - type: string - type: 'null' retry_after_ms: anyOf: - anyOf: - type: integer - type: 'null' - type: 'null' details: anyOf: - type: object - type: 'null' required: - code - message additionalProperties: false request_id: type: string required: - error - request_id additionalProperties: false ServiceUnavailableEncoded: type: object properties: error: type: object properties: code: type: string enum: - service_unavailable message: type: string reason: anyOf: - type: string - type: 'null' control: anyOf: - type: string - type: 'null' retry_after_ms: anyOf: - anyOf: - type: integer - type: 'null' - type: 'null' details: anyOf: - type: object - type: 'null' required: - code - message additionalProperties: false request_id: type: string required: - error - request_id additionalProperties: false securitySchemes: bearer: type: http scheme: Bearer ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.