2026-09-26Developers

Sume request_id vs job_id vs run_id: which ID to store and quote

Store the job or run id, dedupe webhooks on job_id or the run envelope's request_id, and quote the req_ request id with the job or run id to Sume support.

5 min readSume

All posts

In the Sume API, job_id and run_id name the work you started, while a req_… request id names one HTTP response and arrives on every response as the x-sume-request-id header. Store the job or run id, dedupe webhooks on job_id for jobs and on the envelope's request_id (which equals run_id) for runs, and quote the req_… id together with the job or run id when you contact support.

The field name request_id is the trap: its value depends on where it appears. The meanings below come from Sume's Errors and rate limits, Jobs and results, and Run webhooks docs and the Sume API reference, read on 2026-09-26.

What does request_id mean in each place?

Read it by where it appears. A value that starts req_ is an HTTP correlation id, never a job id.

From Errors and rate limits, Run webhooks, and the Sume API reference, read 2026-09-26.
Where	Value	Use it for
`error.request_id`, `x-sume-request-id` header	`req_…`, an HTTP correlation id, not a generation job id	Support and logs
`request_id` on a job submit response	The job id	Store it; poll `/v1/jobs/{id}`
`request_id` and `job_id` in a job webhook	Both the job id, `job_…`	Dedupe on `job_id`
`request_id` in a run webhook envelope	Equals `run_id`; stable across retries	Dedupe on it
`request_id` on a run receipt	A correlation id: `req_…` when read with `GET`, the run id inside a webhook `payload`	Log it; do not dedupe on it
`request_id` on a usage row	The job or request id, when the row is tied to a job	Join usage to jobs

Which id should I store?

The id of the work. Every job submit mode returns the job id in its first response: as request_id on the submit envelope, or as id from POST /v1/videos. A Format run's id is data.id on the create receipt, an arun_… value; the embed cookbook says to store it against your record before you return to the browser.

If your process disconnects or times out, keep that id and recover through the jobs or run routes instead of submitting duplicate paid work.

Which id should I dedupe webhooks on?

Retries repeat the dedupe id, so key your insert-or-ignore on it:

Job webhooks: job_id. The docs name it the idempotency key on your side, and Redeliver repeats the real event.
Run webhooks: the envelope's request_id, which equals run_id. Ignore the nested payload.request_id, and order deliveries by created_at, since request_id repeats on every retry.
Test deliveries: a webhook.test event carries a req_wh_test_… request id and no job_id or run id. It is not a real event.

{
  "event": "job.completed",
  "request_id": "job_…",
  "job_id": "job_…",
  "status": "OK",
  "payload": {
    "artifacts": [
      { "id": "artf_…", "url": "https://media.sume.com/artifacts/…", "type": "image" }
    ]
  }
}

Which ids do I send to Sume support?

Quote the request id with the job or run id and the error.code, and leave out keys and secrets, as Sume API errors and rate limits lists. Where to find each id:

A failed HTTP call: the x-sume-request-id header or error.request_id, a req_… value.
The TypeScript SDK: requestId on SumeApiError and on SumeRunRequestError. waitForJob throws SumeJobRequestError, which carries jobId instead.
A Format run: the receipt's own request_id, which the docs call what support asks for, next to its arun_… id.
A webhook that will not verify: the x-sume-webhook-secret-fingerprint value, the one part safe to paste into a ticket; debugging Sume webhook delivery covers the other checks.

How do I match usage rows to a job or run?

Filter GET /v1/usage by job_id or run_id to sum what one generation job, or one Format, Action, or Agent run, cost. Each ledger row's request_id is the Sume job or request id when the row is tied to a job, and rows also carry run_id and turn_job_id, the agent turn that commissioned the job. Sume jobs vs runs explains how runs and jobs relate.

Sources

Written by Sume