Bulk queue finished_at: measure the wall time of a 100-item batch

Sume sets finished_at on a bulk queue when its status becomes completed, which means every item is terminal. The gap from created_at to finished_at is the wall time of your batch. It is not a success measure: completed does not mean every item succeeded, so read counts.failed and counts.canceled too.

The fields

A queue receipt carries created_at, updated_at and finished_at as ISO-8601 timestamps. finished_at stays null until the queue completes. Poll status_url with backoff; each child is minutes of work for video, so polling every second gains nothing and uses read budget.

Using the number honestly

Wall time depends on the window, on workspace generation concurrency, and on how long each run takes, which varies by Format. One batch is one data point, so do not publish a rate from it.

• Record finished_at - created_at with the concurrency you asked for, the item count and the Format version.
• Separate the time of failed items; a failed item that never started frees its slot immediately and can make a batch look quick.
• If you cancel a child, the queue marks it canceled and the next item starts.

Reading the result with the timing

After finished_at appears, fetch each child by run_id and record its own status and spend. A queue that finished fast with several failed items is a different story from one that finished slowly with all items completed.

The receipt usage on each child gives the generation spend, and GET /v1/usage stays the billing record, so use it, not your own sum, for invoices.

For a client report, quote the facts you measured, such as the item count, the concurrency setting and the elapsed time, and avoid projecting them onto a different Format or a bigger catalog without a new pilot.

Tradeoff

The queue has no publicly documented position or depth field, so you cannot predict finish time from a single poll. Treat wall time as a result to log, not a promise to give a client.