Monitorear un grupo de trabajos

Creaste un grupo, recibiste un groupId y ahora varios idiomas se están traduciendo en paralelo. Necesitas responder una sola pregunta, una y otra vez, hasta que el trabajo termine de asentarse: ¿cómo va todo el envío en este momento? No idioma por idioma, sino el agregado. Cuántos ya terminaron, cuántos generaron salida con advertencias, cuántos fallaron y cuántos siguen en ejecución.

Eso es exactamente lo que devuelve este endpoint. Una sola consulta, el estado de cada idioma, en una sola respuesta. ¿Eres nuevo en la localización asíncrona? Empieza con la Descripción general de la API de localización asíncrona.

En esta página

• Obtener un grupo de trabajos
• Respuesta
• Estados del grupo
• Con qué frecuencia consultar
• Cuando falla un idioma

Obtener un grupo de trabajos#

Recupera el estado de un grupo de trabajos y de todos sus trabajos secundarios.

GET /jobs/localization/groups/:groupId

Autentícate con tu clave de API en el encabezado X-API-Key, la misma clave que usaste para crear el grupo. El groupId es el id con prefijo ljg_ de la respuesta 202.

Respuesta#

La respuesta es una instantánea de todo el envío: el status del grupo, cuatro conteos y los trabajos secundarios con sus estados individuales. Este es el objeto que consultas en cada sondeo.

{
  "groupId": "ljg_A1b2C3d4E5f6G7h8",
  "status": "processing",
  "sourceLocale": "en",
  "totalJobs": 3,
  "completedJobs": 1,
  "completedWithWarningsJobs": 0,
  "failedJobs": 0,
  "jobs": [
    { "id": "ljb_A1b2C3d4E5f6G7h8", "targetLocale": "de", "status": "completed", "warnings": [], "completedAt": "2026-03-16T10:30:04.000Z" },
    { "id": "ljb_B2c3D4e5F6g7H8i9", "targetLocale": "fr", "status": "processing", "warnings": [], "completedAt": null },
    { "id": "ljb_C3d4E5f6G7h8I9j0", "targetLocale": "ja", "status": "queued", "warnings": [], "completedAt": null }
  ],
  "createdAt": "2026-03-16T10:30:00.000Z"
}

Los tres campos de conteo para trabajos terminales —completedJobs, completedWithWarningsJobs y failedJobs— suman la cantidad de idiomas que ya terminaron. El resto de totalJobs sigue en queued o processing. En la instantánea de arriba, 1 de 3 terminó y 2 siguen en curso, así que con solo leer los conteos ya sabes que el trabajo todavía no se ha resuelto, sin necesidad de revisar el arreglo jobs. Cuando esa suma alcanza totalJobs, el grupo llega a un estado terminal.

El arreglo warnings de cada trabajo muestra fallas no críticas en etapas opcionales del pipeline; por ejemplo, un paso de preedición o retrotraducción que no se completó. Un arreglo no vacío significa que el trabajo sí generó salida, pero que al menos una etapa opcional no terminó. El outputData traducido en sí vive en el trabajo individual; consúltalo cuando estés listo para leer el contenido de un idioma terminado.

Estados del grupo#

El status del grupo consolida sus trabajos secundarios en un solo valor. Haz sondeos hasta que alcance un estado terminal.

La diferencia entre completed, completed_with_warnings y partial es justamente el valor de este endpoint: distingue entre "todos los idiomas se entregaron", "todos los idiomas se entregaron, algunos con advertencias" y "algunos idiomas se entregaron y otros no"; tres resultados que, de otro modo, tendrías que reconstruir leyendo cada trabajo. partial no es un error; es un estado real que el grupo informa con claridad para que tu código pueda actuar en consecuencia.

Con qué frecuencia consultar#

Consultar es la forma más simple de monitorear un grupo y, para un lote de corta duración, está perfectamente bien. Pero es la opción más débil, y vale la pena decirlo con claridad: cada consulta es un viaje de ida y vuelta haya cambiado algo o no, y te enteras de que un idioma terminó hasta el siguiente ciclo, no en el momento exacto en que queda listo.

Si quieres cada resultado en el instante en que esté listo, no consultes: deja que te avisen. La plataforma entrega cada idioma completado a tu URL de webhook a medida que termina, y una conexión WebSocket en el grupo envía una instantánea completa del estado con cada cambio, para que tu UI se actualice sin tener que preguntar. Recurre al sondeo cuando un endpoint de webhook o una conexión persistente sea más de lo que justifica el trabajo; recurre al push cuando la latencia hacia tu UI importa.

Cuando falla un idioma#

Una lectura escéptica de "traducir a muchos idiomas a la vez" plantea primero la pregunta obvia: ¿qué pasa con el resto cuando falla un idioma? Aquí está la respuesta, en la propia respuesta.

Cada idioma es un trabajo independiente. Si el alemán tiene éxito pero el japonés falla, la traducción al alemán queda terminada y se entrega con normalidad; la falla no la revierte. El trabajo fallido aparece en el grupo con status: "failed", failedJobs aumenta y el grupo se consolida como partial:

{
  "groupId": "ljg_A1b2C3d4E5f6G7h8",
  "status": "partial",
  "sourceLocale": "en",
  "totalJobs": 3,
  "completedJobs": 2,
  "completedWithWarningsJobs": 0,
  "failedJobs": 1,
  "jobs": [
    { "id": "ljb_A1b2C3d4E5f6G7h8", "targetLocale": "de", "status": "completed", "warnings": [], "completedAt": "2026-03-16T10:30:04.000Z" },
    { "id": "ljb_B2c3D4e5F6g7H8i9", "targetLocale": "fr", "status": "completed", "warnings": [], "completedAt": "2026-03-16T10:30:05.000Z" },
    { "id": "ljb_C3d4E5f6G7h8I9j0", "targetLocale": "ja", "status": "failed", "warnings": [], "completedAt": null }
  ],
  "createdAt": "2026-03-16T10:30:00.000Z"
}

Se entregaron dos idiomas y uno no, y los conteos lo dejan claro sin que tengas que revisar nada. Para reintentar, envía una nueva solicitud con solo los idiomas que fallaron y una nueva clave de idempotencia. La descripción completa del error para un idioma fallido —el errorMessage— vive en el trabajo individual; el grupo te da el conteo y el veredicto.

Siguientes pasos#