Passer au contenu principal
Chaque requête est enregistrée comme une tâche. Vous la soumettez, recevez aussitôt un id de tâche, et récupérez le résultat plus tard par webhook ou par polling. Pour obtenir le résultat dans la même requête, envoyez plutôt la tâche à POST /v1/sync/task.
La réponse de soumission est 200, avec la tâche au statut QUEUED :
Interrogez-la avec son id (référence) :

Cycle de vie

Statuts

Une tâche qui subit un échec transitoire revient à QUEUED et s’exécute de nouveau. Elle ne se fige en FAILED qu’une fois ses tentatives épuisées : un passage PROCESSING → QUEUED est donc normal. Le polling omet response tant que la tâche n’est pas dans un état final. Une tâche échouée porte à la place une chaîne error au premier niveau :

Crédits à la soumission et au polling

Les prix, les blocages et les limites figurent dans Crédits et limites.

Temps de traitement

task.latencyMs est le temps qu’a pris le moteur : de la première prise en charge par un worker jusqu’au résultat final, en millisecondes, sans l’attente en file. Si un échec transitoire la remet en file, le décompte part toujours de cette première prise. Il vaut null dans la réponse de soumission et tant que la tâche est QUEUED ou PROCESSING, et un nombre au polling final et dans le webhook. L’en-tête X-Latency-Ms mesure autre chose : le temps passé par ce serveur sur cette seule requête HTTP.

Priorité

priority accepte de 1 à 10, avec 1 par défaut. Les valeurs hors de cette plage sont ramenées dans la plage, pas refusées. La valeur est renvoyée dans les métadonnées de la tâche.
L’ordre d’exécution n’est garanti ni par la priorité, ni par l’heure de soumission, ni par le compte. Pour un travail dépendant, attendez que la première tâche se termine avant de soumettre la suivante.

Conservation

Vous pouvez interroger une tâche terminée pendant 24 heures après sa fin. Ensuite, GET /v1/async/task/{id} renvoie 404 RESOURCE_NOT_FOUND, la même réponse que pour un id inconnu ou la tâche d’un autre compte. Les tâches QUEUED et PROCESSING restent visibles quel que soit leur âge. La fenêtre de 24 heures s’applique aussi aux corps de résultat de GET /v1/batches/{id}/items et aux lectures de grilles. Une tâche garde son idempotencyKey réservé plus longtemps, pendant au moins 30 jours après la requête (consultez Idempotence). Les nouvelles tentatives automatiques des webhooks suivent leur propre calendrier, indépendamment de cette fenêtre.

Attendre le résultat en une seule requête

POST /v1/sync/task accepte le même corps et garde la requête ouverte jusqu’à la fin de la tâche, 290 secondes au plus. La réponse est alors 200 avec le même corps que le polling de la tâche, y compris pour une tâche en échec. Les moteurs de réponse prennent plus de temps que les tâches SERP et Search. Gardez la requête ouverte selon le type de moteur appelé, tel que regroupé dans le catalogue des moteurs, et réglez le timeout de votre client HTTP quelques secondes au-dessus :
  • Une tâche qui n’est pas terminée à la fin de l’attente reçoit 202, la tâche et Location: /v1/async/task/{id}. Elle continue de s’exécuter et est facturée normalement : interrogez cette adresse ou attendez le webhook. Un 202 peut aussi arriver tout de suite quand le service garde beaucoup de requêtes ouvertes.
  • Envoyez Prefer: wait=<secondes> pour garder la requête moins de 290 secondes. Restez sous le timeout de votre client HTTP, pour recevoir l’id de la tâche avant qu’il abandonne.
  • Envoyez un idempotencyKey. Renvoyer la même clé répond avec la tâche qui la détient : vous pouvez donc répéter une requête expirée de votre côté sans exécuter la tâche deux fois.
  • Avec Accept: text/html et payload.include.html: true, une tâche terminée reçoit sa page enregistrée en text/html, et X-Task-Id porte l’id de la tâche. Une tâche en échec, ou dont la page n’a pas pu être enregistrée, reçoit 406 et le corps JSON.

Webhook ou polling

Préférez les webhooks. Utilisez le polling pour récupérer ce que vous n’avez pas reçu. Un client robuste fait les deux : il traite le webhook comme voie rapide et interroge toute tâche dont il n’a pas eu de nouvelles, bien avant la fin de la fenêtre de 24 heures.

Étapes suivantes

Webhooks

Charge utile, signatures et nouvelles tentatives.

Lots et grilles

Soumettez jusqu’à 10 000 tâches à la fois.