Scheduled run missing from /v1/jobs? Read /v1/action-runs instead

A Sume scheduled agent run is not a generation job, so it never shows up in /v1/jobs. Read it at /v1/action-runs/{run_id}. The two objects have different ids, statuses and result shapes, and a poller written for one will misread the other. The jobs a run commissions along the way are a separate matter from the run itself.

How do a schedule run and a job differ?

A run does not use the job lifecycle described on the jobs page. It is saved instructions executed by an Agent in a new thread, possibly across several generations. A job is one model invocation.

Why do the status words not transfer?

The Action vocabulary spells it canceled with one l, and it is a remapping of internal statuses: done surfaces as completed, error as failed, and cancelled as canceled. Do not assume job-side status strings transfer. A schedule run can also end skipped, which has no job equivalent: it means another run was already active.

The poll payload is built for loops. GET /v1/action-runs/{run_id}/status returns the status, timestamps, cancelable and a next_action to branch on: poll_status while queued or processing, retry_later for skipped, and none for every terminal run.

How do I read the finished result?

GET /v1/action-runs/{run_id}/result returns the full receipt, but only once the run is terminal. Before that it answers 409 run_not_completed with the current status in details.status. The receipt's output is projected onto your schema or the built-in sume/action-run-output/v1, artifacts lists the media, and usage carries the generation figures.

events_url on a run receipt is always null: there is no public events route, so no receipt asks you to inspect one.

STATUS=$(curl -sS "https://api.sume.com/v1/action-runs/$RUN_ID/status" \
  -H "Authorization: Bearer $SUME_API_KEY" | jq -r '.data.next_action')
case "$STATUS" in
  poll_status) echo "still working: poll again with backoff" ;;
  retry_later) echo "skipped: another run was active" ;;
  none) curl -sS "https://api.sume.com/v1/action-runs/$RUN_ID/result" \
          -H "Authorization: Bearer $SUME_API_KEY" | jq '.data.primary_output_url' ;;
esac

What about the jobs a run starts?

A run may commission generation jobs while it works, and those are billed through the same wallet. For cost, the usage endpoint accepts a run_id, so you can total one run without reading job rows yourself. Keep the two id families apart in your logs: arun_… for runs, job ids for jobs.

What should my monitoring watch?

Alert on the run, not on the absence of a job. A schedule that fired and finished leaves a run receipt and no /v1/jobs row of its own, so a dashboard built on the jobs list will look empty on a healthy day. Watch for runs that end failed or skipped instead: list a schedule's runs with GET /v1/actions/{action_id}/runs, and page with next_cursor. A cursor Sume did not mint is rejected with 400 invalid_request, so persist the cursor exactly as returned.