Has creado un grupo, has recibido un groupId y ahora varios idiomas se están traduciendo en paralelo. Necesitas responder una misma pregunta, una y otra vez, hasta que el trabajo termine de asentarse: ¿cómo va ahora mismo el envío completo? No idioma por idioma, sino el conjunto. Cuántos han terminado, cuántos han generado salida con advertencias, cuántos han fallado y cuántos siguen en curso.
Eso es exactamente lo que devuelve este endpoint. Una sola consulta, el estado de todos los idiomas, en una única respuesta. ¿Aún no conoces la localización asíncrona? Empieza por la Descripción general de la API de localización asíncrona.
En esta página
Obtener un grupo de trabajos#
Recupera el estado de un grupo de trabajos y de todos sus trabajos secundarios.
GET /jobs/localization/groups/:groupIdAutentícate con tu clave de API en la cabecera 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 del envío completo: el status del propio grupo, cuatro recuentos 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 recuento de trabajos terminales —completedJobs, completedWithWarningsJobs y failedJobs— suman el número de idiomas que ya han terminado. El resto de totalJobs siguen en estado queued o processing. En la instantánea anterior, 1 de 3 ha terminado y 2 siguen en curso, así que una sola lectura de los recuentos te dice que el trabajo aún no se ha resuelto sin necesidad de revisar el array jobs. Cuando esa suma alcanza totalJobs, el grupo ha llegado a un estado terminal.
El array warnings de cada trabajo muestra fallos no críticos en etapas opcionales del pipeline; por ejemplo, un paso de preedición o de retrotraducción que no llegó a completarse. Un array no vacío significa que el trabajo sí generó salida, pero que al menos una etapa opcional no terminó. El outputData traducido vive en el trabajo individual; recupéralo cuando estés listo para consultar el contenido finalizado de un idioma.
Estados del grupo#
El status del grupo resume sus trabajos secundarios en un único valor. Debes consultar hasta que alcance un estado terminal.
| Estado del grupo | Significado |
|---|---|
pending | Grupo creado; aún no se ha iniciado ningún trabajo |
processing | Hay al menos un trabajo en curso |
completed | Todos los trabajos se completaron correctamente |
completed_with_warnings | Todos los trabajos generaron salida, pero una o más etapas opcionales del pipeline fallaron en al menos uno de ellos |
partial | Algunos trabajos se completaron y otros fallaron |
failed | Todos los trabajos fallaron |
La diferencia entre completed, completed_with_warnings y partial es precisamente la razón de ser 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.
Frecuencia de consulta#
Intervalo de sondeo
Para la mayoría de los trabajos, el procesamiento tarda entre 2 y 8 segundos por idioma. Si haces sondeo en lugar de usar webhooks o WebSocket, un intervalo de 2 segundos es un buen punto de partida.
El sondeo es la forma más sencilla de hacer seguimiento de un grupo y, para un lote de corta duración, encaja perfectamente. Pero también es la opción más limitada, y conviene decirlo claramente: cada consulta implica un viaje de ida y vuelta aunque no haya cambiado nada, y solo te enteras de que un idioma ha terminado en el siguiente intervalo, no en el mismo momento en que ocurre.
Si quieres cada resultado en el mismo instante en que esté listo, no hagas sondeo: deja que te lo comuniquen. La plataforma entrega cada idioma completado a tu URL de webhook en cuanto termina, y una conexión WebSocket del grupo envía una instantánea completa del estado con cada cambio, para que tu interfaz 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; opta por el envío por eventos cuando la latencia en tu interfaz importe.
Cuando falla un idioma#
Si lees "traducir a muchos idiomas a la vez" con cierto escepticismo, la primera pregunta es obvia: ¿qué pasa con el resto cuando falla un idioma? Aquí tienes 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; el fallo no la revierte. El trabajo fallido aparece en el grupo con status: "failed", failedJobs aumenta y el grupo pasa a 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 recuentos lo dejan claro sin que tengas que revisar nada. Para reintentarlo, envía una nueva solicitud solo con los idiomas fallidos y una nueva clave de idempotencia. La descripción completa del error de un idioma fallido —el errorMessage— está en el trabajo individual; el grupo te da el recuento y el veredicto.
Los fallos parciales son un estado normal
partial significa exactamente lo que muestran los recuentos: algunos idiomas se completaron y otros fallaron. Los idiomas completados ya se han entregado. No hay nada que revertir ni ningún coste duplicado en los idiomas que tuvieron éxito: solo reintentas los que fallaron.
