Is there an endpoint to list all Format runs? No, build an index

There is no endpoint that lists every Format run across your account: GET /v1/format-runs does not exist. You can list the runs of one Format with a cursor, and you can fetch a run by id, so the answer is to keep your own index of run ids.

This is a deliberate shape of the API, not a gap you can route around. Plan for it before your first production run, because the id of the run you did not save is the one you will need on a Friday evening.

The reason this matters in practice is cost and support. Every run can spend money, and when someone asks what ran last night, a list you own answers in one query while a hunt across Formats takes an afternoon.

What does exist

Per Format, you can page through runs with a limit from 1 to 100 (default 20) and a cursor. The response returns next_cursor and has_more. A run is fetched by its own receipt URLs: status_url, result_url, events_url, and cancel_url. See Format runs.

Two routes people try do not exist: GET /v1/formats/{h}/{s}/runs/{id} and a /messages route. The receipt URLs from the 202 response are the stable way back to a run.

The cursor is opaque. Pass next_cursor back unchanged and stop when has_more is false; do not try to construct one. A limit of 100 is the largest page, so a Format with 2,000 runs is 20 requests.

What to write at create time

Save a row the moment you get the 202. You have everything you need in the receipt and in your own request. For a bulk queue, save the frq_ queue id and each item's index and run_id as the queue reports them. The Bulk runs page describes the queue shape.

Store the idempotency key you sent too. The input you sent does not round-trip into the structured output, so your own row is the only place that links a business record, such as an order or a product, to a run.

Backfilling a lost index

If you lost rows, page each Format you use with the cursor and rebuild from the receipts. Do it once, in a script, at a modest pace; reads get 40 times the write budget on every plan, so a backfill will not hurt your create traffic, but there is no reason to hammer the API. Plans give writes per minute of 120 on Free, 300 on Pro, 600 on Startup, and 1200 on Scale.

The same rule for scheduled runs

Scheduled runs use a separate wire namespace, /v1/actions, with receipts at /v1/action-runs/{id}. Do not expect a Format-run listing to include them. Keep a second index key, or a source column, so your dashboard can tell the two apart.

The habit is simple: the run id is the primary key of your side of the integration, and it is written before anything else happens.

A tip for dashboards: store the terminal timestamp as well. Status values are queued, processing, completed, failed, canceled, and skipped, and a view of runs by day and status is the first report finance and support both ask for.