Webhooks und der Live-WebSocket informieren dich über einen Job genau in dem Moment, in dem er abgeschlossen ist. Doch am nächsten Morgen, nach einem Deployment oder wenn du alle Sprachen sehen willst, die in der letzten Stunde fehlgeschlagen sind, helfen dir beide nicht weiter. Der Moment ist vorbei, das Ereignis weg. Die Jobs nicht – jeder einzelne bleibt als dauerhafter Datensatz auf der Plattform erhalten, lange nachdem der einreichende Prozess schon weitergelaufen ist.
GET /jobs/localization gibt dir genau diesen Rückgriff auf die Datensätze. Es liefert deine Jobs in absteigender Reihenfolge, seitenweise per Cursor, gefiltert nach der Engine, auf der sie gelaufen sind, oder nach dem Status, mit dem sie beendet wurden. Das ist dein Kanal zum Nachfassen: der dauerhafte Datensatz, den du abfragst, wenn du nicht live dabei warst.
GET /jobs/localizationNeu bei asynchroner Lokalisierung? Starte mit dem Überblick. Diese Seite setzt voraus, dass du bereits Jobs zum Durchsehen hast. Wie jeder Endpunkt authentifiziert auch dieser sich mit deinem X-API-Key.
Filter und Paginierung#
GET /jobs/localization?engineId=eng_abc123&status=completed&limit=20&cursor=...| Parameter | Typ | Beschreibung |
|---|---|---|
engineId | string (optional) | Gib nur Jobs zurück, die auf dieser Lokalisierungs-Engine gelaufen sind (eng_...). |
status | string (optional) | Gib nur Jobs in diesem Status zurück: queued, processing, completed, completed_with_warnings oder failed. |
limit | number (optional) | Seitengröße. Standardmäßig 20, maximal 100. |
cursor | string (optional) | Ein undurchsichtiger Cursor aus dem nextCursor der vorherigen Antwort. Für die erste Seite lässt du ihn weg. |
Beide Filter sind optional und lassen sich kombinieren: engineId=eng_abc123&status=failed liefert die fehlgeschlagenen Jobs für eine Engine – und nichts sonst. Genau diese Kombination beantwortet eine Frage, die du dir im Incident-Fall tatsächlich stellst – zeig mir alles, was auf dieser Engine fehlgeschlagen ist – ohne dafür erst jeden Job in der gesamten Organisation abrufen und clientseitig filtern zu müssen.
Der cursor ist eine Position im Ergebnisstrom, keine Seitenzahl. Du berechnest ihn nicht, du bekommst ihn. Jede Antwort liefert dir einen nextCursor, und genau diesen Wert gibst du zurück, um die darauffolgende Seite abzurufen.
Antwort#
Jede Seite besteht aus einem items-Array plus einem nextCursor. nextCursor ist auf der letzten Seite null – das ist die Abbruchbedingung deiner Schleife, kein Fehler.
{
"items": [
{
"id": "ljb_C3d4E5f6G7h8I9j0",
"groupId": "ljg_A1b2C3d4E5f6G7h8",
"targetLocale": "ja",
"status": "completed",
"warnings": [],
"createdAt": "2026-03-16T10:30:00.000Z",
"completedAt": "2026-03-16T10:30:06.000Z"
}
],
"nextCursor": "eyJ0IjoiMjAyNi0wMy0xNlQxMDozMDowMC4wMDBaIiwiaSI6ImxqYl9CMmMzRDRlNUY2ZzdIOGk5In0"
}Jeder Eintrag ist eine Zusammenfassung – genug, um einen Job zu finden und sein Ergebnis zu erfassen: welche Sprache, welche Gruppe, welcher Status, wann er erstellt wurde und wann er abgeschlossen war. Die übersetzte Ausgabe ist bewusst nicht enthalten. Wenn du die vollständigen outputData und die steps pro Phase für einen dieser Jobs abrufen willst, nimm seine id und rufe Einzelnen Job abrufen auf. Die Liste ist zum Finden da, der Abruf zum Lesen.
Unbekannte Statuswerte robust behandeln
Prüfe auf die Statuswerte, die du kennst, und falle für alle anderen auf einen Standardzweig zurück, statt den Consumer bei einem unbekannten Wert abstürzen zu lassen. Einen nicht erkannten Wert zu tolerieren, ist die defensive Standardeinstellung für jedes String-Enum, das du nicht kontrollierst – so bleibt dein Reader funktionsfähig, statt bei Eingaben einen Fehler zu werfen, die er nicht einordnen kann.
Durch alle Ergebnisse blättern#
Genau darum geht es bei der Abbruchbedingung: Stelle so lange Anfragen, bis nextCursor als null zurückkommt. Übergib den nextCursor aus einer Antwort als cursor in der nächsten, und die Schleife endet von selbst.
async function listFailedJobs(engineId) {
const failed = [];
let cursor = undefined; // first page: no cursor
do {
const url = new URL("https://api.lingo.dev/jobs/localization");
url.searchParams.set("engineId", engineId);
url.searchParams.set("status", "failed");
url.searchParams.set("limit", "100"); // fewer round-trips
if (cursor) url.searchParams.set("cursor", cursor);
const response = await fetch(url, {
headers: { "X-API-Key": process.env.LINGO_API_KEY },
});
const { items, nextCursor } = await response.json();
failed.push(...items);
cursor = nextCursor; // null on the last page -> loop ends
} while (cursor);
return failed; // every failed job for this engine
}Wenn du limit auf 100 erhöhst, reduzierst du bei einem großen Backlog die Zahl der Round-Trips. Am Ergebnis ändert das nichts – nur daran, wie viele Seiten du durchlaufen musst, um es zu lesen. Es gibt keinen Offset, der verrutschen kann, und keine Seitenzahl, die du synchron halten musst – der Cursor markiert deine Position, und null sagt dir, wann du alles gelesen hast.
Nächste Schritte#
Du hast die id eines Jobs. Der Kanal zum Nachfassen hat dich bis hierhergebracht; ab hier liest du das Ergebnis aus – oder du verdrahtest die Live-Kanäle, damit du es beim nächsten Mal direkt mitbekommst, während es passiert.
