Observar execuções do pipeline

Cada etapa ativa do pipeline deixa um registo no job, para que possa ver o que correu em vez de apenas confiar que correu.

Ativou algumas etapas do pipeline — talvez pré-edição para limpar a origem e retrotradução para detetar desvios — e um job voltou completed_with_warnings. Que etapa falhou? O revisor humano chegou a pegá-lo, ou deixou expirar o prazo? Quanto custaram as etapas extra? Um pipeline que executa várias etapas de IA e humanas por idioma é exatamente o tipo de coisa que se transforma numa caixa-preta: sai um resultado e fica-se a acreditar que as etapas intermédias fizeram o seu trabalho.

Aqui não lhe pedem um ato de fé. Cada etapa ativa escreve um registo no array steps[] do job — que etapa, com que estado, com que custo, quando começou e quando terminou. Lê o que cada etapa fez; não parte do princípio de que correu. Esse é todo o objetivo desta página.

Nesta página

• Onde ficam os registos
• O array steps
• Mapear um stepId para uma etapa
• Estado da etapa: concluído, falhado, ignorado
• Como uma falha numa etapa se torna um aviso no job

Onde ficam os registos#

O array steps[] é um campo do job de localização. Não precisa de o pedir à parte — vem sempre que lê o job:

GET /jobs/localization/:jobId

Autentique-se com a sua chave de API no cabeçalho X-API-Key. O endpoint completo, os valores de estado do job e o payload outputData são abordados na página do job individual; esta página centra-se num campo dessa resposta — o histórico por etapa — e no que ele lhe mostra.

A regra, por isso, é simples: cada job que lê já traz o seu próprio registo de auditoria. Um job sem pipeline ativado mostra um único registo, porque a localização principal corre sempre. Ative duas etapas opcionais e passa a ter três registos. O array cresce com o pipeline, uma entrada por etapa, pela ordem em que as etapas correram.

O array steps#

Cada entrada em steps[] é o registo de uma etapa. Estes são os campos a ler para auditar uma execução — que etapa foi, com que resultado, com que custo e em que momento:

"steps": [
  {
    "stepId": "preEdit",
    "type": "action",
    "status": "completed",
    "errorMessage": null,
    "costUsd": 0.0012,
    "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:02.000Z"
  },
  {
    "stepId": "localize",
    "type": "action",
    "status": "completed",
    "errorMessage": null,
    "costUsd": 0.0184,
    "externalRefType": null,
    "externalRefId": null,
    "externalRefUrl": null,
    "createdAt": "2026-03-16T10:30:02.000Z",
    "startedAt": "2026-03-16T10:30:02.000Z",
    "completedAt": "2026-03-16T10:30:05.000Z"
  }
]

Cada registo também inclui um campo outputData — o conteúdo que essa etapa produziu, com a mesma estrutura do outputData do job. Esse payload é a tradução, não o registo de auditoria, por isso está documentado na página do job individual juntamente com o outputData ao nível do job; os campos acima são os que lê para ver o que o pipeline fez.

Há duas coisas que estes registos lhe dão e que um único bloco outputData não dá. Primeiro, o custo é discriminado por etapa, não apenas totalizado por job — por isso, quando ativa a retrotradução e a fatura muda, pode ver exatamente que etapa a fez subir. Segundo, o tempo é por etapa — um registo humanEdit cujos startedAt e completedAt estão separados por horas diz-lhe que a espera foi do humano, não do motor.

Mapear um stepId para uma etapa#

Cada stepId identifica uma etapa do pipeline. Esta é a tabela de correspondência entre o valor no registo, a etapa que representa e a página que documenta o que essa etapa faz:

localize é o único stepId que aparece em todos os jobs, com pipeline ou sem ele — é a etapa principal de tradução, e corre sempre. As outras cinco só aparecem quando ativa essa etapa no motor ou no pedido.

Estado da etapa: concluído, falhado, ignorado#

Cada etapa tem o seu próprio status, definido independentemente do job e de todas as outras etapas. Há três valores:

completed e failed leem-se como seria de esperar. skipped é o que merece uma pausa, porque não é o mesmo que "desativada". Uma etapa que nunca ativou não produz registo nenhum. Um registo skipped significa que a etapa estava ativada, mas foi passada à frente por uma razão definida pelo pipeline — o caso mais claro é a revisão humana: se a janela de revisão fechar sem resposta humana, essa etapa fica marcada como skipped e a tradução por IA segue como final. O registo continua lá, por isso a omissão fica visível em vez de passar despercebida.

Como uma falha numa etapa se torna um aviso no job#

Quando uma etapa não crítica falha, a falha aparece em dois sítios ao mesmo tempo — e são duas perspetivas sobre o mesmo evento. O registo em steps[] fica como failed com um errorMessage — essa é a vista detalhada. A mesma falha também surge como uma entrada no array warnings de topo do job — essa é a vista resumida em que o seu código de tratamento de estado se baseia para ramificar:

{
  "id": "ljb_A1b2C3d4E5f6G7h8",
  "status": "completed_with_warnings",
  "outputData": { "title": "Hallo" },
  "warnings": [
    { "step": "backTranslation", "message": "Back-translation check did not complete" }
  ],
  "steps": [
    { "stepId": "localize", "type": "action", "status": "completed", "errorMessage": null, "costUsd": 0.0184, "completedAt": "2026-03-16T10:30:05.000Z" },
    { "stepId": "backTranslation", "type": "action", "status": "failed", "errorMessage": "Back-translation check did not complete", "costUsd": 0.0031, "completedAt": "2026-03-16T10:30:11.000Z" }
  ]
}

Cada entrada de warnings é { step, message }, em que step é o mesmo stepId que encontraria no registo falhado. Por isso, os dois arrays estão alinhados: warnings é a lista curta do que correu mal, e steps[] é onde vai buscar o detalhe por trás de cada caso. Leia warnings para decidir se deve sinalizar o idioma para revisão humana; leia o registo steps[] correspondente quando quiser o errorMessage, o custo e o timing por trás disso.

Este é o mecanismo por trás de completed_with_warnings: a tradução principal foi concluída com êxito, por isso tem outputData utilizável, mas pelo menos uma etapa não crítica deixou um registo failed e um aviso correspondente. Trate o resultado como pronto a publicar e os avisos como um sinal de qualidade que vale a pena mostrar. Só um status do job de failed significa que não há tradução para ler — e essa decisão, com a tabela completa de estados do job, encontra-se na página do job individual.

Passos seguintes#