> ## 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. # Investigación SEO > Investiga el volumen y la dificultad de palabras clave, las posiciones en búsquedas, los backlinks, las auditorías de sitios y la visibilidad en respuestas de IA en varios proveedores de datos con un único resultado normalizado. Elige una acción y proporciona palabras clave o un dominio. Cada acción devuelve `output` normalizado. La salida nativa del Provider no se repite allí; permanece en el Run y puede leerse con [Get Run](https://glasser.ai/docs/es/api-reference/runs/get.md). Las acciones de lista exponen `output.items[]` con campos fijos por fila; las acciones de resumen exponen campos fijos de nivel superior. Un valor que el Provider seleccionado no informa es `null`; Glasser no convierte ni completa valores. El dinero siempre está expresado en USD (`cpc_usd`, `organic_traffic_value_usd`). `volume`, `traffic` y `cpc_usd` son estimaciones propias del Provider que responde. Compárelas únicamente dentro de un mismo Provider (`runs[].provider`), no entre Providers. Lea `result_status` por separado de `status`: `success`, `no_result`, `error` o `pending`. Una respuesta vacía pero válida es `no_result` y conserva la estructura de la acción: `items` es `[]`, o todos los campos de nivel superior son `null`. `error` con `error.code` significa que no se pudo entregar la salida del Provider. `charge_usd` suma los `runs` de esta respuesta, incluidos los resultados vacíos cobrados, y es null hasta que todos los Runs finalizan. Con `provider: auto`, el fallback puede crear varios Runs, cada uno enumerado en `runs[]` con su propio cargo. Para un rastreo pendiente (`site_audit`, HTTP 202), siga el [result\_url](https://glasser.ai/docs/es/api-reference/solutions/gtm/seo_research/result.md) autenticado. [Get Run](https://glasser.ai/docs/es/api-reference/runs/get.md) sigue siendo nativo e informa de un cargo individual. Consulte [Provider selection and charges](https://glasser.ai/docs/es/api-reference/solutions/overview.md#how-provider-selection-works). ## Salida por acción Todos los campos están presentes en cada fila; un valor que el Provider no informa es `null`. Los campos siguen las [convenciones de campos](https://glasser.ai/docs/es/api-reference/solutions/overview.md#field-conventions): los importes terminan en `_usd`, las marcas de tiempo terminan en `_at` (ISO 8601 UTC), y `domain` es un nombre de host simple sin `www.` ni puerto. Las puntuaciones de autoridad conservan la métrica y el nombre propios de cada Provider y nunca se convierten: `ahrefs_domain_rating` (Domain Rating de Ahrefs, 0–100, puede tener decimales), `semrush_authority_score` (Authority Score de Semrush, 0–100), `dataforseo_rank` (rango de DataForSEO, 0–1000) y `serpstat_domain_rank` (Domain Rank de Serpstat, 0–100). La dificultad de palabras clave se divide de la misma manera: `semrush_keyword_difficulty`, `serpstat_keyword_difficulty`, `dataforseo_keyword_difficulty` y `ahrefs_keyword_difficulty` están cada una en el rango 0–100 según el modelo propio del Provider, por lo que la misma palabra clave puede obtener puntuaciones muy diferentes entre ellas. `dataforseo_onpage_score` es la puntuación propia de página de DataForSEO. Solo se completa el campo del Provider que respondió; los demás son `null`. `position` es la posición orgánica: 1 es el primer resultado orgánico, y las funciones de SERP, como los anuncios o los cuadros de respuesta, no se cuentan. | `action` | `output` | | - | - | | `keyword_overview` | `items[]`: `keyword`, `volume`, `cpc_usd`, `semrush_keyword_difficulty`, `serpstat_keyword_difficulty`, `dataforseo_keyword_difficulty`, `ahrefs_keyword_difficulty`, `intent` (una fila por `keyword`) | | `keyword_ideas` | `items[]`: misma fila que `keyword_overview` | | `serp` | `items[]`: `position`, `url`, `domain`, `title`, `snippet` (solo `results` orgánico) | | `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` del competidor), `organic_traffic`. Se excluyen el `domain` objetivo y sus subdominios. | | `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`. Una fila por enlace de cada Provider. | | `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` a los Endpoints del informe OnPage de DataForSEO), `crawl_progress`, `crawl_stop_reason` (vocabulario de 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` = no está entre los 100 primeros), identificados por los dominios que envió | | `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 más citadas en respuestas de IA que mencionan el `domain`, de cualquier sitio. | | `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}` | Las filas de `keyword_gap` difieren según el Provider: Semrush devuelve las palabras clave para las que se posiciona cualquiera de los dominios (una unión), mientras que DataForSEO devuelve las palabras clave para las que se posiciona el competidor y usted no. `ai_visibility` informa de dos métricas diferentes: Ahrefs cuenta las citas de las páginas del dominio en respuestas de IA, mientras que DataForSEO cuenta las menciones del dominio en modelos de lenguaje de gran escala. Cada Provider completa únicamente sus propios campos y no existe un total entre Providers. El `first_seen_at` de Semrush no incluye zona horaria (Semrush no especifica ninguna), por lo que no tiene el sufijo `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.es.json post /v1/solutions/gtm/seo_research openapi: 3.1.0 info: title: Glasser version: 0.0.1 description: >- Una API Key, sin contrato, con pago por llamada, para APIs de pago adquiridas al por mayor. Cada respuesta incluye x-request-id; cada cuerpo de error incluye el mismo sobre. 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: Investigación SEO description: >- Investigue el volumen y la dificultad de palabras clave, las posiciones en buscadores, los backlinks, las brechas de palabras clave y backlinks frente a competidores, el historial de posiciones, los rastreos de sitios, las comprobaciones de páginas individuales y las citas en respuestas de IA. Elija una acción y proporcione palabras clave, un dominio o una URL de página. Cada acción devuelve resultados normalizados con el id, el proveedor de datos y el estado del ciclo de vida del último Run. Las acciones de lista (keyword_ideas, serp, ranked_keywords, organic_competitors, backlinks, referring_domains, keyword_gap, backlink_gap, visibility_history, ai_citations y keyword_overview con una fila por palabra clave) exponen output.items[] con campos fijos por fila; las acciones de resumen (domain_overview, backlinks_overview, domain_rating, ai_visibility, page_audit, site_audit) exponen campos fijos en el nivel superior. El resultado nativo del proveedor de datos no se repite en output; permanece en el Run y puede leerse con GET /v1/runs/:id. Un valor que el proveedor de datos seleccionado no informe es null. Los valores son cifras propias del proveedor de datos que responde (volume, traffic y cpc son sus estimaciones; compárelos solo dentro de un mismo proveedor de datos). Las puntuaciones del modelo propio de un proveedor de datos conservan su nombre, como ahrefs_domain_rating o semrush_keyword_difficulty, y nunca se convierten entre proveedores de datos. El dinero siempre se expresa en USD. Lea result_status por separado de status: success, no_result, error o pending. COMPLETED significa que el Run final se completó con una respuesta del proveedor de datos; una respuesta vacía pero válida es no_result y conserva la estructura de la acción (items es [], o todos los campos son null). output es null cuando hay un error o mientras está pending. charge_usd es el cargo total de los Runs de esta respuesta, incluidos los resultados vacíos y errores cobrados, y es null hasta que todos los Runs indicados se hayan completado. runs[] incluye el cargo y charge_basis de cada Run, sin cuerpos; un total de varios Runs tiene charge_basis=null. GET /v1/runs/:id sigue siendo nativo y muestra el cargo individual. provider=auto selecciona el primer proveedor de datos elegible y prueba el siguiente solo ante PROVIDER_ERROR, TIMED_OUT o un 503 durante la admisión. Los Runs sin resultado y en curso no activan el fallback. Un proveedor de datos indicado por nombre nunca hace fallback. Cada fallback admitido es un Run independiente; use task_id para encontrar los Runs relacionados. Para QUEUED/RUNNING (HTTP 202, actualmente solo site_audit), consulte mediante sondeo el result_url autenticado en el origen de la API. Esa lectura devuelve el mismo contrato normalizado y el total, no crea Runs ni reanuda el fallback. Reutilice la misma Idempotency-Key y los mismos parámetros de ejecución para un reintento intencionado. operationId: gtm-seo-research parameters: - name: idempotency-key in: header schema: type: string minLength: 1 description: >- Genere un valor único para cada ejecución prevista (se recomienda un UUID). Reintente con la misma clave y los mismos parámetros de ejecución para recuperar el Run original sin un segundo cargo. Cambiar los parámetros de ejecución con la misma clave devuelve 409; cambiar task_id o metadata no actualiza el Run original. required: true requestBody: content: application/json: schema: type: object properties: use_case: anyOf: - type: string description: >- Una breve descripción de esta tarea de SEO, incluido su tema. Con task_id, guarda la descripción de Task para revisar sus resultados y evaluar si cumplen la solicitud. Incluya solo la información relevante para esta tarea, no el historial de la conversación ni datos personales no relacionados. Omítala en llamadas posteriores para mantener la descripción guardada. - 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: >- Predeterminado: keyword_overview. - keyword_overview: proporciona una o más palabras clave. - keyword_ideas o serp: proporciona exactamente una palabra clave en keywords. - site_audit: proporciona el dominio; limit es el número de páginas que se rastrearán (predeterminado: 20, como máximo 100). El rastreo se ejecuta de forma asíncrona. - keyword_gap y backlink_gap: proporciona el dominio y entre uno y cuatro competidores. - page_audit: proporciona url (una página). - visibility_history: proporciona el dominio; limit es el número de meses (predeterminado: 12, como máximo 24). - Todas las demás acciones: proporciona el dominio. organic_competitors encuentra los dominios que se posicionan para las mismas palabras clave; ai_visibility: visibilidad en respuestas de IA según la métrica propia del proveedor de datos que responde (Ahrefs: citas de las páginas del dominio; DataForSEO: menciones del dominio en LLM); ai_citations: páginas más citadas en respuestas de IA que mencionan el dominio, de cualquier sitio. - Las filas de keyword_gap difieren según el proveedor de datos: Semrush devuelve las palabras clave para las que se posiciona cualquiera de los dominios (unión); DataForSEO devuelve las palabras clave para las que se posiciona el competidor y tú no. - type: 'null' provider: anyOf: - type: string enum: - auto - semrush - serpstat - dataforseo - ahrefs - serper description: >- Predeterminado auto: selecciona el primer proveedor de datos elegible según el orden de preferencia de Glasser. Un proveedor de datos especificado debe admitir la solicitud y estar permitido por tu API Key; no se recurre a otro proveedor de datos. Los valores disponibles se indican a continuación. - 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: >- Un dominio de sitio web, como stripe.com. Se acepta una URL completa y se reduce a su host. - type: 'null' competitors: anyOf: - type: array items: type: string minLength: 3 maxLength: 253 description: >- Un dominio de sitio web, como stripe.com. Se acepta una URL completa y se reduce a su host. minItems: 1 maxItems: 4 description: >- Dominios de competidores para keyword_gap y backlink_gap, entre uno y cuatro. Las URL completas se reducen a su host. - type: 'null' url: anyOf: - type: string minLength: 1 maxLength: 2048 description: >- Una 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 dos letras o nombre del país, p. ej., us, gb, de, Germany. Predeterminado: us. Códigos de país compatibles: 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. La disponibilidad también depende de la acción y del proveedor de datos. Un país no compatible se rechaza antes de crear un Run. No cambies el país para evitar un error; eso modifica los datos solicitados. - type: 'null' limit: anyOf: - type: integer minimum: 1 maximum: 100 description: >- Filas que se devolverán. Mantén un número reducido: la regla de cobro del Endpoint enrutado puede leerlo. Cada capacidad lo limita aún más. - type: 'null' task_id: anyOf: - type: string description: >- Agrupa los Runs relacionados, incluido el fallback automático, en un solo Task. Reutiliza una cadena estable y filtra la lista de Runs por task para recuperarlos. - 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 de seguimiento opcionales, devueltos en el Run y disponibles como filtros. Nunca se envían al proveedor de datos ni afectan al enrutamiento, al Price ni a la idempotencia. - Hasta 20 claves: letras minúsculas, dígitos y guiones bajos; deben comenzar por una letra y tener como máximo 40 caracteres. - Valores: cadenas de entre 1 y 500 caracteres. - user_id: el ID opaco de tu usuario final, nunca su dirección de correo electrónico ni su nombre. Las entradas no válidas se descartan por completo, sin truncarlas. La solicitud continúa y el Run devuelve los campos que se almacenaron. - 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: Abre este Run en la consola. Requiere pertenecer a un 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 o RUNNING: sigue en curso. COMPLETED: hay una respuesta del proveedor de datos disponible, incluidas las respuestas que no son 2xx. FAILED: consulta `failure`. STOPPED: detenido antes del envío. Consulta charge_usd por separado 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 por el que falló el Run. No es null únicamente cuando el estado es 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 acción. El resultado nativo del proveedor de datos no se repite aquí; permanece en el Run (GET /v1/runs/:id). Los valores que un proveedor de datos no informa son null. Los importes monetarios están en USD. Las puntuaciones de autoridad conservan la métrica y el nombre propios del proveedor de datos que responde y nunca se convierten: ahrefs_domain_rating (Ahrefs Domain Rating, 0–100), semrush_authority_score (Semrush Authority Score, 0–100), dataforseo_rank (DataForSEO rank, 0–1000), serpstat_domain_rank (Serpstat Domain Rank, 0–100). La dificultad de palabras clave se divide del mismo modo (semrush_keyword_difficulty, serpstat_keyword_difficulty, dataforseo_keyword_difficulty, ahrefs_keyword_difficulty, cada una de 0–100 según su propio modelo). Solo se completa el campo del proveedor de datos que respondió; los demás son null. volume, traffic y cpc son estimaciones del proveedor de datos que responde; compáralos únicamente dentro de un mismo proveedor de datos (runs[].provider). Una respuesta vacía (result_status no_result) conserva la estructura de la acción: items es [], o todos los campos son null. - keyword_overview: items[]: keyword, volume, cpc_usd, semrush_keyword_difficulty, serpstat_keyword_difficulty, dataforseo_keyword_difficulty, ahrefs_keyword_difficulty, intent - keyword_ideas: items[]: misma fila que keyword_overview - serp: items[]: position (posición orgánica: 1 = primer resultado orgánico; las funciones de SERP no se contabilizan), url, domain, title, snippet (solo resultados orgánicos) - domain_overview: organic_keywords, organic_traffic, organic_traffic_value_usd, paid_keywords, paid_traffic - ranked_keywords: items[]: keyword, position (posición orgánica: 1 = primer resultado orgánico; las funciones de SERP no se contabilizan), url, volume, cpc_usd, traffic - organic_competitors: items[]: domain, common_keywords, organic_keywords (total del competidor), organic_traffic (se excluyen el dominio objetivo y sus subdominios) - 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: zona no indicada, sin sufijo Z). Una fila por enlace de cada proveedor de datos - referring_domains: items[]: domain, ahrefs_domain_rating, semrush_authority_score, dataforseo_rank, backlinks, dofollow_backlinks, first_seen_at (ISO 8601 UTC; Semrush: zona no indicada, sin sufijo Z) - domain_rating: ahrefs_domain_rating - site_audit: dataforseo_task_id (entrada para los endpoints de informes OnPage de DataForSEO), crawl_progress, crawl_stop_reason (vocabulario de 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: posición orgánica; null = no está entre los 100 primeros}`, identificadas por los dominios enviados. Las filas de Semrush son palabras clave para las que posiciona cualquiera de los dominios (unión); las filas de DataForSEO son palabras clave para las que posiciona el competidor y tú no - backlink_gap: items[]: domain, dataforseo_rank, backlinks_per_target `{dominio del competidor: cantidad}` - 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 más citadas en respuestas de IA que mencionan el dominio, de cualquier sitio) - 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: volumen de búsqueda de IA}`. Cada proveedor de datos completa únicamente sus propios campos; no hay un total combinado entre proveedores provider_response: anyOf: - type: object properties: http_status: type: integer minimum: 100 maximum: 599 description: >- Estado HTTP devuelto por el proveedor de datos. Compruébalo incluso cuando el Run esté COMPLETED. error: anyOf: - {} - type: 'null' required: - http_status additionalProperties: false - type: 'null' description: >- No es null únicamente cuando el estado es COMPLETED. - Para respuestas 2xx, output contiene JSON nativo del proveedor de datos (de cualquier estructura), o null si el cuerpo está vacío. - Para respuestas que no son 2xx, error contiene el cuerpo de error del proveedor de datos y output es null. Los campos sensibles se eliminan de ambos cuerpos. charge_usd: anyOf: - type: string pattern: ^(0|[1-9]\d*)\.(\d{2}|\d{2}\d{0,3}[1-9])$ description: >- Cadena decimal exacta en USD (mínimo 2 y máximo 6 decimales, con una única representación canónica). Suma con aritmética decimal o escala por 10^6; nunca uses números de coma flotante. - type: 'null' description: >- Cargo total de los Runs en esta respuesta de Solution. Es null hasta que se liquiden todos los Runs incluidos. Cada Run conserva su propio cargo; los errores también pueden generar cargos. 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 del cargo de un único Run, o null para un total de varios Runs. Consulta runs[].charge_basis para cada cargo. stoppable: type: boolean description: >- Indica si actualmente se puede aceptar una solicitud de detención. Esto no garantiza que el Run pueda detenerse antes del envío. stop_requested_at: anyOf: - type: string description: Marca de tiempo UTC en formato ISO-8601 format: date-time - type: 'null' description: >- Momento en que se solicitó la detención. El Run puede continuar si el envío ya había comenzado. created_at: type: string description: Marca de tiempo UTC en formato ISO-8601 format: date-time started_at: anyOf: - type: string description: Marca de tiempo UTC en formato ISO-8601 format: date-time - type: 'null' completed_at: anyOf: - type: string description: Marca de tiempo UTC en 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: >- Tus campos de seguimiento almacenados. Úsalos para filtrar Runs. Nunca se envían al proveedor de datos ni afectan al enrutamiento, Price o la idempotencia. - Hasta 20 claves: letras minúsculas, dígitos y guiones bajos; deben comenzar por una letra; como máximo 40 caracteres. - Valores: cadenas de 1–500 caracteres. - user_id: el ID opaco de tu usuario final, nunca su dirección de correo electrónico ni su nombre. 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: >- Estado de entrega empresarial, independiente del ciclo de vida final del Run en status. no_result es una respuesta vacía pero válida; error significa que no se pudo entregar el resultado del proveedor de datos. 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: >- Abre este Run en la consola. Requiere pertenencia al 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 o RUNNING: todavía está en curso. COMPLETED: hay una respuesta del proveedor de datos disponible, incluidas las respuestas no-2xx. FAILED: consulta `failure`. STOPPED: detenido antes del envío. Consulta charge_usd por separado 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 por el que falló el Run. Solo es distinto de null cuando status es 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: >- Estado HTTP devuelto por el proveedor de datos. Compruébalo incluso cuando el Run esté 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: >- Cadena decimal exacta en USD (mín. 2 y máx. 6 decimales, con una única representación canónica). Suma mediante aritmética decimal o escala por 10^6; nunca uses números de coma flotante. - type: 'null' description: >- Cargo final como cadena decimal exacta en USD. Es null mientras está QUEUED o RUNNING. Un Run FAILED puede tener un cargo distinto de cero según el Price del 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 utilizada para calcular el cargo. Es null antes de la liquidación o cuando no se realizó ningún intento con el proveedor de datos. stoppable: type: boolean description: >- Indica si actualmente se puede aceptar una solicitud de detención. Esto no garantiza que el Run pueda detenerse antes del envío. stop_requested_at: anyOf: - type: string description: Marca de tiempo UTC ISO-8601 format: date-time - type: 'null' description: >- Momento en que se solicitó la detención. El Run puede continuar si el envío ya había comenzado. created_at: type: string description: Marca de tiempo UTC ISO-8601 format: date-time started_at: anyOf: - type: string description: Marca de tiempo UTC ISO-8601 format: date-time - type: 'null' completed_at: anyOf: - type: string description: Marca de tiempo UTC 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: >- Tus campos de seguimiento almacenados. Úsalos para filtrar Runs. Nunca se envían al proveedor de datos ni afectan al enrutamiento, Price o la idempotencia. - Hasta 20 claves: letras minúsculas, dígitos y guiones bajos; deben comenzar por una letra; como máximo 40 caracteres. - Valores: cadenas de 1–500 caracteres. - user_id: el ID opaco de tu usuario final, nunca su dirección de correo electrónico ni su nombre. 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: >- Ruta URL autenticada y de solo lectura para consultar este resultado normalizado y el cargo total. Úsala con el origen de la API. No crea Runs ni reanuda el fallback. GET /v1/runs/:id sigue devolviendo el 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.