Runs & Steps

Run lifecycle

Every run goes through a state machine:

queued → running → completed
                 → failed
                 → cancelled
                 → budget_exceeded

queued — the run is in the work queue, waiting for a worker to pick it up
running — a worker is actively executing steps
completed — the agent produced a final response
failed — an unrecoverable error occurred
cancelled — the run was cancelled via the API or dashboard
budget_exceeded — the run hit its cost limit

What is a step?

A step is the smallest unit of execution. There are three types:

Tool call step

The LLM decided to call a tool. The step records:

Which tool was called
The input parameters
The tool's output
Tokens used and cost

Response step

The LLM produced a final text response. This is typically the last step in a successful run.

Error step

Something went wrong — a tool threw an exception, the LLM returned an invalid response, or an infrastructure error occurred.

Step numbering

Steps are indexed starting at 0. A run with max_steps: 10 will execute at most 10 steps (indices 0–9). If the agent hasn't produced a final response by step 9, the run ends.

Tracking

Every run records:

Field	Description
`current_step`	The index of the last completed step
`total_input_tokens`	Cumulative input tokens across all steps
`total_output_tokens`	Cumulative output tokens across all steps
`total_cost_cents`	Cumulative cost in cents (integer math)
`started_at`	When the first step began
`completed_at`	When the run reached a terminal state

Callback URL

When triggering a run, you can include an optional callback_url. When the run reaches any terminal state (completed, failed, cancelled, or budget_exceeded), Papayya will POST the run result to that URL. This eliminates polling and is ideal for queue-worker architectures where you want to fire-and-forget.

POST /v1/runs
{
  "agent_id": "...",
  "input": "...",
  "callback_url": "https://your-api.com/run-complete"
}

The callback payload includes: run_id, status, current_step, token counts, cost, error details, and timestamps. Retried up to 3 times with exponential backoff. Callback failures never affect the run itself.

Viewing runs

Dashboard — the Runs page shows all runs with status, timing, and cost
CLI — papayya status <task-id> and papayya logs <task-id>
API — GET /v1/runs and GET /v1/runs/{runId}/steps

Overview Triggers