Saltar al contenido principal
Cada solicitud se guarda como una tarea. La envías, recibes al instante un id de tarea y recoges el resultado más tarde por webhook o mediante sondeo. Si necesitas el resultado en la misma solicitud, envía la tarea a POST /v1/sync/task.
La respuesta del envío es 200 con la tarea en QUEUED:
Sondéala con el id (referencia):

Ciclo de vida

Estados

Una tarea que sufre un fallo transitorio vuelve a QUEUED y se ejecuta de nuevo. Solo queda en FAILED cuando se agotan sus reintentos, así que un paso PROCESSING → QUEUED es normal. El sondeo omite response hasta que la tarea llega a un estado final. Una tarea fallida tiene en su lugar una cadena error de nivel superior:

Créditos al enviar y al sondear

Los precios, las retenciones y los límites están en Créditos y límites.

Tiempo de procesamiento

task.latencyMs es el tiempo que tardó el motor: desde que un worker toma la tarea por primera vez hasta el resultado final, en milisegundos, sin la espera en cola. Si un fallo transitorio la devuelve a la cola, el cómputo sigue desde esa primera toma. Vale null en la respuesta de envío y mientras la tarea está QUEUED o PROCESSING, y es un número en el sondeo final y en el webhook. El encabezado X-Latency-Ms mide otra cosa: el tiempo que este servidor dedicó a esa única solicitud HTTP.

Prioridad

priority acepta de 1 a 10 y por defecto vale 1. Los valores fuera de ese rango se ajustan al rango, no se rechazan. El valor se devuelve en los metadatos de la tarea.
El orden de ejecución no está garantizado por prioridad, hora de envío ni cuenta. Para trabajo dependiente, espera a que la primera tarea se complete antes de enviar la siguiente.

Retención

Puedes sondear una tarea finalizada durante 24 horas tras completarse. Después, GET /v1/async/task/{id} devuelve 404 RESOURCE_NOT_FOUND, la misma respuesta que un id desconocido o una tarea de otra cuenta. Las tareas QUEUED y PROCESSING siguen visibles sea cual sea su antigüedad. La ventana de 24 horas también se aplica a los cuerpos de resultado en GET /v1/batches/{id}/items y en las lecturas de cuadrículas. La idempotencyKey de una tarea sigue reservada más tiempo, durante al menos 30 días después de la solicitud (consulta Idempotencia). Los reintentos automáticos de webhook siguen su propio calendario, independiente de esta ventana.

Esperar el resultado en una sola solicitud

POST /v1/sync/task acepta el mismo cuerpo y mantiene la solicitud abierta hasta que la tarea termina, como máximo 290 segundos. La respuesta es entonces 200 con el mismo cuerpo que el sondeo de la tarea, incluida una tarea fallida. Los motores de respuesta tardan más que las tareas de SERP y Search. Mantén la solicitud abierta según el tipo de motor que llamas, como se agrupa en el catálogo de motores, y pon el timeout de tu cliente HTTP unos segundos por encima:
  • Una tarea que no ha terminado cuando acaba la espera se responde con 202, la tarea y Location: /v1/async/task/{id}. Sigue ejecutándose y se cobra como siempre, así que sondea esa dirección o recibe el webhook. Un 202 también puede llegar al instante mientras el servicio mantiene muchas solicitudes abiertas.
  • Envía Prefer: wait=<segundos> para mantener la solicitud menos de 290 segundos. Quédate por debajo del timeout de tu cliente HTTP, para recibir el id de la tarea antes de que tu cliente deje de esperar.
  • Envía un idempotencyKey. Si envías la misma clave otra vez, la respuesta es la tarea que la tiene, así que puedes repetir una solicitud que expiró de tu lado sin ejecutar la tarea dos veces.
  • Con Accept: text/html y payload.include.html: true, una tarea completada se responde con su página guardada como text/html, y X-Task-Id lleva el id de la tarea. Una tarea fallida, o una cuya página no se pudo guardar, se responde con 406 y el cuerpo JSON.

Webhook o sondeo

Prefiere los webhooks. Usa el sondeo para recuperar lo que no te haya llegado. Un cliente robusto usa ambos: toma el webhook como vía rápida y sondea, con margen dentro de la ventana de 24 horas, cualquier tarea de la que no haya tenido noticia.

Siguientes pasos

Webhooks

Payload, firmas y reintentos.

Lotes y cuadrículas

Envía hasta 10.000 tareas a la vez.