List jobs API: filter video jobs by status and recover lost job ids

To list jobs with the Sume API, call GET /v1/jobs with an optional status (queued, processing, completed, failed, or canceled), type, run_id, and a limit of 1–100. Results come newest first; when data.next_cursor is present, pass it back as starting_after to read the next page.

The route is in Sume's API reference docs; its query parameters and row fields are defined in the live OpenAPI reference, read on 2026-09-26. Replaying a create safely is a different problem, covered in idempotency keys for AI video APIs; this post finds jobs you already created.

Which filters does GET /v1/jobs accept?

The list covers the authenticated workspace's jobs. An unrecognized query parameter is a 400 unknown_parameter, not a silently unfiltered page, so a typo cannot hand you every job.

How do I page through every job?

Rows arrive in data.jobs, newest first. data.next_cursor is an opaque cursor that is present only when more jobs remain. Pass it back as starting_after. It is absent on the last page, which is your loop terminator; do not build a cursor from the final job yourself.

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

How do I recover job ids after a crash?

Store the job id from every submit response. If a client disconnects or times out locally, keep the id and recover with the jobs API instead of submitting duplicate paid work; a local timeout does not cancel the job, which keeps running and still bills.

• Join on idempotency_key. Each row carries the Idempotency-Key it was created with, or null when none was sent. Newest first is not your submission order once a wave retries, so map your own key to id rather than reading identity off array position.
• List status=queued and status=processing to find work still in flight, then resume polling each id; see how to poll a video generation job.
• List status=failed to collect failures, and read each row's error.
• If a submit response was lost before you stored the id, retrying the submit with the same Idempotency-Key returns the original job instead of billing a second one.

What does each job row contain?

Every row uses the same public job schema that GET /v1/jobs/{id} returns, so result and error come with it:

• id, type, status, and model: the Sume-owned public model id when available, never an internal provider model id.
• idempotency_key and communication_mode (async, sync, subscribe, or webhook).
• created_at, updated_at, started_at, completed_at, and canceled_at.
• result, error, usage_summary (the job's reservation, capture, or refund when a ledger row exists), and webhook_delivery.

Can I list Format, Action, and Agent runs the same way?

Not through /v1/jobs. Actions are not jobs and do not appear there, and Formats have their own run resource. Format and Action run lists also page differently: pass next_cursor back as cursor until has_more is false.

• Format runs: GET /v1/formats/{handle}/{slug}/runs, newest first, limit 1–100 (default 20). There is no cross-Format GET /v1/format-runs list.
• Scheduled (Action) runs: GET /v1/actions/{action_id}/runs, limit 1–100 (default 50).
• Agent Completions: GET /v1/agent-runs lists completions, newest first.
• Outside your code, the Jobs dashboard shows recent Developer API jobs, and the CLI's sume jobs list and sume jobs get <job_id> read the same jobs. Sume jobs vs runs explains the split.