Skip to Content
Puppi

Runs and assets

Start a run, and read what each asset last did.

A manual run plans the whole active graph. The engine answers before the attempts finish.

Start a run

curl -X POST \
  -H "Authorization: Bearer <api-key>" \
  -H "Content-Type: application/json" \
  -d '{"force": true}' \
  "$PUPPI_ENGINE_URL/api/v1/environments/hello/runs"

202 means the run was accepted. force defaults to false. true bypasses the staleness gate. The body is the run, plus attempts and outcome.

status is running when the run started, or queued when a run of the same plan is already in flight. A trigger that arrives while one is already queued comes back as that queued run.

GET /api/v1/environments/:name/runs lists the newest 100 runs, without attempts. GET /api/v1/runs/:id returns one run with its attempts. Each attempt has id, asset_key, partition, number, status, error_class, error_message, observed_reads, secret_versions, bindings, logs, timings, started_at, finished_at, and quarantined. quarantined is true when the materialization this attempt wrote is quarantined, and false when the attempt wrote none. outcome is the per-asset summary. success and failed_by_check stay distinct.

Follow a run

GET /api/v1/runs/:id/events?after=<seq> returns the events emitted since that cursor. Omit after, or pass 0, to read from the start.

curl -s \
  -H "Authorization: Bearer <api-key>" \
  "$PUPPI_ENGINE_URL/api/v1/runs/$RUN_ID/events?after=0"

$RUN_ID is the id from the 202. The body has status (the run’s status now), next, and events. Pass next as after on the next poll. An empty events list means nothing new arrived; next stays put.

Cancel a run

POST /api/v1/runs/:id/cancel asks the engine to stop the run.

curl -X POST \
  -H "Authorization: Bearer <api-key>" \
  "$PUPPI_ENGINE_URL/api/v1/runs/$RUN_ID/cancel"

200 is the run. A queued run comes back cancelled. A running run stays running with cancel_requested true until every attempt has stopped, then status is cancelled. An attempt that was still running shows cancelling until it stops, then cancelled.

A run that has already finished is 409 {"error": "already_settled"}. Cancelling again while a cancel is in progress is 200.

Each event has seq, at, type, asset_key, number, status, error_class, error_message, rows, duration_ms, and after_run_id. run.started sets after_run_id to the run this one waited behind. attempt.producer_completed sets rows to the producer’s row count. A missing run, or a run in another tenant, is the same 404 as GET /api/v1/runs/:id.

List assets

GET /api/v1/environments/:name/assets returns every asset in the active deployment. Each row has key, definition, latest, latest_attempt, next_run_at, and staleness.

definition includes role, group, visibility, deps, connections, schema, schedule, and code_version. latest is the current materialization, or null. latest_attempt is the newest attempt for that asset across every run, or null. next_run_at is computed from the schedule. It is null while schedules are paused. staleness is one verdict per partition: current, or stale with reasons.

curl -s \
  -H "Authorization: Bearer <api-key>" \
  "$PUPPI_ENGINE_URL/api/v1/environments/hello/assets/core/customer"

The key keeps its slash. The detail adds history, newest first. Each history row has retained: true when the engine still has the data. A rollback to a row that is not retained is 422 data_not_retained.

Staleness

GET /api/v1/environments/:name/staleness returns the same verdicts, one object per asset and partition, with asset_key and partition on each.