Cada etapa habilitada del pipeline deja un registro en el trabajo, así que puedes ver qué se ejecutó en lugar de dar por hecho que se ejecutó.
Has activado varias etapas del pipeline —quizá pre-edit para limpiar el original y back-translation para detectar desviaciones— y un trabajo ha vuelto con completed_with_warnings. ¿Qué etapa se quedó por el camino? ¿Llegó el revisor humano a revisarlo, o se agotó el tiempo? ¿Cuánto costaron las etapas adicionales? Un pipeline que ejecuta varios pasos de IA y humanos por idioma es justo el tipo de sistema que acaba convirtiéndose en una caja negra: sale un resultado y das por hecho que las etapas intermedias hicieron su trabajo.
Aquí no te piden un acto de fe. Cada etapa habilitada escribe un registro en el array steps[] del trabajo: qué etapa fue, qué estado tuvo, cuánto costó y cuándo empezó y terminó. Lees lo que hizo cada etapa; no das por hecho que se ejecutó. Ese es precisamente el objetivo de esta página.
¿Aún no conoces el pipeline? Empieza por la Descripción general del pipeline.
En esta página
- Dónde están los registros
- El array steps
- Cómo relacionar un stepId con una etapa
- Estado de una etapa: completed, failed, skipped
- Cómo un fallo de etapa se convierte en una advertencia del trabajo
Dónde están los registros#
El array steps[] es un campo del trabajo de localización. No tienes que recuperarlo por separado: llega cada vez que lees el trabajo:
GET /jobs/localization/:jobIdAutentícate con tu clave de API en la cabecera X-API-Key. El endpoint completo, los valores de estado del trabajo y el payload outputData se explican en la página del trabajo individual; esta página se centra en un único campo de esa respuesta —el rastro por etapa— y en lo que te dice.
La regla, por tanto, es simple: cada trabajo que lees ya lleva su propio registro de auditoría. Un trabajo sin pipeline habilitado muestra un único registro, porque core localization siempre se ejecuta. Activa dos etapas opcionales y tendrás tres registros. El array crece con el pipeline, una entrada por etapa, en el orden en que se ejecutaron.
El array steps#
Cada entrada de steps[] es el registro de una etapa. Estos son los campos que debes leer para auditar una ejecución: qué etapa fue, con qué resultado, con qué coste y cuándo:
"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"
}
]| Campo | Descripción |
|---|---|
stepId | A qué etapa del pipeline corresponde este registro. Consulta la tabla de correspondencias más abajo. |
type | El tipo de paso. action para una etapa automatizada. |
status | completed, failed o skipped para esta etapa, independientemente del estado del trabajo. |
errorMessage | Por qué falló esta etapa. null salvo que status sea failed. |
costUsd | Cuánto costó esta etapa, en USD: un número JSON o null. |
externalRefType, externalRefId, externalRefUrl | Un puntero a un registro externo para etapas que delegan el trabajo en un tercero: la etapa de human review. null para etapas totalmente automatizadas. |
createdAt, startedAt, completedAt | Cuándo se creó, se recogió y terminó la etapa. |
Cada registro también incluye un campo outputData: el contenido que produjo esa etapa, con la misma estructura que el outputData del trabajo. Ese payload es la traducción, no el rastro de auditoría, así que está documentado en la página del trabajo individual junto con el outputData a nivel de trabajo; los campos anteriores son los que debes leer para ver qué hizo el pipeline.
Estos registros te dan dos cosas que un único blob outputData no puede darte. Primero, el coste está desglosado por etapa, no solo totalizado por trabajo; así que, cuando activas back-translation y cambia la factura, puedes ver exactamente qué etapa la movió. Segundo, el tiempo se mide por etapa: un registro humanEdit cuyos startedAt y completedAt están separados por horas te dice que la espera fue cosa del humano, no del motor.
Lee steps por stepId, no por posición
Los registros aparecen en orden de ejecución, pero no indexes el array por posición: las etapas que se ejecutan dependen de cuáles hayas habilitado, así que la posición no es estable entre trabajos. Encuentra una etapa por su stepId (steps.find(s => s.stepId === "humanEdit")). El conjunto de valores stepId es fijo; el conjunto presente en un trabajo concreto es el que tú hayas activado.
Cómo relacionar un stepId con una etapa#
Cada stepId nombra una etapa del pipeline. Esta es la tabla de referencia que relaciona el valor del registro con la etapa que representa y con la página que documenta lo que hace esa etapa:
stepId | Etapa |
|---|---|
preEdit | Edición de IA previa a la localización |
localize | Localización principal |
humanEdit | Revisión humana posterior a la localización |
postEdit | evaluación de IA posterior a la localización |
rephrase | Reformular para lograr un texto natural |
backTranslation | Comprobación de retraducción |
localize es el único stepId que aparece en todos los trabajos, haya pipeline o no: es el paso principal de traducción y siempre se ejecuta. Los otros cinco solo aparecen cuando has habilitado esa etapa en el motor o en la solicitud.
Estado de una etapa: completed, failed, skipped#
Cada paso lleva su propio status, establecido de forma independiente del trabajo y de cualquier otro paso. Hay tres valores:
status de la etapa | Significado |
|---|---|
completed | La etapa se ejecutó y produjo su resultado. |
failed | La etapa se ejecutó y dio error. errorMessage indica por qué. |
skipped | La etapa no llegó a completarse esta vez, aunque estaba habilitada. |
completed y failed se entienden como cabría esperar. skipped es el que merece detenerse un momento, porque no es lo mismo que "disabled". Una etapa que nunca activaste no produce ningún registro. Un registro skipped significa que la etapa sí estaba habilitada, pero se pasó por alto por una razón definida por el pipeline; el caso más claro es human review: si la ventana de revisión se cierra sin respuesta humana, esa etapa se marca como skipped y la traducción de IA pasa a ser la final. El registro sigue ahí, así que la omisión queda visible en lugar de pasar desapercibida.
El estado de una etapa no es el estado del trabajo
Una etapa failed no siempre significa un trabajo failed. La mayoría de las etapas opcionales no son críticas: cuando una falla, su registro aparece como failed, el motor arrastra la última salida válida y el trabajo sigue terminando con outputData. El estado de trabajo resultante —completed_with_warnings— se explica en la página del trabajo individual. El estado de la etapa te dice qué ocurrió en una etapa; el estado del trabajo te dice si obtuviste una traducción.
Cómo un fallo de etapa se convierte en una advertencia del trabajo#
Cuando falla una etapa no crítica, el fallo aparece a la vez en dos sitios, y son dos vistas del mismo evento. El registro steps[] aparece como failed con un errorMessage: esa es la vista detallada. Ese mismo fallo también aparece como una entrada en el array warnings de nivel superior del trabajo: esa es la vista resumida sobre la que ramifica tu código de gestión de estados:
{
"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 es { step, message }, donde step es el mismo stepId que encontrarías en el registro fallido. Así que los dos arrays se corresponden: warnings es la lista corta de lo que salió mal, y steps[] es donde vas a buscar el detalle de cada caso. Lee warnings para decidir si debes marcar el idioma para revisión humana; lee el registro steps[] correspondiente cuando quieras conocer el errorMessage, el coste y el tiempo que hay detrás.
Este es el mecanismo detrás de completed_with_warnings: la traducción principal tuvo éxito, así que tienes un outputData utilizable, pero al menos una etapa no crítica dejó un registro failed y una advertencia correspondiente. Trata el resultado como apto para publicarse y las advertencias como una señal de calidad que merece mostrarse. Solo un status del trabajo con valor failed significa que no hay ninguna traducción que consultar; esa decisión, junto con la tabla completa de estados del trabajo, está en la página del trabajo individual.
La salud agregada de las etapas va por otra vía
steps[] responde a «qué hizo el pipeline en este trabajo». Si quieres ver la tendencia a lo largo de muchos trabajos —con qué frecuencia falla pre-edit, con qué frecuencia back-translation corrige una traducción—, eso ya es una pregunta agregada, y se responde en la página de Informes, no en una respuesta por trabajo. Aquí, registros por trabajo; allí, agregados.
