Saltar para o conteúdo principal
Toda requisição é salva como uma tarefa. Você a envia, recebe na hora um id de tarefa e coleta o resultado depois, por webhook ou por polling. Para receber o resultado na mesma requisição, envie a tarefa para POST /v1/sync/task.
A resposta do envio é 200, com a tarefa em QUEUED:
Consulte-a pelo id (referência):

Ciclo de vida

Status

Uma tarefa que encontra uma falha temporária volta para QUEUED e é executada de novo. Ela só termina em FAILED depois de esgotar as novas tentativas, então uma passagem de PROCESSING para QUEUED é normal. O polling omite response até a tarefa chegar a um estado final. Uma tarefa com falha traz, em vez disso, uma string error no nível superior:

Créditos no envio e no polling

Preços, reservas e limites estão em Créditos e limites.

Tempo de processamento

task.latencyMs é o tempo que o motor levou: da primeira retirada por um worker até o resultado final, em milissegundos, sem a espera na fila. Se uma falha transitória devolve a tarefa à fila, a contagem continua a partir dessa primeira retirada. É null na resposta de envio e enquanto a tarefa está QUEUED ou PROCESSING, e um número no polling final e no webhook. O cabeçalho X-Latency-Ms mede outra coisa: o tempo que este servidor gastou nessa única requisição HTTP.

Prioridade

priority aceita de 1 a 10 e o padrão é 1. Valores fora desse intervalo são ajustados ao limite, não rejeitados. O valor é devolvido nos metadados da tarefa.
A ordem de execução não é garantida pela prioridade, pelo horário de envio nem pela conta. Para trabalho dependente, espere a primeira tarefa ser concluída antes de enviar a próxima.

Retenção

Você pode consultar uma tarefa finalizada por 24 horas depois que ela termina. Depois disso, GET /v1/async/task/{id} retorna 404 RESOURCE_NOT_FOUND, a mesma resposta de um id desconhecido ou de uma tarefa de outra conta. Tarefas QUEUED e PROCESSING continuam visíveis, não importa a idade. A janela de 24 horas também vale para os corpos de resultado em GET /v1/batches/{id}/items e nas leituras de grades. O idempotencyKey de uma tarefa continua reservado por mais tempo, por pelo menos 30 dias depois da solicitação (veja Idempotência). As novas tentativas automáticas de webhook seguem seu próprio cronograma, independente dessa janela.

Esperar o resultado em uma só requisição

POST /v1/sync/task aceita o mesmo corpo e mantém a requisição aberta até a tarefa terminar, por no máximo 290 segundos. A resposta é então 200 com o mesmo corpo do polling da tarefa, inclusive para uma tarefa que falhou. Os mecanismos de resposta demoram mais que as tarefas de SERP e Search. Mantenha a requisição aberta conforme o tipo de mecanismo que você chama, como agrupado no catálogo de mecanismos, e defina o timeout do seu cliente HTTP alguns segundos acima:
  • Uma tarefa que não terminou quando a espera acaba é respondida com 202, a tarefa e Location: /v1/async/task/{id}. Ela continua rodando e é cobrada normalmente, então faça polling desse endereço ou receba o webhook. Um 202 também pode vir na hora enquanto o serviço mantém muitas requisições abertas.
  • Envie Prefer: wait=<segundos> para manter a requisição por menos de 290 segundos. Fique abaixo do timeout do seu cliente HTTP, para receber o id da tarefa antes que ele desista.
  • Envie um idempotencyKey. Enviar a mesma chave de novo responde com a tarefa que a detém, então você pode repetir uma requisição que expirou do seu lado sem executar a tarefa duas vezes.
  • Com Accept: text/html e payload.include.html: true, uma tarefa concluída é respondida com a página salva em text/html, e X-Task-Id traz o id da tarefa. Uma tarefa que falhou, ou cuja página não pôde ser salva, é respondida com 406 e o corpo JSON.

Webhook ou polling

Prefira webhooks. Use o polling para recuperar o que você não recebeu. Um cliente robusto faz os dois: recebe o webhook como caminho rápido e consulta por polling qualquer tarefa de que não teve notícia, com folga dentro da janela de 24 horas.

Próximos passos

Webhooks

Payload, assinaturas e novas tentativas.

Lotes e grades

Envie até 10.000 tarefas de uma vez.