Webhooks e o WebSocket em tempo real avisam sobre um job no instante em que ele é concluído. Mas nenhum dos dois ajuda na manhã seguinte, depois de um deploy, ou quando você quer ver todos os idiomas que falharam na última hora. O momento já passou; o evento já foi. Os jobs, não — cada um continua como um registro durável na plataforma, muito depois de o processo que o enviou seguir em frente.
GET /jobs/localization é como você recupera esses registros. Ele retorna seus jobs dos mais recentes para os mais antigos, em páginas que você percorre com um cursor, filtradas pela engine de localização em que rodaram ou pelo status com que terminaram. Este é o canal de recuperação: o registro durável que você consulta quando não estava acompanhando em tempo real.
GET /jobs/localizationAinda não conhece localização assíncrona? Comece pela Visão geral. Esta página parte do princípio de que você já tem jobs para consultar. Como todo endpoint, ela usa sua X-API-Key para autenticação.
Filtros e paginação#
GET /jobs/localization?engineId=eng_abc123&status=completed&limit=20&cursor=...| Parâmetro | Tipo | Descrição |
|---|---|---|
engineId | string (opcional) | Retorna apenas jobs executados nesta engine de localização (eng_...). |
status | string (opcional) | Retorna apenas jobs neste status: queued, processing, completed, completed_with_warnings ou failed. |
limit | number (opcional) | Tamanho da página. Padrão: 20; máximo: 100. |
cursor | string (opcional) | Cursor opaco vindo do nextCursor da resposta anterior. Omita na primeira página. |
Os dois filtros são opcionais e podem ser combinados: engineId=eng_abc123&status=failed retorna os jobs com falha de uma engine específica e nada além disso. Essa combinação responde a uma pergunta que você realmente faz durante um incidente — mostre tudo o que falhou nesta engine — sem trazer todos os jobs da organização para filtrar no cliente.
O cursor é uma posição no fluxo de resultados, não um número de página. Você não calcula esse valor; você o recebe. Cada resposta traz um nextCursor, e você reutiliza esse valor para buscar a página seguinte.
Resposta#
Cada página traz um array items e um nextCursor. nextCursor é null na última página — essa é a condição de saída do seu loop, não um erro.
{
"items": [
{
"id": "ljb_C3d4E5f6G7h8I9j0",
"groupId": "ljg_A1b2C3d4E5f6G7h8",
"targetLocale": "ja",
"status": "completed",
"warnings": [],
"createdAt": "2026-03-16T10:30:00.000Z",
"completedAt": "2026-03-16T10:30:06.000Z"
}
],
"nextCursor": "eyJ0IjoiMjAyNi0wMy0xNlQxMDozMDowMC4wMDBaIiwiaSI6ImxqYl9CMmMzRDRlNUY2ZzdIOGk5In0"
}Cada item é um resumo — suficiente para localizar um job e entender seu resultado: qual idioma, qual grupo, qual status, quando foi criado e quando terminou. Deliberadamente, ele não inclui a saída traduzida. Para obter o outputData completo e os steps por etapa de um desses jobs, pegue o id e chame Obter um job. Liste para encontrar; busque para ler.
Trate status desconhecidos com robustez
Faça match com os valores de status que você conhece e deixe o restante cair em um caso padrão, em vez de fazer o consumidor quebrar ao receber um valor que ele ainda não viu. Tolerar um valor não reconhecido é a escolha defensiva padrão para qualquer enum de string que não é seu — assim, seu leitor continua funcionando em vez de lançar erro ao receber uma entrada que não consegue classificar.
Percorra todos os resultados#
A condição de saída é o ponto central: continue fazendo requisições até que nextCursor volte como null. Passe o nextCursor de uma resposta como cursor da próxima, e o loop se encerra sozinho.
async function listFailedJobs(engineId) {
const failed = [];
let cursor = undefined; // first page: no cursor
do {
const url = new URL("https://api.lingo.dev/jobs/localization");
url.searchParams.set("engineId", engineId);
url.searchParams.set("status", "failed");
url.searchParams.set("limit", "100"); // fewer round-trips
if (cursor) url.searchParams.set("cursor", cursor);
const response = await fetch(url, {
headers: { "X-API-Key": process.env.LINGO_API_KEY },
});
const { items, nextCursor } = await response.json();
failed.push(...items);
cursor = nextCursor; // null on the last page -> loop ends
} while (cursor);
return failed; // every failed job for this engine
}Aumentar limit para 100 reduz o número de idas e vindas em um backlog grande; isso não altera o resultado, apenas quantas páginas você precisa percorrer para lê-lo. Não há offset para sair de sincronia nem contagem de páginas para manter alinhada — o cursor guarda sua posição, e null indica quando você já leu tudo.
Próximos passos#
Você já tem o id de um job. O canal de recuperação trouxe você até aqui; agora, basta ler o resultado ou conectar os canais em tempo real para que, da próxima vez, você acompanhe tudo enquanto acontece.
