Sume job status: queue.state, a null position, worker_heartbeat

On a Sume job status, queue.position is null until Sume computes a real queue rank, and the OpenAPI schema says the API does not return fake queue positions. The queue object still tells you something useful: a state, a provider-neutral reason, the earliest available_at, and a worker_heartbeat liveness summary. A queued job with a null position is normal; keep polling.

Field names and descriptions come from the JobStatusResponse schema in the OpenAPI file; the no-position boundary is stated on Generation admission. Both read 2026-10-02.

What is in the queue object?

GET /v1/jobs/{id}/status returns the queue object next to the flat status, sume_status, terminal, and result_ready fields. A top-level queue_position is also required in the response and is null for the same reason.

What does worker_heartbeat tell me?

runtime.worker_heartbeat is described as a provider-neutral worker liveness summary. It carries status (fresh, stale, or missing), last_seen_at, and stale_after_seconds. Raw worker identifiers and internal topology are not exposed.

The schema does not say what to do on stale or missing, so treat it as a diagnostic, not a trigger to resubmit. Resubmitting a paid job because a status looks slow is the one action the docs rule out: do not resubmit the original paid request just because a local process timed out.

Why can a job wait in queued at all?

Concurrency is a dispatch limit, not a submit limit. A workspace already at its processing limit can still be accepted into queued while queue capacity remains, and workers move jobs to processing later. Free is 1 concurrent with a queue capacity of 5; Pro is 4 with 20, according to the plan table on the admission page, and the dashboard Concurrency tab is the source of truth for your workspace.

Sume exposes queue counts and remaining accepted capacity, not a precise per-job queue position or ETA. If you need a number, read generation_limits on a submit response: queued_generation_jobs, active_generation_jobs, and queue_capacity_remaining.

What should a poller do with a long queue?

Keep the loop boring; none of these steps need a resubmit.

• Treat queued and processing as normal non-terminal states and poll with backoff until terminal is true.
• Sleep for next_poll_after_seconds when it is present; it is the suggested minimum delay before the next poll.
• Read events_url if a job seems stuck; events are the public timeline for debugging and recovery.
• If you need to give up, cancel while cancelable is true. A client-side timeout does not cancel the job, which keeps running and billing.
• When asking for help, send the request_id from the error body or the x-sume-request-id header, not your API key.