Job 목록 API: 상태별 영상 Job 필터링과 잃어버린 ID 복구

Sume API로 Job 목록을 보려면 GET /v1/jobs를 호출하세요. 선택적으로 status(queued, processing, completed, failed, canceled 중 하나), type, run_id, 그리고 1–100 사이의 limit을 붙일 수 있습니다. 결과는 최신순으로 오며, data.next_cursor가 있으면 그 값을 starting_after로 다시 넘겨 다음 페이지를 읽으세요.

이 경로는 Sume 문서 API 레퍼런스에 있고, 쿼리 파라미터와 행 필드는 라이브 OpenAPI 레퍼런스에 정의되어 있습니다. 모두 2026-09-26에 확인했습니다. 생성 요청을 안전하게 다시 보내는 것은 다른 문제로, AI 영상 API 멱등성 키에서 다룹니다. 이 글은 이미 만든 Job을 찾는 방법을 다룹니다.

GET /v1/jobs는 어떤 필터를 받나요?

목록은 인증된 워크스페이스의 Job을 대상으로 합니다. 알 수 없는 쿼리 파라미터를 보내면 필터가 조용히 빠진 페이지가 아니라 400 unknown_parameter가 돌아오므로, 오타 때문에 모든 Job을 받게 되는 일은 없습니다.

모든 Job을 페이지별로 어떻게 읽나요?

행은 data.jobs에 최신순으로 담깁니다. data.next_cursor는 불투명한 커서로, 남은 Job이 더 있을 때만 있습니다. 이 값을 starting_after로 다시 넘기세요. 마지막 페이지에는 커서가 없으며, 이것이 루프의 종료 조건입니다. 마지막 Job으로 커서를 직접 만들지 마세요.

URL="https://api.sume.com/v1/jobs?status=failed&limit=100"
CURSOR=""
while :; do
  PAGE=$(curl -sS "$URL${CURSOR:+&starting_after=$CURSOR}" \
    -H "Authorization: Bearer $SUME_API_KEY")
  echo "$PAGE" | jq -r '.data.jobs[] | [.id, .status, .idempotency_key] | @tsv'
  CURSOR=$(echo "$PAGE" | jq -r '.data.next_cursor // empty')
  [ -z "$CURSOR" ] && break
done

비정상 종료 뒤 Job ID는 어떻게 복구하나요?

모든 제출 응답에서 Job ID를 저장하세요. 클라이언트 연결이 끊기거나 로컬에서 타임아웃되면 ID를 보관한 채, 유료 작업을 중복 제출하는 대신 Jobs API로 복구하세요. 로컬 타임아웃은 Job을 취소하지 않으며, Job은 계속 실행되고 계속 과금됩니다.

• idempotency_key로 매칭하세요. 각 행에는 생성할 때 쓴 Idempotency-Key가 담기며, 보내지 않았다면 null입니다. 한 묶음(wave)을 재시도하고 나면 최신순이 제출 순서와 달라지므로, 배열 위치로 Job을 식별하지 말고 여러분의 키를 id에 대응시키세요.
• status=queued와 status=processing을 나열해 아직 진행 중인 작업을 찾고, 각 ID의 폴링을 이어 가세요. 영상 생성 Job 폴링하는 방법을 참고하세요.
• status=failed를 나열해 실패한 Job을 모으고, 각 행의 error를 읽으세요.
• ID를 저장하기 전에 제출 응답을 잃었다면, 같은 Idempotency-Key로 제출을 재시도할 때 두 번째 Job이 과금되는 대신 원래 Job이 돌아옵니다.

각 Job 행에는 무엇이 들어 있나요?

모든 행은 GET /v1/jobs/{id}가 반환하는 것과 같은 공개 Job 스키마를 쓰므로, 결과와 오류도 함께 옵니다.

• id, type, status, model이 있습니다. model에는 가능한 경우 Sume가 소유한 공개 모델 ID가 담기며, 내부 프로바이더 모델 ID는 절대 담기지 않습니다.
• idempotency_key와 communication_mode(async, sync, subscribe, webhook 중 하나)가 있습니다.
• created_at, updated_at, started_at, completed_at, canceled_at이 있습니다.
• result, error, usage_summary(원장 행이 있을 때 그 Job의 예약, 확정, 환불), webhook_delivery가 있습니다.

Format, Action, Agent 실행도 같은 방식으로 나열할 수 있나요?

/v1/jobs로는 안 됩니다. Action은 Job이 아니어서 그 목록에 나타나지 않고, Format에는 자체 실행 리소스가 있습니다. Format과 Action의 실행 목록은 페이지를 넘기는 방식도 다릅니다. has_more가 false가 될 때까지 next_cursor를 cursor로 다시 넘기세요.

• Format 실행: GET /v1/formats/{handle}/{slug}/runs입니다. 최신순이며 limit은 1–100(기본값 20)입니다. 여러 Format에 걸친 GET /v1/format-runs 목록은 없습니다.
• Scheduled(Action) 실행: GET /v1/actions/{action_id}/runs입니다. limit은 1–100(기본값 50)입니다.
• Agent Completions: GET /v1/agent-runs가 completion을 최신순으로 나열합니다.
• 코드 밖에서는 Jobs 대시보드가 최근 Developer API Job을 보여 주고, CLI의 sume jobs list와 sume jobs get <job_id>도 같은 Job을 읽습니다. 둘이 어떻게 나뉘는지는 Sume Job과 실행의 차이에서 설명합니다.