POST /v1/sync/task.
200 con la tarea en QUEUED:
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.
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 yLocation: /v1/async/task/{id}. Sigue ejecutándose y se cobra como siempre, así que sondea esa dirección o recibe el webhook. Un202tambié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/htmlypayload.include.html: true, una tarea completada se responde con su página guardada comotext/html, yX-Task-Idlleva el id de la tarea. Una tarea fallida, o una cuya página no se pudo guardar, se responde con406y 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.