単一ジョブを取得

1 つのロケールの翻訳結果と、その生成過程を示すステージ別の記録を取得します。

このエンドポイントを使うのは、すでに jobId を持っているときです。これは create の 202 レスポンスで返されることもあれば、webhook で受け取ることもあり、job group の一覧に含まれることもあります。グループエンドポイントでわかるのは、完了したロケールが いくつ あるか。このエンドポイントでわかるのは、特定の 1 ロケールが 何を 生成したか、そして途中で何が起きたかです。

GET /jobs/localization/:jobId

この違いこそが、このページの要点です。グループレスポンスはスコアボードのようなもので、件数とジョブごとのステータスを返します。詳しくは job group のページをご覧ください。一方、単一ジョブは 1 つのロケールに関する完全な記録 です。翻訳済みの outputData、最終的な status、必要に応じた warnings、そして pipeline が実行したすべてのステージをたどれる steps[] の履歴が含まれます。データベースにドイツ語コピーを書き込む段階になったら、そのドイツ語コピーを受け取るのがこの呼び出しです。

認証#

API キーは X-API-Key ヘッダーで渡します。キーは組織スコープで、その組織内のすべてのエンジンにアクセスできます。詳しくは Authentication を参照してください。

レスポンス#

outputData フィールドは、入力した data の構造をそのまま反映します。文字列の値はすべて翻訳され、文字列以外の値（数値、ブール値、null）はそのまま保持されます。キーもネストも配列順も変わらず、変わるのは文字列だけです。

{
  "id": "ljb_A1b2C3d4E5f6G7h8",
  "groupId": "ljg_A1b2C3d4E5f6G7h8",
  "targetLocale": "de",
  "status": "completed",
  "outputData": {
    "id": "course_101",
    "title": "Einführung in maschinelles Lernen",
    "steps": [
      { "heading": "Was ist ML?", "body": "Maschinelles Lernen ist ein Teilbereich der künstlichen Intelligenz." },
      { "heading": "Überwachtes Lernen", "body": "Trainieren eines Modells mit gelabelten Daten." }
    ],
    "metadata": { "author": "Dr. Smith", "difficulty": "beginner" }
  },
  "errorMessage": null,
  "warnings": [],
  "callbackStatus": "delivered",
  "createdAt": "2026-03-16T10:30:00.000Z",
  "startedAt": "2026-03-16T10:30:01.000Z",
  "completedAt": "2026-03-16T10:30:04.000Z",
  "steps": [
    {
      "stepId": "localize",
      "type": "action",
      "status": "completed",
      "errorMessage": null,
      "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:04.000Z"
    }
  ]
}

上の metadata ブロックは手つかずのまま残っています。Dr. Smith と beginner は文字列ではないリーフ値なので、エンジンは変更していません。返ってきた outputData は送信時と同じ形を保っているため、ペイロードを組み立てたのと同じコードで、そのまま翻訳結果を扱えます。

ジョブステータス値#

ジョブは queued から processing へ進み、その後は必ず 1 つの終端状態に到達します。ほかのフィールドを見る前に、まず status で分岐してください。どのフィールドに値が入るかは、これで決まります。

steps 配列#

steps[] は、単一ジョブのステージ別の実行履歴です。エンジンが実行した各ステージについて、順番どおりに 1 レコードずつ入ります。すべてのジョブには最低でも localize ステップが含まれます。コア翻訳は必ず実行されるためです。有効化した各 pipeline ステージごとに、さらに 1 レコードが追加されます。つまり、追加ステージがなければ localize ステップが 1 つだけ、pre-edit と back-translation を有効にしていれば 3 つのレコードが並びます。

これによって、ジョブはブラックボックスではなく、監査可能なものになります。ステージが実行されたかどうかを信じる必要はありません。記録を見れば、どのステージか（stepId）、それが completed したのか、failed したのか、あるいは skipped されたのか、いくらかかったのか（costUsd）、いつ開始していつ終わったのかまで確認できます。人手によるレビューのステージでは、externalRef* が外部レコードを指します。

"steps": [
  {
    "stepId": "preEdit",
    "type": "action",
    "status": "completed",
    "errorMessage": null,
    "costUsd": 0.0012,
    "createdAt": "2026-03-16T10:30:01.000Z",
    "completedAt": "2026-03-16T10:30:02.000Z"
  },
  {
    "stepId": "localize",
    "type": "action",
    "status": "completed",
    "errorMessage": null,
    "costUsd": 0.0184,
    "createdAt": "2026-03-16T10:30:02.000Z",
    "completedAt": "2026-03-16T10:30:05.000Z"
  }
]

ここで failed エントリがあっても、必ずしもジョブ全体が失敗したことにはなりません。非クリティカルなステージが失敗した場合、その steps[] レコードは failed となり、同じ失敗がジョブ上位レベルの warnings にも現れます。それでもジョブは、完全な outputData を伴ったまま completed_with_warnings に到達します。完全な記録形式、つまり全フィールド、すべての stepId、completed/failed/skipped の意味については、正規の 1 ページである Observe pipeline runs にまとまっています。このページではジョブ内のどこを見るかを示し、詳細な仕様はそちらで定義しています。

完了済みジョブを読む#

一般的な利用側の実装では、まず status で分岐し、成功時には outputData を書き込み、失敗時には errorMessage をログに残します。以下のそのまま使える呼び出しは、上で示したペイロードを返します。

const jobId = "ljb_A1b2C3d4E5f6G7h8";
const response = await fetch(`https://api.lingo.dev/jobs/localization/${jobId}`, {
  headers: { "X-API-Key": process.env.LINGO_API_KEY },
});

const job = await response.json();

switch (job.status) {
  case "completed":
  case "completed_with_warnings":
    // outputData is populated; warnings may carry non-critical stage failures
    await db.content.update({
      where: { id: job.outputData.id },
      data: { [`content_${job.targetLocale}`]: job.outputData },
    });
    if (job.warnings.length) console.warn(job.targetLocale, job.warnings);
    break;
  case "failed":
    console.error(`${job.targetLocale} failed: ${job.errorMessage}`);
    break;
  default:
    // queued or processing - nothing to read yet; also catches future states
    break;
}

このエンドポイントがエラーを返す場合—たとえば未知の jobId やキーの欠落など—は、標準の JSON エラーモデルに従います。詳しくは Errors and status codes を参照してください。

次のステップ#