Saltar al contenido principal
POST
Investigación SEO
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. 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 autenticado. Get Run sigue siendo nativo e informa de un cargo individual. Consulte Provider selection and charges.

​
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: 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. 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.

Encabezados

​
idempotency-key
string
requerido

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.

Minimum string length: 1

Cuerpo

application/json
​
use_case
string | null

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.

​
action
enum<string> | null

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.
Opciones disponibles:
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
​
provider
enum<string> | null

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.

Opciones disponibles:
auto,
semrush,
serpstat,
dataforseo,
ahrefs,
serper
​
keywords
string[] | null
Required array length: 1 - 20 elements
Required string length: 1 - 200
​
domain
string | null

Un dominio de sitio web, como stripe.com. Se acepta una URL completa y se reduce a su host.

Required string length: 3 - 253
​
competitors
string[] | null

Dominios de competidores para keyword_gap y backlink_gap, entre uno y cuatro. Las URL completas se reducen a su host.

Required array length: 1 - 4 elements

Un dominio de sitio web, como stripe.com. Se acepta una URL completa y se reduce a su host.

Required string length: 3 - 253
​
url
string | null

Una URL de página para page_audit, como https://stripe.com/pricing.

Required string length: 1 - 2048
​
country
string | null

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.

Required string length: 2 - 60
​
limit
integer | null

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.

Rango requerido: 1 <= x <= 100
​
task_id
string | null

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.

​
metadata

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.

Respuesta

Success

​
id
string
requerido
​
run_url
string
requerido

Abre este Run en la consola. Requiere pertenecer a un Workspace.

​
provider
string
requerido
Pattern: ^[a-z0-9][a-z0-9-]*$
​
endpoint
string
requerido
Pattern: ^\/.+$
​
endpoint_version
integer
requerido
​
status
enum<string>
requerido

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.

Opciones disponibles:
QUEUED,
RUNNING,
COMPLETED,
FAILED,
STOPPED
​
failure
object | null
requerido

Motivo por el que falló el Run. No es null únicamente cuando el estado es FAILED.

​
input
object
requerido
​
output
object
requerido

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
object | null
requerido

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
string | null
requerido

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.

Pattern: ^(0|[1-9]\d*)\.(\d{2}|\d{2}\d{0,3}[1-9])$
​
charge_basis
object | null
requerido

Base del cargo de un único Run, o null para un total de varios Runs. Consulta runs[].charge_basis para cada cargo.

​
stoppable
boolean
requerido

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
string<date-time> | null
requerido

Momento en que se solicitó la detención. El Run puede continuar si el envío ya había comenzado.

​
created_at
string<date-time>
requerido

Marca de tiempo UTC en formato ISO-8601

​
started_at
string<date-time> | null
requerido

Marca de tiempo UTC en formato ISO-8601

​
completed_at
string<date-time> | null
requerido

Marca de tiempo UTC en formato ISO-8601

​
task_id
string | null
requerido
​
metadata
object
requerido

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
enum<string>
requerido
Opciones disponibles:
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
enum<string>
requerido

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.

Opciones disponibles:
success,
no_result,
error,
pending
​
error
object | null
requerido
​
runs
object[]
requerido
​
result_url
string
requerido

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.