Buscar um job

Leia a saída traduzida de um idioma e o registro por etapa de como ela foi produzida.

Você recorre a isso quando já tem um jobId — retornado no 202 da criação, enviado em um webhook ou listado em um grupo de jobs. O endpoint de grupo informa quantos idiomas já foram concluídos. Este endpoint mostra o que um único idioma produziu e o que aconteceu ao longo do processo.

GET /jobs/localization/:jobId

Essa distinção é exatamente o motivo desta página existir. A resposta de um grupo é um placar — contagens e status por job, abordados na página de grupo de jobs. Já um job individual é o registro completo de um idioma: o outputData traduzido, o status terminal, qualquer warnings e o histórico em steps[] de cada etapa executada pelo pipeline. Quando chegar a hora de gravar o texto em alemão no seu banco de dados, é esta chamada que entrega esse texto em alemão.

Autenticação#

Passe sua chave de API no cabeçalho X-API-Key. As chaves têm escopo de organização e dão acesso a todos os engine da organização. Consulte Authentication para mais detalhes.

Resposta#

O campo outputData espelha a estrutura do data de entrada, com cada valor string traduzido e cada valor não string (números, booleanos, null) preservado no lugar. Mesmas chaves, mesmo aninhamento, mesma ordem nos arrays — só as strings mudam.

{
  "id": "ljb_A1b2C3d4E5f6G7h8",
  "groupId": "ljg_A1b2C3d4E5f6G7h8",
  "targetLocale": "de",
  "status": "completed",
  "outputData": {
    "id": "course_101",
    "title": "Einführung in maschinelles Lernen",
    "steps": [
      { "heading": "Was ist ML?", "body": "Maschinelles Lernen ist ein Teilbereich der künstlichen Intelligenz." },
      { "heading": "Überwachtes Lernen", "body": "Trainieren eines Modells mit gelabelten Daten." }
    ],
    "metadata": { "author": "Dr. Smith", "difficulty": "beginner" }
  },
  "errorMessage": null,
  "warnings": [],
  "callbackStatus": "delivered",
  "createdAt": "2026-03-16T10:30:00.000Z",
  "startedAt": "2026-03-16T10:30:01.000Z",
  "completedAt": "2026-03-16T10:30:04.000Z",
  "steps": [
    {
      "stepId": "localize",
      "type": "action",
      "status": "completed",
      "errorMessage": null,
      "externalRefType": null,
      "externalRefId": null,
      "externalRefUrl": null,
      "createdAt": "2026-03-16T10:30:01.000Z",
      "startedAt": "2026-03-16T10:30:01.000Z",
      "completedAt": "2026-03-16T10:30:04.000Z"
    }
  ]
}

O bloco metadata acima permaneceu intacto — Dr. Smith e beginner são folhas não string que o engine deixou como estavam. O outputData que você recebe de volta mantém o formato do que foi enviado, então o mesmo código que montou o payload pode consumir a tradução.

Valores de status do job#

Um job vai de queued para processing e então para exatamente um estado terminal. Faça a ramificação com base em status antes de ler qualquer outra coisa — é ele que informa quais campos estão preenchidos.

O array steps#

steps[] é o histórico por etapa por trás de um único job — um registro para cada etapa que o engine executou, em ordem. Todo job inclui pelo menos a etapa localize, porque a tradução principal sempre roda. Cada etapa opcional do pipeline que você habilita adiciona mais um registro. Então, um job sem etapas extras mostra uma única etapa localize; um job com pre-edit e back-translation habilitados mostra três.

É isso que torna um job auditável, e não uma caixa-preta. Você não precisa confiar que uma etapa foi executada — basta ler o registro dela: qual etapa (stepId), se ela completed, failed ou foi skipped, quanto custou (costUsd) e quando começou e terminou. Para etapas de revisão humana, externalRef* aponta para o registro externo.

"steps": [
  {
    "stepId": "preEdit",
    "type": "action",
    "status": "completed",
    "errorMessage": null,
    "costUsd": 0.0012,
    "createdAt": "2026-03-16T10:30:01.000Z",
    "completedAt": "2026-03-16T10:30:02.000Z"
  },
  {
    "stepId": "localize",
    "type": "action",
    "status": "completed",
    "errorMessage": null,
    "costUsd": 0.0184,
    "createdAt": "2026-03-16T10:30:02.000Z",
    "completedAt": "2026-03-16T10:30:05.000Z"
  }
]

Uma entrada failed aqui não necessariamente faz o job falhar. Quando uma etapa não crítica falha, o registro steps[] dela aparece como failed, a mesma falha também aparece no nível superior do job em warnings, e o job ainda assim chega a completed_with_warnings com outputData completo. O formato completo do registro — cada campo, cada stepId, a semântica de completed/failed/skipped — fica em uma única página canônica: Observe pipeline runs. Esta página mostra onde encontrá-lo em um job; aquela página define a especificação.

Lendo um job concluído#

Um consumidor típico faz a ramificação com base em status, grava outputData em caso de sucesso e registra errorMessage em caso de falha. A chamada pronta para copiar e colar abaixo retorna o payload mostrado acima.

const jobId = "ljb_A1b2C3d4E5f6G7h8";
const response = await fetch(`https://api.lingo.dev/jobs/localization/${jobId}`, {
  headers: { "X-API-Key": process.env.LINGO_API_KEY },
});

const job = await response.json();

switch (job.status) {
  case "completed":
  case "completed_with_warnings":
    // outputData is populated; warnings may carry non-critical stage failures
    await db.content.update({
      where: { id: job.outputData.id },
      data: { [`content_${job.targetLocale}`]: job.outputData },
    });
    if (job.warnings.length) console.warn(job.targetLocale, job.warnings);
    break;
  case "failed":
    console.error(`${job.targetLocale} failed: ${job.errorMessage}`);
    break;
  default:
    // queued or processing - nothing to read yet; also catches future states
    break;
}

Quando este endpoint retorna um erro — um jobId desconhecido, uma chave ausente — ele segue o modelo padrão de erro JSON. Consulte Errors and status codes.

Próximos passos#