---
title: "ジョブ状態ポーリング"
method: GET
path: "/api/v1/jobs/{jobId}"
tags: ["jobs"]
---

# ジョブ状態ポーリング

`GET /api/v1/jobs/{jobId}`

## Request

- Base URL: `https://app.yukkurigen.com`
- URL: `https://app.yukkurigen.com/api/v1/jobs/{jobId}`
- Auth: one of:
  - HTTP bearer
  - HTTP bearer

## Path parameters

- `jobId` string, required

## Response `200`

ジョブの現在状態

- object
  - `jobId` string, required
  - `kind` 'welcome_email' | 'project_audio' | 'bgm_generate' | 'bgm_pipeline' | 'bgm_asset_generate' | 'agent_generate' | 'agent_generate_batch' | 'youtube_upload', required
  - `status` 'queued' | 'running' | 'succeeded' | 'failed', required
  - `projectId` string, nullable: ジョブが作った、または対象にしているプロジェクトの ID（無いジョブは null）
  - `progress` object, nullable
    - `done` number
    - `total` number
  - `result` unknown
  - `error` object, nullable: failed のときの理由。agent_generate の failed は押さえたクレジットの返金を伴う（レンダーの起動後に失敗した場合を除く）。agent_generate_batch の failed は返金を意味しない: バッチのジョブ自体はクレジットを持たず、作り始めた件はそれぞれのジョブで課金されたまま進む
    - `code` string
    - `message` string
    - `httpStatus` number
  - `partialResults` object, nullable: kind が agent_generate_batch で status が failed のときだけ付く（それ以外のジョブには無い）。失敗したバッチは result が null のままなので、各件がどこまで進んだかをここで返す。started と failedWithJob の件は**投げ直さない**（作り始めた件は課金されたまま進む。failedWithJob の課金の扱いはその jobId のジョブで確かめる）。ただし failedWithJob のうち、その件のジョブが失敗して返金された件は冪等キーが空いているので、同じ idempotencyKeyPrefix で全件を送り直すと作り直され、1回課金される（送り直す前にその jobId のジョブを確かめる。child_timeout でまだ動いている件は作り直されない）。投げ直すなら resendIndexes の件だけを、新しい idempotencyKeyPrefix の新しいバッチで送る。inFlight の件（同じ冪等キーの処理が別の呼び出しで進行中だった件）は resendIndexes に入らず、新しい idempotencyKeyPrefix のバッチに入れてはいけない（生きている予約を素通りし、別の呼び出しが作っている動画をもう一度作って払う）。しばらく置いてから、その件だけを同じ冪等キー（<idempotencyKeyPrefix>:<index>、idempotencyKeyPrefix が無ければその件の idempotencyKey）で送り直す。同じ idempotencyKeyPrefix で全件を送り直しても作り始めた件が二重に作られないのは、その件のジョブが終わってから 24 時間以内だけで、その期限を fullResendSafeUntil に入れる（null なら全件の送り直しをしない）。件を読めなかったときは partialResults 自体が null（しばらく置いて再度 GET する。推測で送り直さない）
    - `started` object[]: 作り始めた件。state が created は結果が成功（mp4 はレンダーの開始まで。renderId と projectId を進捗のポーリングに渡す）、running はその件のジョブがまだ動いている（jobId で追う）
      - `index` integer, required
      - `state` 'created' | 'running', required
      - `projectId` string
      - `renderId` string
      - `jobId` string: その件のジョブ（draft の件には無い）
    - `failedWithJob` object[]: 結果は失敗だが、その件のジョブがある件（child_timeout を含む）。返金されたか・まだ動いているかはその jobId のジョブが決める
      - `index` integer, required
      - `status` integer, required
      - `code` string
      - `error` string
      - `projectId` string
      - `jobId` string, required
    - `notCreated` object[]: 結果は失敗で、このバッチがその件のジョブを作っていない件（受け付けで断った件）
      - `index` integer, required
      - `status` integer, required
      - `code` string
      - `error` string
    - `inFlight` object[]: 結果が 409（code: in_flight）で、このバッチがその件のジョブを作っていない件。同じ冪等キーの処理が別の呼び出しで進行中だった（その呼び出しが作って課金している途中）。resendIndexes に入らない。新しい idempotencyKeyPrefix では送らず、しばらく置いてから同じ冪等キーでその件だけを送り直す
      - `index` integer, required
      - `status` integer, required
      - `code` string
      - `error` string
    - `notAttempted` integer[]: まだ作っていない件の index
    - `resendIndexes` integer[]: 新しい idempotencyKeyPrefix の新しいバッチで投げ直してよい件の index（notCreated と notAttempted。inFlight は入れない。昇順）
    - `hadIdempotencyKeyPrefix` boolean: 受け付けに idempotencyKeyPrefix があったか
    - `fullResendSafeUntil` string, date-time, nullable: この時刻までなら、同じ idempotencyKeyPrefix で全件を送り直しても started の件と、まだ動いている failedWithJob の件（child_timeout）は作り直されない（各件の冪等キーの 24 時間から余裕を引いた期限）。failedWithJob のうち、その件のジョブが失敗して返金された件は冪等キーが空いているので、期限内でも全件の送り直しで作り直され、1回課金される（送り直す前にその jobId のジョブを確かめる）。idempotencyKeyPrefix が無い・期限を過ぎた・確かめられないときは null
  - `createdAt` string, date-time, nullable
  - `updatedAt` string, date-time, nullable

## Other responses

- `401`: 未認証（code: unauthenticated）
- `403`: API キーのスコープ不足（projects:read が必要）
- `404`: ジョブが存在しないか他ユーザーのジョブ（列挙防止のため同一 404）

## Changes

- **2026-10-20** `ba5f36b016da`: 15 warning, 9 info
  - added the new `already_subscribed` enum value to the `code` response property for the response status `401`
  - added the new `already_subscribed` enum value to the `code` response property for the response status `403`
  - added the new `already_subscribed` enum value to the `code` response property for the response status `404`
  - added the new `render_not_paid` enum value to the `code` response property for the response status `401`
  - …20 more

[Operation history](https://skmtc.dev/yukkurigen/apis/yukkurigen-ai-operated-api/changes/api/v1/jobs/:jobId/get.md)

---

[API](https://skmtc.dev/yukkurigen/apis/yukkurigen-ai-operated-api.md) · [All operations](https://skmtc.dev/yukkurigen/apis/yukkurigen-ai-operated-api/llms.txt) · [OpenAPI document](https://skmtc.dev/yukkurigen/apis/yukkurigen-ai-operated-api/revisions/ba5f36b016da?raw)