Run object

A run is a single execution of an agent within a thread. You create a run by specifying an agent type and an input prompt. The run progresses through a lifecycle and produces steps and artifacts that capture the agent’s work.

Example JSON response

1 {
2   "object": "run",
3   "id": "c1d2e3f4-5678-90ab-cdef-1234567890ab",
4   "created_at": "2026-01-15T12:00:00.000Z",
5   "updated_at": "2026-01-15T12:05:00.000Z",
6   "status": "completed",
7   "started_at": "2026-01-15T12:00:01.000Z",
8   "ended_at": "2026-01-15T12:05:00.000Z",
9   "steps": []
10 }

Run attributes

Attribute	Type	Description
`object`	string	Object type identifier. Always `run`.
`id`	string	Unique identifier for the run.
`created_at`	string	ISO 8601 timestamp of when the run record was created.
`updated_at`	string	ISO 8601 timestamp of when the run record was last updated.
`status`	string	Current lifecycle status. One of `pending`, `completed`, `failed`, or `interrupted`.
`started_at`	string \| null	ISO 8601 timestamp of when the run started execution.
`ended_at`	string \| null	ISO 8601 timestamp of when the run finished execution.
`steps`	Step[]	Top-level execution steps for this run. Only included when requesting run details with step state. See Step attributes.

Status values

Status	Description
`pending`	The run has been created and is awaiting or actively executing.
`completed`	The run finished successfully.
`failed`	The run encountered an error.
`interrupted`	The run has paused and is waiting for input. See Take action.

Step attributes

Each step represents an individual unit of work within a run. Steps can be nested, reflecting how an orchestrator delegates to specialists.

Example step

1 {
2   "id": "d1e2f3a4-5678-90ab-cdef-1234567890ab",
3   "run_id": "c1d2e3f4-5678-90ab-cdef-1234567890ab",
4   "graph": "cip_orchestrator",
5   "type": "activity",
6   "name": "research_tin",
7   "label": "Researching TIN verification",
8   "parent_step_id": null,
9   "status": "completed",
10   "started_at": "2026-01-15T12:01:00.000Z",
11   "completed_at": "2026-01-15T12:02:30.000Z",
12   "steps": [],
13   "result": {},
14   "artifacts": []
15 }

Attribute	Type	Description
`id`	string	Unique identifier for the step.
`run_id`	string	Identifier of the run that produced the step.
`graph`	string	Graph identifier that generated this step.
`type`	string	Category of step output. One of `activity`, `output`, `interrupt`, or `error`.
`name`	string	Internal step name.
`label`	string	Human-readable step label.
`parent_step_id`	string \| null	Parent step identifier for nested steps.
`status`	string	Current execution status. One of `running`, `completed`, or `error`.
`started_at`	string	ISO 8601 timestamp of when the step started.
`completed_at`	string \| null	ISO 8601 timestamp of when the step completed.
`steps`	Step[]	Nested child steps.
`result`	object	Structured result payload for the step.
`artifacts`	Artifact[]	Artifacts produced by the step. See Artifact attributes.

Step types

Type	Description
`activity`	An action the agent performed, such as researching a data source or analyzing a result.
`output`	A final output produced by the agent.
`interrupt`	The agent has paused and is requesting input. See Take action.
`error`	The step encountered an error during execution.

Artifact attributes

Each artifact is a structured result produced by a step. Artifacts include confidence indicators and source references that trace findings back to the data that informed them.

Example artifact

1 {
2   "title": "TIN Verification Result",
3   "type": "tin_verification",
4   "confidence": "high",
5   "summary": "TIN matches IRS records for the registered business name.",
6   "sources": [
7     {
8       "url": "https://irs.gov/tin-matching",
9       "source_name": "IRS TIN Matching",
10       "source_tier": "government",
11       "source_type": "tin_match"
12     }
13   ],
14   "data": {}
15 }

Attribute	Type	Description
`title`	string	Human-readable title for the artifact.
`type`	string	Artifact type identifier.
`confidence`	string \| null	Confidence label for artifact quality.
`summary`	string \| null	Summary of the artifact contents.
`sources`	Source[]	Source references used to produce the artifact. See Source attributes.
`data`	object	Structured payload for artifact content.

Source attributes

Each source identifies where an artifact’s data originated.

Attribute	Type	Description
`url`	string	Canonical source URL.
`source_name`	string	Human-readable source name.
`source_tier`	string	Source quality or trust tier.
`source_type`	string	Source category.

Get a demo

Contact your account manager or contact sales to inquire about access.