Você criou um grupo, recebeu um groupId de volta, e agora vários idiomas estão sendo traduzidos em paralelo. A pergunta que você precisa responder, repetidamente, até o trabalho terminar é: como está a submissão inteira neste exato momento? Não idioma por idioma — o agregado. Quantos foram concluídos, quantos geraram saída com avisos, quantos falharam e quantos ainda estão em andamento.
É exatamente isso que este endpoint retorna. Um polling, o status de todos os idiomas, em uma única resposta. Está começando em localização assíncrona? Comece pela Visão geral da API de localização assíncrona.
Nesta página
Obter um grupo de jobs#
Recupere o status de um grupo de jobs e de todos os seus jobs filhos.
GET /jobs/localization/groups/:groupIdAutentique com sua chave de API no cabeçalho X-API-Key, a mesma chave que você usou para criar o grupo. O groupId é o id com prefixo ljg_ retornado na resposta 202.
Resposta#
A resposta é um retrato da submissão inteira: o status do próprio grupo, quatro contagens e os jobs filhos com seus estados individuais. É esse objeto que você consulta a cada polling.
{
"groupId": "ljg_A1b2C3d4E5f6G7h8",
"status": "processing",
"sourceLocale": "en",
"totalJobs": 3,
"completedJobs": 1,
"completedWithWarningsJobs": 0,
"failedJobs": 0,
"jobs": [
{ "id": "ljb_A1b2C3d4E5f6G7h8", "targetLocale": "de", "status": "completed", "warnings": [], "completedAt": "2026-03-16T10:30:04.000Z" },
{ "id": "ljb_B2c3D4e5F6g7H8i9", "targetLocale": "fr", "status": "processing", "warnings": [], "completedAt": null },
{ "id": "ljb_C3d4E5f6G7h8I9j0", "targetLocale": "ja", "status": "queued", "warnings": [], "completedAt": null }
],
"createdAt": "2026-03-16T10:30:00.000Z"
}Os três campos de contagem de jobs em estado terminal — completedJobs, completedWithWarningsJobs e failedJobs — somam o número de idiomas que já terminaram. O restante de totalJobs ainda está em queued ou processing. No retrato acima, 1 de 3 foi concluído e 2 ainda estão em andamento, então uma única leitura das contagens já mostra que o trabalho ainda não terminou, sem precisar percorrer o array jobs. Quando essa soma atingir totalJobs, o grupo terá alcançado um status terminal.
O array warnings de cada job expõe falhas não críticas em etapas do pipeline — por exemplo, uma etapa de pré-edição ou back-translation que não foi concluída. Um array não vazio significa que o job ainda produziu saída, mas pelo menos uma etapa opcional não foi concluída. O próprio outputData traduzido fica no job individual — busque-o quando estiver pronto para ler o conteúdo finalizado de um idioma.
Status do grupo#
O status do grupo consolida os jobs filhos em um único valor. Você faz polling até ele atingir um estado terminal.
| Status do grupo | Significado |
|---|---|
pending | Grupo criado, nenhum job iniciado ainda |
processing | Pelo menos um job está em andamento |
completed | Todos os jobs foram concluídos com sucesso |
completed_with_warnings | Todos os jobs produziram saída, mas uma ou mais etapas opcionais do pipeline falharam em pelo menos um job |
partial | Alguns jobs foram concluídos, outros falharam |
failed | Todos os jobs falharam |
A divisão entre completed, completed_with_warnings e partial é justamente o ponto deste endpoint: ela diferencia entre "todos os idiomas foram entregues" e "todos os idiomas foram entregues, alguns com aviso" e "alguns idiomas foram entregues e outros não" — três resultados que, de outra forma, você teria de reconstruir lendo cada job. partial não é um erro; é um estado real que o grupo reporta de forma explícita para que seu código possa seguir caminhos diferentes com base nisso.
Com que frequência fazer polling#
Intervalo de polling
Para a maioria dos jobs, o processamento leva de 2 a 8 segundos por idioma. Se você estiver fazendo polling em vez de usar webhooks ou WebSocket, um intervalo de 2 segundos é um ponto de partida razoável.
Polling é a forma mais simples de acompanhar um grupo e, para um lote de curta duração, funciona muito bem. Mas é a opção mais limitada, e vale a pena dizer isso com clareza: cada polling é uma ida e volta, tenha algo mudado ou não, e você só descobre que um idioma foi concluído no próximo intervalo — não no momento exato em que ele fica pronto.
Se você quer receber cada resultado no instante em que ele estiver pronto, não faça polling — receba a notificação. A plataforma entrega cada idioma concluído na sua URL de webhook assim que termina, e uma conexão WebSocket no grupo envia um retrato completo do estado a cada mudança, para que sua UI seja atualizada sem precisar consultar. Recorra ao polling quando um endpoint de webhook ou uma conexão persistente forem mais do que o job exige; prefira push quando a latência até a sua UI importa.
Quando um idioma falha#
Uma leitura cética de "traduzir para muitos idiomas de uma vez" faz primeiro a pergunta mais óbvia: o que acontece com os demais quando um idioma falha? Aqui está a resposta, na própria resposta.
Cada idioma é um job independente. Se o alemão for bem-sucedido, mas o japonês falhar, a tradução para alemão é concluída e entregue normalmente — a falha não faz rollback. O job com falha aparece no grupo com status: "failed", failedJobs é incrementado, e o grupo consolida para partial:
{
"groupId": "ljg_A1b2C3d4E5f6G7h8",
"status": "partial",
"sourceLocale": "en",
"totalJobs": 3,
"completedJobs": 2,
"completedWithWarningsJobs": 0,
"failedJobs": 1,
"jobs": [
{ "id": "ljb_A1b2C3d4E5f6G7h8", "targetLocale": "de", "status": "completed", "warnings": [], "completedAt": "2026-03-16T10:30:04.000Z" },
{ "id": "ljb_B2c3D4e5F6g7H8i9", "targetLocale": "fr", "status": "completed", "warnings": [], "completedAt": "2026-03-16T10:30:05.000Z" },
{ "id": "ljb_C3d4E5f6G7h8I9j0", "targetLocale": "ja", "status": "failed", "warnings": [], "completedAt": null }
],
"createdAt": "2026-03-16T10:30:00.000Z"
}Dois idiomas foram entregues, um não, e as contagens mostram isso sem que você precise inspecionar nada. Para tentar de novo, envie uma nova solicitação apenas com os idiomas que falharam e uma nova chave de idempotência. A descrição completa do erro de um idioma com falha — o errorMessage — fica no job individual; o grupo fornece a contagem e o veredito.
Falhas parciais são um estado normal
partial significa exatamente o que as contagens mostram: alguns idiomas foram concluídos, alguns falharam. Os idiomas concluídos já foram entregues. Não há nada para reverter nem novo consumo nos idiomas que deram certo — você tenta novamente apenas o que falhou.
