List Agent Run Steps

Beta

GET

https://api.speechify.ai/v1/agents/:agent_id/runs/:run_id/steps

GET

/v1/agents/:agent_id/runs/:run_id/steps

curl https://api.speechify.ai/v1/agents/agent_01jqr8x9zg5k2m3n4p5q6r7s8t/runs/arun_01kr410dd3yrst4chn5kn0t78f/steps \
     -H "Authorization: Bearer <token>"

{
  "next_cursor": "string",
  "has_more": true,
  "steps": [
    {
      "seq": 1,
      "kind": "plan",
      "created_at": "2024-01-15T09:30:00Z",
      "content": "string",
      "tool": "store_query",
      "args": {
        "collection": "news",
        "store_id": "store_01kr41f8m2p7q3v9x0y1z2a3b4"
      },
      "delegation": {
        "child_run_id": "arun_01kr410dd3yrst4chn5kn0t78f",
        "agent_id": "agent_01jqr8x9zg5k2m3n4p5q6r7s8t",
        "depth": 1,
        "child_status": "succeeded",
        "batch_size": 3,
        "batch_index": 0
      },
      "files": [
        {
          "id": "file_01jqr8x9zg5k2m3n4p5q6r7s8t",
          "filename": "invoice-2026-09.pdf",
          "content_type": "application/pdf",
          "size_bytes": 1,
          "kind": "ephemeral",
          "content_path": "/v1/files/file_01jqr8x9zg5k2m3n4p5q6r7s8t/content",
          "created_at": "2024-01-15T09:30:00Z",
          "project_id": "proj_01jqr8x9zg5k2m3n4p5q6r7s8t",
          "user_identity": "string",
          "path": "reports/q3.html",
          "source": {
            "run_id": "arun_01jqr8x9zg5k2m3n4p5q6r7s8t",
            "step": 1
          },
          "expires_at": "2024-01-15T09:30:00Z"
        }
      ],
      "duration_ms": 1,
      "model": "gpt-5.6-terra",
      "input_tokens": 1,
      "cached_input_tokens": 1,
      "output_tokens": 1,
      "total_tokens": 1
    }
  ]
}

List a run’s step journal: the append-only plan-act-observe trail the durable runtime leaves behind, in order (seq ascending). Each step is one iteration of the loop - a plan (the agent’s rationale), a tool_call (the tool and its arguments), or an observation (the tool’s result). The run’s final answer is not a step; it lives on the run object (getRun). Use this to render or audit exactly what a run did between its instruction and its result.

Credential-shaped values in a step’s arguments and content are redacted.

The journal is kept for 90 days, after which an older run returns an empty list here. The run itself is not deleted with it: its instruction, answer and usage stay on the run object indefinitely. Export the trail if you need it beyond that window.

This endpoint is in beta: it is available to workspaces granted durable_runs_access, and every other workspace receives 402 durable_runs_not_in_plan.

List a run's **step journal**: the append-only plan-act-observe trail the durable runtime leaves behind, in order (`seq` ascending). Each step is one iteration of the loop - a `plan` (the agent's rationale), a `tool_call` (the tool and its arguments), or an `observation` (the tool's result). The run's final answer is not a step; it lives on the run object (`getRun`). Use this to render or audit exactly what a run did between its instruction and its result. Credential-shaped values in a step's arguments and content are redacted. **The journal is kept for 90 days**, after which an older run returns an empty list here. The run itself is not deleted with it: its instruction, answer and usage stay on the run object indefinitely. Export the trail if you need it beyond that window. This endpoint is in beta: it is available to workspaces granted `durable_runs_access`, and every other workspace receives `402 durable_runs_not_in_plan`.

Authentication

AuthorizationBearer

Enter your API key with the Bearer prefix, e.g. ‘Bearer sk_…’.

Path parameters

agent_idstringRequired

Agent id (prefixed external id, agent_...).

run_idstringRequired

Run id (prefixed external id, arun_...).

Query parameters

cursorstringOptional

Opaque pagination cursor from a previous response.

limitintegerOptional1-200Defaults to 50

Max items per page (default 50, max 200).

Response headers

Speechify-Request-IdstringOptional

Unique identifier for this request, present on every response (2xx and non-2xx alike). If the caller sends a Speechify-Request-Id request header the server echoes it back (sanitized and length-capped) so one logical request can be traced end-to-end; otherwise the server generates a fresh value. Log it on every response and quote it in support requests

it is the stable handle that ties your observation to Speechify’s server-side logs, and it matches the request_id field in the error envelope.

The legacy alias X-Request-ID carries the same value and is still accepted on requests, until 2027-07-24. Prefer the un-prefixed name (RFC 6648).

Unique identifier for this request, present on every response (2xx and non-2xx alike). If the caller sends a `Speechify-Request-Id` request header the server echoes it back (sanitized and length-capped) so one logical request can be traced end-to-end; otherwise the server generates a fresh value. Log it on every response and quote it in support requests - it is the stable handle that ties your observation to Speechify's server-side logs, and it matches the `request_id` field in the error envelope. The legacy alias `X-Request-ID` carries the same value and is still accepted on requests, until 2027-07-24. Prefer the un-prefixed name (RFC 6648).

Response

The run's steps, oldest first.

next_cursorstring or null

Opaque keyset cursor for the next page. Pass back as the cursor request parameter. null when the caller has reached the end of the list (has_more is also false in that case).

has_moreboolean

True when more rows exist beyond this page.

stepslist of objects

Errors

400

Bad Request Error

401

Unauthorized Error

402

Payment Required Error

404

Not Found Error