Retrieve an agent run

GET

https://api.middesk.com/v1/runs/:id

GET

/v1/runs/:id

$ curl https://api.middesk.com/v1/runs/id \
>      -H "Authorization: Bearer <token>"

1 {
2   "object": "run",
3   "id": "9f1b2c34-5678-4abc-9def-0123456789ab",
4   "created_at": "2026-04-30T18:42:11Z",
5   "updated_at": "2026-04-30T18:42:38Z",
6   "status": "completed",
7   "thread_id": "1aaa2bbb-3ccc-4ddd-8eee-fffaaa111222",
8   "agent": "cip_orchestrator",
9   "requester": {
10     "id": "u1234567-89ab-4cde-9012-345678901234",
11     "name": "Jane Reviewer",
12     "email": "[email protected]"
13   },
14   "started_at": "2026-04-30T18:42:12Z",
15   "ended_at": "2026-04-30T18:42:38Z",
16   "output": {
17     "artifacts": [
18       {
19         "title": "CIP verification summary",
20         "type": "cip_summary",
21         "confidence": "high",
22         "summary": "Verified business identity against SOS, IRS, and watchlist sources.",
23         "sources": [
24           {
25             "url": "https://example-sos.gov/business/12345",
26             "source_name": "Delaware Secretary of State",
27             "source_tier": "primary",
28             "source_type": "sos"
29           }
30         ]
31       }
32     ]
33   },
34   "interrupts": [
35     {
36       "id": "id",
37       "value": {
38         "key": "value"
39       },
40       "agent": "agent"
41     }
42   ],
43   "steps": [
44     {
45       "id": "id",
46       "run_id": "run_id",
47       "type": "activity",
48       "name": "name",
49       "label": "label",
50       "status": "running",
51       "started_at": "2024-01-15T09:30:00Z",
52       "agent": "agent",
53       "parent_step_id": "parent_step_id",
54       "completed_at": "2024-01-15T09:30:00Z",
55       "artifacts": [
56         {
57           "title": "title",
58           "type": "type"
59         }
60       ]
61     }
62   ]
63 }

Retrieves details of a specific agent run

Retrieve an agent run

GET

https://api.middesk.com/v1/runs/:id

GET

/v1/runs/:id

$ curl https://api.middesk.com/v1/runs/id \
>      -H "Authorization: Bearer <token>"

1 {
2   "object": "run",
3   "id": "9f1b2c34-5678-4abc-9def-0123456789ab",
4   "created_at": "2026-04-30T18:42:11Z",
5   "updated_at": "2026-04-30T18:42:38Z",
6   "status": "completed",
7   "thread_id": "1aaa2bbb-3ccc-4ddd-8eee-fffaaa111222",
8   "agent": "cip_orchestrator",
9   "requester": {
10     "id": "u1234567-89ab-4cde-9012-345678901234",
11     "name": "Jane Reviewer",
12     "email": "[email protected]"
13   },
14   "started_at": "2026-04-30T18:42:12Z",
15   "ended_at": "2026-04-30T18:42:38Z",
16   "output": {
17     "artifacts": [
18       {
19         "title": "CIP verification summary",
20         "type": "cip_summary",
21         "confidence": "high",
22         "summary": "Verified business identity against SOS, IRS, and watchlist sources.",
23         "sources": [
24           {
25             "url": "https://example-sos.gov/business/12345",
26             "source_name": "Delaware Secretary of State",
27             "source_tier": "primary",
28             "source_type": "sos"
29           }
30         ]
31       }
32     ]
33   },
34   "interrupts": [
35     {
36       "id": "id",
37       "value": {
38         "key": "value"
39       },
40       "agent": "agent"
41     }
42   ],
43   "steps": [
44     {
45       "id": "id",
46       "run_id": "run_id",
47       "type": "activity",
48       "name": "name",
49       "label": "label",
50       "status": "running",
51       "started_at": "2024-01-15T09:30:00Z",
52       "agent": "agent",
53       "parent_step_id": "parent_step_id",
54       "completed_at": "2024-01-15T09:30:00Z",
55       "artifacts": [
56         {
57           "title": "title",
58           "type": "type"
59         }
60       ]
61     }
62   ]
63 }

Retrieves details of a specific agent run

Authentication

AuthorizationBearer

Bearer authentication of the form Bearer <token>, where token is your auth token.

Path parameters

idstringRequired

Agent run ID

Query parameters

includestringOptional

Comma-separated list of optional sub-resources to include. Pass steps to populate the steps array with this run’s execution trace; omitted by default to avoid the cost of fetching step state from the underlying execution backend.

Response

agent run found

objectstring

Object type identifier.

idstringformat: "uuid"

Unique identifier for the agent run.

created_atdatetime

Timestamp when the agent run record was created.

updated_atdatetime

Timestamp when the agent run record was last updated.

statusenum

Current lifecycle status of the agent run.

Allowed values:

thread_idstringformat: "uuid"

Identifier of the agent thread this run belongs to.

agentstring

Agent type that produced this run (for example, cip_orchestrator).

requesterobject or null

Principal that initiated the run. Populated with the authenticated user’s identity when a session caller initiates the run, and with the account when an API key caller initiates the run. null for system-initiated runs.

started_atdatetime or null

Timestamp when the agent run started.

ended_atdatetime or null

Timestamp when the agent run finished.

outputobject or null

Artifact envelope produced by the agent. Non-null only when status is completed; null for running, interrupted, and error runs.

interruptslist of objects

Pending interrupt requests awaiting input. Empty when the run is not interrupted. To resume a run, POST the interrupt’s id along with the caller-supplied input to POST /v1/runs/{id}/resume.

stepslist of objects

Top-level execution steps for this run. Opt-in: pass ?include=steps on GET /v1/runs/{id} (or POST /v1/runs/{id}/resume) to populate this field. Omitted by default to avoid the cost of fetching step state from the underlying execution backend.

Errors

404

Get Agent Run Request Not Found Error