Jump toAgent runs

Agent runs

Read agent runs, what they said, the tools they called, and stream them as they happen.

get/v1/runs

List runs

Needs run.view

Agent runs, newest first: IDs, states, times, cost and who started each one, never content. The console's home page reads them for its charts. parent_run_id lists the sub-agent runs one run started.

Query parameters

agent_idstring
workspace_idstring
statestring
limitinteger
Default50at least 1at most 200
cursorstring
parent_run_idstring

Response200

objectstring
list
dataRun[]
26 fields
- idstring
- objectstring
  run
- agent_idstring or null
- agent_version_idstring or null
- created_atstring or null
- draft_revisioninteger or null
- ended_atstring or null
- finish_reasonstring or null
  One ofend_turnrefusallimiterrorcancelled
- is_testboolean
- model_requestedstring
- profilestring
  One ofstandardprivacyhipaa
- row_versioninteger
- started_atstring or null
- statestring
  One ofqueuedrunningwaiting_approvalwaiting_inputwaiting_eventwaiting_timerblocked_on_keyblocked_on_connectioncompletedfailedcancelledstopped_by_limitfailed_to_start
- state_reasonstring or null
- triggerstring
  One ofwidgetconsoleapiworkflowagentevala2amcpchat
- updated_atstring or null
- workspace_idstring
- aliasstring or null
- cost_micro_usdinteger
  Default0
- created_byActorRef or null
  Who created or last changed something, resolved to a name for display. system, workload (an automation) and end_user (a widget visitor) have no ID or name: the console words them. name is null for someone the directory no longer knows. id is what the lists' created_by/updated_by filters take. avatar_version is set for a person with a photo: it is at GET /v1/members/{id}/avatar?v=<avatar_version> while they are a member.
  5 fields
  idstring or null
  kindstring
  One ofuserapi_keyservice_accountworkloadend_usersystem
  namestring or null
  avatar_versionstring or null
  emailstring or null
- depthinteger
  Default0
- model_effectivestring or null
- parent_run_idstring or null
- root_run_idstring or null
- steps_usedinteger
  Default0
has_moreboolean
next_cursorstring or null
facetsmap<string, map<string, integer>> or null
peoplemap<string, ActorRef> or null
5 fields
- idstring or null
- kindstring
  One ofuserapi_keyservice_accountworkloadend_usersystem
- namestring or null
- avatar_versionstring or null
- emailstring or null
total_countinteger or null
total_count_exactboolean or null

Status codes

200Successful Response
422The request is not valid: errors[] names each field.
4XXThe request was refused: the problem says why.
5XXThe API could not answer: the problem says why.

Request

curl "https://api.mydeepagents.com/v1/runs?limit=20" \
  -H "Authorization: Bearer $MDA_API_KEY"

Response · 200

JSON

{
  "object": "list",
  "data": [
    {
      "id": "run_01jcr77659p6hws1zjqkthay73",
      "object": "run",
      "agent_id": "agt_01jctdbahw9btk5p831xs974yq",
      "agent_version_id": "agv_01jc7jt62eapjyt621bszf6wrs",
      "alias": "live",
      "cost_micro_usd": 0,
      "created_at": "2026-11-10T09:30:00.000Z",
      "created_by": {
        "kind": "user",
        "id": "usr_01jcf1j9wjxfrnhqda3mq7ejxn",
        "name": "Ada Lovelace",
        "email": "ada@example.com"
      },
      "depth": 0,
      "draft_revision": 2,
      "ended_at": null,
      "finish_reason": null,
      "is_test": false,
      "model_effective": "claude-sonnet-5-5",
      "model_requested": "claude-sonnet-5-5",
      "parent_run_id": null,
      "profile": "standard",
      "root_run_id": "run_01jcr77659p6hws1zjqkthay73",
      "row_version": 4,
      "started_at": "2026-11-10T09:30:00.000Z",
      "state": "queued",
      "state_reason": null,
      "steps_used": 0,
      "trigger": "api",
      "updated_at": "2026-11-10T09:30:00.000Z",
      "workspace_id": "ws_01jccj30nr8ad7mx1yc5v9zx3h"
    }
  ],
  "has_more": false,
  "next_cursor": null,
  "total_count": 1
}

get/v1/runs/{run_id}

Get run

Needs run.view

Path parameters

run_idstringRequired

Response200

idstring
objectstring
run
agent_idstring or null
agent_version_idstring or null
created_atstring or null
draft_revisioninteger or null
ended_atstring or null
finish_reasonstring or null
One ofend_turnrefusallimiterrorcancelled
is_testboolean
model_requestedstring
profilestring
One ofstandardprivacyhipaa
row_versioninteger
started_atstring or null
statestring
One ofqueuedrunningwaiting_approvalwaiting_inputwaiting_eventwaiting_timerblocked_on_keyblocked_on_connectioncompletedfailedcancelledstopped_by_limitfailed_to_start
state_reasonstring or null
triggerstring
One ofwidgetconsoleapiworkflowagentevala2amcpchat
updated_atstring or null
workspace_idstring
aliasstring or null
cost_micro_usdinteger
Default0
created_byActorRef or null
Who created or last changed something, resolved to a name for display. system, workload (an automation) and end_user (a widget visitor) have no ID or name: the console words them. name is null for someone the directory no longer knows. id is what the lists' created_by/updated_by filters take. avatar_version is set for a person with a photo: it is at GET /v1/members/{id}/avatar?v=<avatar_version> while they are a member.
5 fields
- idstring or null
- kindstring
  One ofuserapi_keyservice_accountworkloadend_usersystem
- namestring or null
- avatar_versionstring or null
- emailstring or null
depthinteger
Default0
model_effectivestring or null
parent_run_idstring or null
root_run_idstring or null
steps_usedinteger
Default0

Status codes

200Successful Response
422The request is not valid: errors[] names each field.
4XXThe request was refused: the problem says why.
5XXThe API could not answer: the problem says why.

Request

curl "https://api.mydeepagents.com/v1/runs/run_01jcr77659p6hws1zjqkthay73" \
  -H "Authorization: Bearer $MDA_API_KEY"

Response · 200

JSON

{
  "id": "run_01jcr77659p6hws1zjqkthay73",
  "object": "run",
  "agent_id": "agt_01jctdbahw9btk5p831xs974yq",
  "agent_version_id": "agv_01jc7jt62eapjyt621bszf6wrs",
  "alias": "live",
  "cost_micro_usd": 0,
  "created_at": "2026-11-10T09:30:00.000Z",
  "created_by": {
    "kind": "user",
    "id": "usr_01jcf1j9wjxfrnhqda3mq7ejxn",
    "name": "Ada Lovelace",
    "email": "ada@example.com"
  },
  "depth": 0,
  "draft_revision": 2,
  "ended_at": null,
  "finish_reason": null,
  "is_test": false,
  "model_effective": "claude-sonnet-5-5",
  "model_requested": "claude-sonnet-5-5",
  "parent_run_id": null,
  "profile": "standard",
  "root_run_id": "run_01jcr77659p6hws1zjqkthay73",
  "row_version": 4,
  "started_at": "2026-11-10T09:30:00.000Z",
  "state": "queued",
  "state_reason": null,
  "steps_used": 0,
  "trigger": "api",
  "updated_at": "2026-11-10T09:30:00.000Z",
  "workspace_id": "ws_01jccj30nr8ad7mx1yc5v9zx3h"
}

post/v1/runs/{run_id}/cancel

Cancel run

Needs run.view

Stop an agent run. The person who started it may, and anyone holding run.cancel in its workspace. A cancelled chat answer keeps what had streamed (status: stopped).

Path parameters

run_idstringRequired

Response200

idstring
objectstring
run
agent_idstring or null
agent_version_idstring or null
created_atstring or null
draft_revisioninteger or null
ended_atstring or null
finish_reasonstring or null
One ofend_turnrefusallimiterrorcancelled
is_testboolean
model_requestedstring
profilestring
One ofstandardprivacyhipaa
row_versioninteger
started_atstring or null
statestring
One ofqueuedrunningwaiting_approvalwaiting_inputwaiting_eventwaiting_timerblocked_on_keyblocked_on_connectioncompletedfailedcancelledstopped_by_limitfailed_to_start
state_reasonstring or null
triggerstring
One ofwidgetconsoleapiworkflowagentevala2amcpchat
updated_atstring or null
workspace_idstring
aliasstring or null
cost_micro_usdinteger
Default0
created_byActorRef or null
Who created or last changed something, resolved to a name for display. system, workload (an automation) and end_user (a widget visitor) have no ID or name: the console words them. name is null for someone the directory no longer knows. id is what the lists' created_by/updated_by filters take. avatar_version is set for a person with a photo: it is at GET /v1/members/{id}/avatar?v=<avatar_version> while they are a member.
5 fields
- idstring or null
- kindstring
  One ofuserapi_keyservice_accountworkloadend_usersystem
- namestring or null
- avatar_versionstring or null
- emailstring or null
depthinteger
Default0
model_effectivestring or null
parent_run_idstring or null
root_run_idstring or null
steps_usedinteger
Default0

Status codes

200Successful Response
422The request is not valid: errors[] names each field.
4XXThe request was refused: the problem says why.
5XXThe API could not answer: the problem says why.

Request

curl -X POST "https://api.mydeepagents.com/v1/runs/run_01jcr77659p6hws1zjqkthay73/cancel" \
  -H "Authorization: Bearer $MDA_API_KEY"

Response · 200

JSON

{
  "id": "run_01jcr77659p6hws1zjqkthay73",
  "object": "run",
  "agent_id": "agt_01jctdbahw9btk5p831xs974yq",
  "agent_version_id": "agv_01jc7jt62eapjyt621bszf6wrs",
  "alias": "live",
  "cost_micro_usd": 0,
  "created_at": "2026-11-10T09:30:00.000Z",
  "created_by": {
    "kind": "user",
    "id": "usr_01jcf1j9wjxfrnhqda3mq7ejxn",
    "name": "Ada Lovelace",
    "email": "ada@example.com"
  },
  "depth": 0,
  "draft_revision": 2,
  "ended_at": null,
  "finish_reason": null,
  "is_test": false,
  "model_effective": "claude-sonnet-5-5",
  "model_requested": "claude-sonnet-5-5",
  "parent_run_id": null,
  "profile": "standard",
  "root_run_id": "run_01jcr77659p6hws1zjqkthay73",
  "row_version": 4,
  "started_at": "2026-11-10T09:30:00.000Z",
  "state": "queued",
  "state_reason": null,
  "steps_used": 0,
  "trigger": "api",
  "updated_at": "2026-11-10T09:30:00.000Z",
  "workspace_id": "ws_01jccj30nr8ad7mx1yc5v9zx3h"
}

get/v1/runs/{run_id}/content

Get run content

Needs run.view_content

The run's input and its answer (text, structured, error), opened under content.

Path parameters

run_idstringRequired

Response200

objectstring
run_content
inputany
outputany
run_idstring

Status codes

200Successful Response
422The request is not valid: errors[] names each field.
4XXThe request was refused: the problem says why.
5XXThe API could not answer: the problem says why.

Request

curl "https://api.mydeepagents.com/v1/runs/run_01jcr77659p6hws1zjqkthay73/content" \
  -H "Authorization: Bearer $MDA_API_KEY"

Response · 200

JSON

{
  "object": "run_content",
  "input": {},
  "output": {},
  "run_id": "run_01jcr77659p6hws1zjqkthay73"
}

get/v1/runs/{run_id}/events

Run events

Needs run.view

The run as it happens, as server-sent events.

Resume with Last-Event-ID; the connection closes after the final run.* event. message.* events carry the answer's text, so they are sent only to a caller who may also see content (run.view_content). 410 stream_expired when the live copy is gone: the run's rows (GET /v1/runs/{id}/content) hold the record. 503 when streaming is unavailable: poll GET /v1/runs/{id}.

Path parameters

run_idstringRequired

Headers

Last-Event-IDstring
The last event id you received, to carry on after it.

Response200

Answers with server-sent events (text/event-stream).

Status codes

200Successful Response
422The request is not valid: errors[] names each field.
4XXThe request was refused: the problem says why.
5XXThe API could not answer: the problem says why.

Request

curl -N "https://api.mydeepagents.com/v1/runs/run_01jcr77659p6hws1zjqkthay73/events" \
  -H "Authorization: Bearer $MDA_API_KEY" \
  -H "Accept: text/event-stream"

get/v1/runs/{run_id}/tool_calls

List run tool calls

Needs run.view_content

Each tool call of the run with what it was sent and what came back, opened under content. Kept with the run, where the live stream keeps its events for an hour.

Path parameters

run_idstringRequired

Response200

objectstring
list
dataRunToolCall[]
12 fields
- objectstring
  run_tool_call
- call_idstring
- child_run_idstring or null
- duration_msinteger or null
- ended_atstring or null
- error_codestring or null
- inputany
- kindstring
  One oftoolsubagent
- outputany
- started_atstring
- statusstring
  One ofrunningokerrordeniedcancelled
- toolstring

Status codes

200Successful Response
422The request is not valid: errors[] names each field.
4XXThe request was refused: the problem says why.
5XXThe API could not answer: the problem says why.

Request

curl "https://api.mydeepagents.com/v1/runs/run_01jcr77659p6hws1zjqkthay73/tool_calls" \
  -H "Authorization: Bearer $MDA_API_KEY"

Response · 200

JSON

{
  "object": "list",
  "data": [
    {
      "object": "run_tool_call",
      "call_id": "call_01jcjmpqg5rp82pme2v7etkgn6",
      "child_run_id": "run_01jcr77659p6hws1zjqkthay73",
      "duration_ms": 840,
      "ended_at": null,
      "error_code": null,
      "input": {},
      "kind": "tool",
      "output": {},
      "started_at": "2026-11-10T09:30:00.000Z",
      "status": "running",
      "tool": "tool"
    }
  ]
}

get/v1/runs/{run_id}/tree

Get run tree

Needs run.view

The task this run is part of, from its top run down: who handed what to whom and when, for the replay. States and timing only.

Path parameters

run_idstringRequired

Response200

objectstring
run_tree
outside_callsRunTreeCall[]
9 fields
- idstring
- agent_idstring
- agent_namestring or null
- card_urlstring or null
- duration_msinteger
- ended_atstring
- error_codestring or null
- run_idstring
- statusstring
  One ofokfailedinput_required
root_run_idstring
run_idstring
runsRunTreeRun[]
13 fields
- idstring
- agent_idstring
- agent_namestring or null
- cost_micro_usdinteger or null
- created_atstring
- depthinteger
- ended_atstring or null
- is_testboolean
- parent_run_idstring or null
- started_atstring or null
- statestring
- steps_usedinteger or null
- triggerstring
truncatedboolean

Status codes

200Successful Response
422The request is not valid: errors[] names each field.
4XXThe request was refused: the problem says why.
5XXThe API could not answer: the problem says why.

Request

curl "https://api.mydeepagents.com/v1/runs/run_01jcr77659p6hws1zjqkthay73/tree" \
  -H "Authorization: Bearer $MDA_API_KEY"

Response · 200

JSON

{
  "object": "run_tree",
  "outside_calls": [
    {
      "id": "id",
      "agent_id": "agt_01jctdbahw9btk5p831xs974yq",
      "agent_name": "agent name",
      "card_url": "https://example.com",
      "duration_ms": 840,
      "ended_at": "2026-11-10T09:30:00.000Z",
      "error_code": null,
      "run_id": "run_01jcr77659p6hws1zjqkthay73",
      "status": "ok"
    }
  ],
  "root_run_id": "run_01jcr77659p6hws1zjqkthay73",
  "run_id": "run_01jcr77659p6hws1zjqkthay73",
  "runs": [
    {
      "id": "id",
      "agent_id": "agt_01jctdbahw9btk5p831xs974yq",
      "agent_name": "agent name",
      "cost_micro_usd": 1250000,
      "created_at": "2026-11-10T09:30:00.000Z",
      "depth": 2,
      "ended_at": null,
      "is_test": false,
      "parent_run_id": null,
      "started_at": "2026-11-10T09:30:00.000Z",
      "state": "state",
      "steps_used": 2,
      "trigger": "api"
    }
  ],
  "truncated": true
}

Build with us

Ready for your first call?

Early access is open. Tell us what you want your agents to do, and we will help you get your first key.

Talk to us Read the API guide