> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.middesk.com/reference/run/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.middesk.com/_mcp/server. # Run object > A single execution of an agent within a thread. A run is a single execution of an agent within a [thread](/reference/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. ## Run object **`Example JSON response`** ```json title="Example JSON response" { "object": "run", "id": "c1d2e3f4-5678-90ab-cdef-1234567890ab", "business_id": "68b56939-cfc5-4e8c-af0b-51e84d413670", "created_at": "2026-01-15T12:00:00.000Z", "updated_at": "2026-01-15T12:05:00.000Z", "status": "completed", "started_at": "2026-01-15T12:00:01.000Z", "ended_at": "2026-01-15T12:05:00.000Z", "steps": [], "interrupts": [] } ``` ## Run attributes | Attribute | Type | Description | | ------------- | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | | `object` | string | Object type identifier. Always `run`. | | `id` | string (uuid) | Unique identifier for the run. | | `business_id` | string (uuid) \| null | Middesk business the run is scoped to. Null when the run was started with an inline `business` payload whose business did not exist yet. | | `created_at` | string (date-time) | ISO 8601 timestamp of when the run record was created. | | `updated_at` | string (date-time) | ISO 8601 timestamp of when the run record was last updated. | | `status` | string | Current lifecycle status. One of `running`, `completed`, `error`, or `interrupted`. | | `started_at` | string (date-time) \| null | ISO 8601 timestamp of when the run started execution. | | `ended_at` | string (date-time) \| 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](#step-attributes). | | `interrupts` | array | Pending interrupt requests awaiting input. Empty when the run is not interrupted. | ## Status values | Status | Description | | ------------- | ---------------------------------------------------------------------------------------------- | | `running` | The run is actively executing. | | `completed` | The run finished successfully. | | `error` | The run encountered an error. | | `interrupted` | The run has paused and is waiting for input. See [Take action](/work-with-agents/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`** ```json title="Example step" { "id": "d1e2f3a4-5678-90ab-cdef-1234567890ab", "run_id": "c1d2e3f4-5678-90ab-cdef-1234567890ab", "agent": "cip_orchestrator", "type": "activity", "name": "research_tin", "label": "Researching TIN verification", "parent_step_id": null, "status": "completed", "started_at": "2026-01-15T12:01:00.000Z", "completed_at": "2026-01-15T12:02:30.000Z", "steps": [], "result": {}, "artifacts": [] } ``` | Attribute | Type | Description | | ---------------- | -------------- | -------------------------------------------------------------------------------- | | `id` | string | Unique identifier for the step. | | `run_id` | string | Identifier of the run that produced the step. | | `agent` | string | Agent 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](#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](/work-with-agents/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`** ```json title="Example artifact" { "title": "TIN Verification Result", "type": "tin_verification", "confidence": "high", "summary": "TIN matches IRS records for the registered business name.", "sources": [ { "url": "https://irs.gov/tin-matching", "source_name": "IRS TIN Matching", "source_tier": "government", "source_type": "tin_match" } ] } ``` | 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](#source-attributes). | ## 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](https://www.middesk.com/contact-sales) to inquire about access. > A single execution of an agent within a thread.