List Agent Runs

Beta

GET

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

GET

/v1/agents/:agent_id/runs

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

{
  "next_cursor": "string",
  "has_more": true,
  "runs": [
    {
      "id": "arun_01kr410dd3yrst4chn5kn0t78f",
      "agent_id": "agent_01jqr8x9zg5k2m3n4p5q6r7s8t",
      "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"
        }
      ],
      "status": "queued",
      "input": {
        "instruction": "string",
        "variables": {},
        "max_turns": 1,
        "user_identity": "string",
        "output_schema": {},
        "attachments": [
          "file_01jqr8x9zg5k2m3n4p5q6r7s8t"
        ],
        "delegation_targets": [
          {
            "agent_id": "agent_01jqr8x9zg5k2m3n4p5q6r7s8t",
            "role": "researcher",
            "delegation": "hand off deep research"
          }
        ]
      },
      "created_at": "2024-01-15T09:30:00Z",
      "project_id": "proj_01kwxwcbyb6wk952swa0432cf1",
      "output": {
        "reply": "string",
        "data": {},
        "transcript": [
          {}
        ]
      },
      "error": {
        "code": "string",
        "message": "string"
      },
      "incomplete_reason": "max_turns_exhausted",
      "usage": {
        "duration_ms": 1,
        "input_tokens": 1,
        "cached_input_tokens": 1,
        "output_tokens": 1,
        "total_tokens": 1,
        "cost_micro_usd": 13404,
        "rate_card_version": "2026-09-08",
        "models": [
          {
            "model": "gpt-5.6-terra",
            "input_tokens": 1,
            "cached_input_tokens": 1,
            "output_tokens": 1,
            "total_tokens": 1,
            "cost_micro_usd": 1
          }
        ],
        "tools": [
          {
            "tool": "web_search",
            "calls": 3,
            "cost_micro_usd": 18000
          },
          {
            "tool": "generate_image",
            "calls": 1,
            "cost_micro_usd": 48000
          }
        ]
      },
      "pending_action": {
        "key": "string",
        "type": "string",
        "reason": "string",
        "default_decision": "approve",
        "requested_at": "2024-01-15T09:30:00Z",
        "expires_at": "2024-01-15T09:30:00Z",
        "summary": "string",
        "payload": {},
        "approve_effect": "string",
        "deny_effect": "string",
        "timeout_effect": "string"
      },
      "metadata": {},
      "parent_run_id": "arun_01kr410dd3yrst4chn5kn0t78f",
      "started_at": "2024-01-15T09:30:00Z",
      "ended_at": "2024-01-15T09:30:00Z",
      "team_id": "team_01jqr8x9zg5k2m3n4p5q6r7s8t"
    }
  ]
}

List an agent’s runs, newest first.

The filters are exactly the ones listed here. A query parameter this list does not accept is a 400 naming it, never silently ignored.

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_...).

Query parameters

statusenumOptional

Narrow the list to one run status. Omit for every status. A value outside the enum is rejected with a 400 naming status, rather than quietly widening to everything - a filter that ignores a typo is how a surface reports “nothing waiting” while a run waits.

user_identitystringOptional<=256 characters

Narrow the list to runs acting for one person - the user_identity they were started with, matched exactly. Omit for every run. A scheduled run started by a trigger carrying user_identity is found here too.

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 agent's runs, newest 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.

runslist of objects

Errors

400

Bad Request Error

401

Unauthorized Error

402

Payment Required Error

404

Not Found Error