Acompanhe execuções do pipeline

Cada etapa habilitada do pipeline deixa um registro no job, para que você veja o que foi executado em vez de simplesmente confiar que foi.

Você ativou algumas etapas do pipeline — talvez pré-edição para limpar o texto de origem e back-translation para detectar desvios — e um job voltou completed_with_warnings. Em qual etapa deu problema? A revisão humana chegou a assumir essa etapa ou ela expirou? Quanto custaram as etapas extras? Um pipeline que executa várias etapas de IA e humanas por idioma é exatamente o tipo de coisa que vira uma caixa-preta: a saída aparece, e você precisa acreditar que as etapas intermediárias fizeram seu trabalho.

Aqui, você não precisa acreditar. Cada etapa habilitada grava um registro no array steps[] do job — qual etapa, qual status, qual custo, quando começou e quando terminou. Você lê o que cada etapa fez; não presume que ela rodou. Esse é o objetivo desta página.

Nesta página

• Onde os registros ficam
• O array steps
• Como mapear um stepId para uma etapa
• Status da etapa: concluída, falhou, ignorada
• Como a falha de uma etapa vira um aviso no job

Onde os registros ficam#

O array steps[] é um campo do job de localização. Você não precisa buscá-lo separadamente — ele vem sempre que você consulta o job:

GET /jobs/localization/:jobId

Autentique com sua chave de API no cabeçalho X-API-Key. O endpoint completo, os valores de status do job e o payload outputData são abordados na página de job único; esta página trata de um campo dessa resposta — o rastro por etapa — e do que ele mostra.

A regra, então, é simples: todo job que você consulta já traz seu próprio log de auditoria. Um job sem pipeline habilitado mostra um único registro, porque a localização principal sempre é executada. Ative duas etapas opcionais e você terá três registros. O array cresce com o pipeline, uma entrada por etapa, na ordem em que as etapas foram executadas.

O array steps#

Cada entrada em steps[] é o registro de uma etapa. Estes são os campos que você lê para auditar uma execução — qual etapa, com qual resultado, a que custo e quando:

"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 registro também traz um campo outputData — o conteúdo produzido por aquela etapa, no mesmo formato de outputData do job. Esse payload é a tradução, não a trilha de auditoria, então está documentado na página de job único ao lado de outputData no nível do job; os campos acima são os que você lê para ver o que o pipeline fez.

Há duas coisas que esses registros oferecem e que um único bloco outputData não oferece. Primeiro, o custo é discriminado por etapa, não apenas totalizado por job — então, quando você habilita back-translation e a fatura muda, pode ver exatamente qual etapa provocou a mudança. Segundo, o tempo é por etapa — um registro humanEdit cujo startedAt e completedAt estão separados por horas mostra que a espera foi do humano, não do engine.

Como mapear um stepId para uma etapa#

Cada stepId identifica uma etapa do pipeline. Esta é a tabela de referência que liga o valor no registro à etapa que ele representa e à página que documenta o que essa etapa faz:

localize é o único stepId que aparece em todos os jobs, com pipeline ou sem pipeline — é a etapa principal de tradução, e sempre é executada. As outras cinco só aparecem quando você habilita essa etapa no engine ou na solicitação.

Status da etapa: concluída, falhou, ignorada#

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

completed e failed são lidos como você espera. skipped é o que merece mais atenção, porque não é a mesma coisa que "desabilitado". Uma etapa que você nunca ativou não gera registro nenhum. Um registro skipped significa que a etapa estava habilitada, mas foi pulada por um motivo definido pelo pipeline — o caso mais claro é revisão humana: se a janela de revisão se encerrar sem resposta humana, essa etapa é marcada como skipped e a tradução por IA segue como versão final. O registro continua lá, então o skip fica visível em vez de silencioso.

Como a falha de uma etapa vira um aviso no job#

Quando uma etapa não crítica falha, isso aparece em dois lugares ao mesmo tempo — e são duas visões do mesmo evento. O registro em steps[] aparece como failed com um errorMessage — essa é a visão detalhada. A mesma falha também aparece como uma entrada no array warnings no nível superior do job — essa é a visão resumida, na qual o seu código de tratamento de status se baseia para tomar decisões:

{
  "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 em warnings é { step, message }, em que step é o mesmo stepId que você encontra no registro com falha. Assim, os dois arrays se alinham: warnings é a lista resumida do que deu errado, e steps[] é onde você vai para ver os detalhes por trás de cada item. Leia warnings para decidir se deve sinalizar o idioma para um humano; leia o registro correspondente em steps[] quando quiser o errorMessage, o custo e o tempo por trás disso.

Esse é o mecanismo por trás de completed_with_warnings: a tradução principal foi bem-sucedida, então você tem outputData utilizável, mas pelo menos uma etapa não crítica deixou um registro failed e um aviso correspondente. Trate a saída como pronta para envio e os avisos como um sinal de qualidade que vale a pena destacar. Só um status de job com valor failed significa que não há tradução para ler — e essa decisão, junto com a tabela completa de status do job, está na página de job único.

Próximos passos#