# Agent runs and research

Paths on this page are relative to <code>/api/liquidity-studio/v2</code>. Authentication and required headers vary by operation.

[API reference overview](/api-reference/overview/) · [OpenAPI download](/openapi/liquidity-operating-system-v2.openapi.json)

## Operations on this page

| Method | Path | Operation |
| --- | --- | --- |
| <code>GET</code> | <code>/agent-runs/{runId}/research-planning</code> | [getResearchPlanning](#getResearchPlanning) |
| <code>GET</code> | <code>/agent-runs/{runId}/research-progress</code> | [getResearchProgress](#getResearchProgress) |
| <code>GET</code> | <code>/agent-runs/{runId}/research-trials/{trialKey}</code> | [getResearchTrialInput](#getResearchTrialInput) |
| <code>GET</code> | <code>/agent-runs/{runId}/result</code> | [getAgentRunResult](#getAgentRunResult) |
| <code>GET</code> | <code>/agent-runs/{runId}/evidence/{evidenceId}</code> | [getAgentRunEvidence](#getAgentRunEvidence) |
| <code>POST</code> | <code>/agent-runs/{runId}/commands</code> | [applyAgentRunCommand](#applyAgentRunCommand) |
| <code>POST</code> | <code>/agent-runs</code> | [startHealthAgentRun](#startHealthAgentRun) |
| <code>GET</code> | <code>/agent-runs</code> | [listAgentRuns](#listAgentRuns) |
| <code>GET</code> | <code>/agent-runs/{runId}</code> | [getAgentRun](#getAgentRun) |
| <code>GET</code> | <code>/agent-runs/{runId}/events</code> | [listAgentRunEvents](#listAgentRunEvents) |

<a id="getResearchPlanning"></a>

## Read current private Research proposal, clarification and linked study task

`GET /agent-runs/{runId}/research-planning`

Operation ID: <code>getResearchPlanning</code>

**Authentication:** <code>&#95;&#95;Host-klineo&#95;session</code> cookie (<code>sessionCookie</code>)

### Parameters

| Name | Location | Required | Type | Description and constraints |
| --- | --- | --- | --- | --- |
| <code>x-klineo-organization-id</code> | header | Yes | <code>string</code> | — |
| <code>runId</code> | path | Yes | <code>string</code> | Pattern: <code>^&#91;a-zA-Z0-9&#93;&#91;a-zA-Z0-9:&#95;-&#93;{2,159}$</code> |

### Responses

| Status | Description | Content type and schema |
| --- | --- | --- |
| <code>200</code> | Current tenant-authorized projection. Activity has no model reasoning or raw evidence. | <code>application/json</code>: <code>object</code> |
| <code>400</code> | Invalid query or cursor | No response body declared |
| <code>401</code> | Session required | No response body declared |
| <code>403</code> | Current workspace access denied | No response body declared |
| <code>404</code> | Run is unavailable in this workspace | No response body declared |
| <code>503</code> | Recovery data temporarily unavailable | No response body declared |

**<code>200</code> response headers**

| Header | Required | Type | Description and constraints |
| --- | --- | --- | --- |
| <code>Cache-Control</code> | Yes | Constant <code>private, no-store</code> | — |

**<code>200</code> <code>application/json</code> body**

<code>object</code> — Additional properties rejected

| Field | Required at this level | Type | Description and constraints |
| --- | --- | --- | --- |
| <code>data</code> | Yes | [ResearchPlanningState](/api-reference/schemas/research-planning-state/) | — |

Nested required fields apply when their parent object or matching union branch is present. Named types link to their complete schema.

<a id="getResearchProgress"></a>

## Read current private Research child-study progress

`GET /agent-runs/{runId}/research-progress`

Operation ID: <code>getResearchProgress</code>

**Authentication:** <code>&#95;&#95;Host-klineo&#95;session</code> cookie (<code>sessionCookie</code>)

### Parameters

| Name | Location | Required | Type | Description and constraints |
| --- | --- | --- | --- | --- |
| <code>x-klineo-organization-id</code> | header | Yes | <code>string</code> | — |
| <code>runId</code> | path | Yes | <code>string</code> | Pattern: <code>^&#91;a-zA-Z0-9&#93;&#91;a-zA-Z0-9:&#95;-&#93;{2,159}$</code> |

### Responses

| Status | Description | Content type and schema |
| --- | --- | --- |
| <code>200</code> | Current tenant-authorized projection. Activity has no model reasoning or raw evidence. | <code>application/json</code>: <code>object</code> |
| <code>400</code> | Invalid query or cursor | No response body declared |
| <code>401</code> | Session required | No response body declared |
| <code>403</code> | Current workspace access denied | No response body declared |
| <code>404</code> | Run is unavailable in this workspace | No response body declared |
| <code>503</code> | Recovery data temporarily unavailable | No response body declared |

**<code>200</code> response headers**

| Header | Required | Type | Description and constraints |
| --- | --- | --- | --- |
| <code>Cache-Control</code> | Yes | Constant <code>private, no-store</code> | — |

**<code>200</code> <code>application/json</code> body**

<code>object</code> — Additional properties rejected

| Field | Required at this level | Type | Description and constraints |
| --- | --- | --- | --- |
| <code>data</code> | Yes | [ResearchProgress](/api-reference/schemas/research-progress/) | — |

Nested required fields apply when their parent object or matching union branch is present. Named types link to their complete schema.

<a id="getResearchTrialInput"></a>

## Inspect the exact immutable inputs of a private Research study

`GET /agent-runs/{runId}/research-trials/{trialKey}`

Operation ID: <code>getResearchTrialInput</code>

**Authentication:** <code>&#95;&#95;Host-klineo&#95;session</code> cookie (<code>sessionCookie</code>)

### Parameters

| Name | Location | Required | Type | Description and constraints |
| --- | --- | --- | --- | --- |
| <code>x-klineo-organization-id</code> | header | Yes | <code>string</code> | — |
| <code>runId</code> | path | Yes | <code>string</code> | Pattern: <code>^&#91;a-zA-Z0-9&#93;&#91;a-zA-Z0-9:&#95;-&#93;{2,159}$</code> |
| <code>trialKey</code> | path | Yes | <code>string</code> | Allowed: <code>baseline</code>, <code>alternative-1</code>, <code>alternative-2</code>, <code>alternative-3</code> |

### Responses

| Status | Description | Content type and schema |
| --- | --- | --- |
| <code>200</code> | Current tenant-authorized projection. Activity has no model reasoning or raw evidence. | <code>application/json</code>: <code>object</code> |
| <code>400</code> | Invalid query or cursor | No response body declared |
| <code>401</code> | Session required | No response body declared |
| <code>403</code> | Current workspace access denied | No response body declared |
| <code>404</code> | Run is unavailable in this workspace | No response body declared |
| <code>503</code> | Recovery data temporarily unavailable | No response body declared |

**<code>200</code> response headers**

| Header | Required | Type | Description and constraints |
| --- | --- | --- | --- |
| <code>Cache-Control</code> | Yes | Constant <code>private, no-store</code> | — |

**<code>200</code> <code>application/json</code> body**

<code>object</code> — Additional properties rejected

| Field | Required at this level | Type | Description and constraints |
| --- | --- | --- | --- |
| <code>data</code> | Yes | [ResearchTrialInput](/api-reference/schemas/research-trial-input/) | — |

Nested required fields apply when their parent object or matching union branch is present. Named types link to their complete schema.

<a id="getAgentRunResult"></a>

## Read and revalidate a saved Health, Proposal Review or Research report

`GET /agent-runs/{runId}/result`

Operation ID: <code>getAgentRunResult</code>

**Authentication:** <code>&#95;&#95;Host-klineo&#95;session</code> cookie (<code>sessionCookie</code>)

Interactive tenant-authorized read. Returns the immutable vault or public-project Health report, or saved Proposal Review report, after deterministic verification against its sealed capture and settled model draft. Applicability is separate from the historical report. Public-project results contain at most two frozen public observations; comparison of saved samples is not a continuous-period measurement or causal explanation. PARTIAL and ABSTAINED reports do not assess market health or grant financial authority. Proposal Review requires current narrow review authority and exposes recorded proposal evidence, exact atomic flows where available, cost gaps and current applicability; it never approves or executes a proposal. Research reports reconstruct the comparison from the immutable protocol and completed child receipts; COMPLETED describes modeled work, not financial assurance. Failed and incompatible trials remain visible. Unavailable or unverifiable results fail closed.

### Parameters

| Name | Location | Required | Type | Description and constraints |
| --- | --- | --- | --- | --- |
| <code>x-klineo-organization-id</code> | header | Yes | <code>string</code> | — |
| <code>runId</code> | path | Yes | <code>string</code> | Pattern: <code>^&#91;a-zA-Z0-9&#93;&#91;a-zA-Z0-9:&#95;-&#93;{2,159}$</code> |

### Responses

| Status | Description | Content type and schema |
| --- | --- | --- |
| <code>200</code> | Current tenant-authorized projection. Activity has no model reasoning or raw evidence. | <code>application/json</code>: <code>object</code> |
| <code>400</code> | Invalid query or cursor | No response body declared |
| <code>401</code> | Session required | No response body declared |
| <code>403</code> | Current workspace access denied | No response body declared |
| <code>404</code> | Run is unavailable in this workspace | No response body declared |
| <code>503</code> | Recovery data temporarily unavailable | No response body declared |

**<code>200</code> response headers**

| Header | Required | Type | Description and constraints |
| --- | --- | --- | --- |
| <code>Cache-Control</code> | Yes | Constant <code>private, no-store</code> | — |

**<code>200</code> <code>application/json</code> body**

<code>object</code> — Additional properties rejected

| Field | Required at this level | Type | Description and constraints |
| --- | --- | --- | --- |
| <code>data</code> | Yes | [AgentRunResult](/api-reference/schemas/agent-run-result/) | — |

Nested required fields apply when their parent object or matching union branch is present. Named types link to their complete schema.

<a id="getAgentRunEvidence"></a>

## Read allowlisted fields from a sealed Health evidence record

`GET /agent-runs/{runId}/evidence/{evidenceId}`

Operation ID: <code>getAgentRunEvidence</code>

**Authentication:** <code>&#95;&#95;Host-klineo&#95;session</code> cookie (<code>sessionCookie</code>)

Interactive tenant-authorized read. Evidence is the frozen captured generation, never refreshed source data. Only scalar fields from the strict source allowlists are returned; internal authorization classifications, signatures, credentials and arbitrary payload objects are excluded. Recorded source assertions are not independent verification.

### Parameters

| Name | Location | Required | Type | Description and constraints |
| --- | --- | --- | --- | --- |
| <code>x-klineo-organization-id</code> | header | Yes | <code>string</code> | — |
| <code>runId</code> | path | Yes | <code>string</code> | Pattern: <code>^&#91;a-zA-Z0-9&#93;&#91;a-zA-Z0-9:&#95;-&#93;{2,159}$</code> |
| <code>evidenceId</code> | path | Yes | <code>string</code> | Pattern: <code>^&#91;a-zA-Z0-9&#93;&#91;a-zA-Z0-9:&#95;-&#93;{2,159}$</code> |

### Responses

| Status | Description | Content type and schema |
| --- | --- | --- |
| <code>200</code> | Current tenant-authorized projection. Activity has no model reasoning or raw evidence. | <code>application/json</code>: <code>object</code> |
| <code>400</code> | Invalid query or cursor | No response body declared |
| <code>401</code> | Session required | No response body declared |
| <code>403</code> | Current workspace access denied | No response body declared |
| <code>404</code> | Run is unavailable in this workspace | No response body declared |
| <code>503</code> | Recovery data temporarily unavailable | No response body declared |

**<code>200</code> response headers**

| Header | Required | Type | Description and constraints |
| --- | --- | --- | --- |
| <code>Cache-Control</code> | Yes | Constant <code>private, no-store</code> | — |

**<code>200</code> <code>application/json</code> body**

<code>object</code> — Additional properties rejected

| Field | Required at this level | Type | Description and constraints |
| --- | --- | --- | --- |
| <code>data</code> | Yes | [CapturedHealthEvidenceView](/api-reference/schemas/captured-health-evidence-view/) | — |

Nested required fields apply when their parent object or matching union branch is present. Named types link to their complete schema.

<a id="applyAgentRunCommand"></a>

## Cancel remaining work or answer a persisted clarification as its requester

`POST /agent-runs/{runId}/commands`

Operation ID: <code>applyAgentRunCommand</code>

**Authentication:** <code>&#95;&#95;Host-klineo&#95;session</code> cookie (<code>sessionCookie</code>)

Interactive requester only; current tenant/workflow authority is rechecked atomically. Retry an unconfirmed command with the identical body, If-Match and Idempotency-Key. Receipt state is the accepted command outcome, not a claim about current worker progress. Cancellation preserves settled work and does not undo external work already sent.

### Parameters

| Name | Location | Required | Type | Description and constraints |
| --- | --- | --- | --- | --- |
| <code>x-klineo-organization-id</code> | header | Yes | <code>string</code> | — |
| <code>runId</code> | path | Yes | <code>string</code> | Pattern: <code>^&#91;a-zA-Z0-9&#93;&#91;a-zA-Z0-9:&#95;-&#93;{2,159}$</code> |
| <code>If-Match</code> | header | Yes | <code>string</code> | Pattern: <code>^"0x&#91;0-9a-f&#93;{64}"$</code> |
| <code>Idempotency-Key</code> | header | Yes | <code>string</code> | Min length: <code>8</code>; Max length: <code>200</code> |

### Request body

Required: **yes**.

**<code>application/json</code>**

[AgentControlCommand](/api-reference/schemas/agent-control-command/)

### Responses

| Status | Description | Content type and schema |
| --- | --- | --- |
| <code>200</code> | Current tenant-authorized projection. Activity has no model reasoning or raw evidence. | <code>application/json</code>: <code>object</code> |
| <code>400</code> | Invalid query or cursor | No response body declared |
| <code>401</code> | Session required | No response body declared |
| <code>403</code> | Current workspace access denied | No response body declared |
| <code>404</code> | Run is unavailable in this workspace | No response body declared |
| <code>409</code> | Command key conflicts or run is terminal; refresh before a new command | No response body declared |
| <code>412</code> | Run or clarification changed; refresh before a new command | No response body declared |
| <code>428</code> | Strong current run If-Match required | No response body declared |
| <code>429</code> | Remaining checkpoint budget exhausted | No response body declared |
| <code>503</code> | Recovery data temporarily unavailable | No response body declared |

**<code>200</code> response headers**

| Header | Required | Type | Description and constraints |
| --- | --- | --- | --- |
| <code>Cache-Control</code> | Yes | Constant <code>private, no-store</code> | — |

**<code>200</code> <code>application/json</code> body**

<code>object</code> — Additional properties rejected

| Field | Required at this level | Type | Description and constraints |
| --- | --- | --- | --- |
| <code>data</code> | Yes | [AgentControlReceipt](/api-reference/schemas/agent-control-receipt/) | — |

Nested required fields apply when their parent object or matching union branch is present. Named types link to their complete schema.

<a id="startHealthAgentRun"></a>

## Admit a bounded Health, Proposal Review or Research task against an exact source version

`POST /agent-runs`

Operation ID: <code>startHealthAgentRun</code>

**Authentication:** <code>&#95;&#95;Host-klineo&#95;session</code> cookie (<code>sessionCookie</code>)

The existing operation identifier is retained for SDK compatibility. Interactive member only. Admission checks deployment enablement, current delegated authority, tenant policy, source version and quotas. Provider assignment and profile eligibility are checked when the worker prepares model work. The caller cannot choose tools, model, budgets, organization or requester. Vault Health uses fully closed UTC-day windows; public-project Health binds saved samples. Proposal Review binds an exact V1 updatedAt, V2 resourceVersion or Research candidate Decision Pack resourceVersion plus contentHash and uses narrow ai:proposal-review authority; it does not grant general AI generation or simulation rights to an approver. Research accepts an explicit reviewed experiment or a PLAN request containing a question and explicit optional assumptions, with exact issuer-intent version and simulation authority. PLAN reserves model resources but no study compute; typed confirmation creates a separately linked execution task. It runs a private baseline plus at most three alternatives, without signed-study or publication side effects. Retry uncertain admission with the identical body and key. A receipt means accepted work, not a completed report; recover progress using the returned run ID. No proposal, approval, comment, payment or financial transaction is created or changed by this endpoint.

### Parameters

| Name | Location | Required | Type | Description and constraints |
| --- | --- | --- | --- | --- |
| <code>x-klineo-organization-id</code> | header | Yes | <code>string</code> | — |
| <code>Idempotency-Key</code> | header | Yes | <code>string</code> | Min length: <code>8</code>; Max length: <code>200</code> |

### Request body

Required: **yes**.

**<code>application/json</code>**

[AgentAdmissionRequest](/api-reference/schemas/agent-admission-request/)

### Responses

| Status | Description | Content type and schema |
| --- | --- | --- |
| <code>200</code> | The identical admission was recovered; read current task state separately. | <code>application/json</code>: <code>object</code> |
| <code>202</code> | A new bounded investigation was atomically admitted. | <code>application/json</code>: <code>object</code> |
| <code>400</code> | Invalid or unsupported request. | <code>application/json</code>: <code>object</code> |
| <code>401</code> | Interactive session required. | <code>application/json</code>: <code>object</code> |
| <code>403</code> | Current authority does not permit the investigation. | <code>application/json</code>: <code>object</code> |
| <code>404</code> | Subject unavailable in this workspace. | <code>application/json</code>: <code>object</code> |
| <code>409</code> | Idempotency key belongs to a different request. | <code>application/json</code>: <code>object</code> |
| <code>412</code> | Reviewed source generation or window changed. | <code>application/json</code>: <code>object</code> |
| <code>428</code> | Reviewed subject version is required. | <code>application/json</code>: <code>object</code> |
| <code>429</code> | Workspace allowance or active limit reached. | <code>application/json</code>: <code>object</code> |
| <code>503</code> | Admission, provider or tenant workflow is unavailable. | <code>application/json</code>: <code>object</code> |

**<code>200</code> response headers**

| Header | Required | Type | Description and constraints |
| --- | --- | --- | --- |
| <code>Cache-Control</code> | Yes | Constant <code>private, no-store</code> | — |
| <code>ETag</code> | Yes | <code>string</code> | Pattern: <code>^"0x&#91;0-9a-f&#93;{64}"$</code> |

**<code>200</code> <code>application/json</code> body**

<code>object</code> — Additional properties rejected

| Field | Required at this level | Type | Description and constraints |
| --- | --- | --- | --- |
| <code>data</code> | Yes | [AgentAdmissionReceipt](/api-reference/schemas/agent-admission-receipt/) | — |

Nested required fields apply when their parent object or matching union branch is present. Named types link to their complete schema.

**<code>202</code> response headers**

| Header | Required | Type | Description and constraints |
| --- | --- | --- | --- |
| <code>Cache-Control</code> | Yes | Constant <code>private, no-store</code> | — |
| <code>ETag</code> | Yes | <code>string</code> | Pattern: <code>^"0x&#91;0-9a-f&#93;{64}"$</code> |

**<code>202</code> <code>application/json</code> body**

<code>object</code> — Additional properties rejected

| Field | Required at this level | Type | Description and constraints |
| --- | --- | --- | --- |
| <code>data</code> | Yes | [AgentAdmissionReceipt](/api-reference/schemas/agent-admission-receipt/) | — |

Nested required fields apply when their parent object or matching union branch is present. Named types link to their complete schema.

**<code>400</code> response headers**

| Header | Required | Type | Description and constraints |
| --- | --- | --- | --- |
| <code>Cache-Control</code> | Yes | Constant <code>private, no-store</code> | — |

**<code>400</code> <code>application/json</code> body**

<code>object</code> — Additional properties rejected

| Field | Required at this level | Type | Description and constraints |
| --- | --- | --- | --- |
| <code>error</code> | Yes | [ApiError](/api-reference/schemas/api-error/) | — |

Nested required fields apply when their parent object or matching union branch is present. Named types link to their complete schema.

**<code>401</code> response headers**

| Header | Required | Type | Description and constraints |
| --- | --- | --- | --- |
| <code>Cache-Control</code> | Yes | Constant <code>private, no-store</code> | — |

**<code>401</code> <code>application/json</code> body**

<code>object</code> — Additional properties rejected

| Field | Required at this level | Type | Description and constraints |
| --- | --- | --- | --- |
| <code>error</code> | Yes | [ApiError](/api-reference/schemas/api-error/) | — |

Nested required fields apply when their parent object or matching union branch is present. Named types link to their complete schema.

**<code>403</code> response headers**

| Header | Required | Type | Description and constraints |
| --- | --- | --- | --- |
| <code>Cache-Control</code> | Yes | Constant <code>private, no-store</code> | — |

**<code>403</code> <code>application/json</code> body**

<code>object</code> — Additional properties rejected

| Field | Required at this level | Type | Description and constraints |
| --- | --- | --- | --- |
| <code>error</code> | Yes | [ApiError](/api-reference/schemas/api-error/) | — |

Nested required fields apply when their parent object or matching union branch is present. Named types link to their complete schema.

**<code>404</code> response headers**

| Header | Required | Type | Description and constraints |
| --- | --- | --- | --- |
| <code>Cache-Control</code> | Yes | Constant <code>private, no-store</code> | — |

**<code>404</code> <code>application/json</code> body**

<code>object</code> — Additional properties rejected

| Field | Required at this level | Type | Description and constraints |
| --- | --- | --- | --- |
| <code>error</code> | Yes | [ApiError](/api-reference/schemas/api-error/) | — |

Nested required fields apply when their parent object or matching union branch is present. Named types link to their complete schema.

**<code>409</code> response headers**

| Header | Required | Type | Description and constraints |
| --- | --- | --- | --- |
| <code>Cache-Control</code> | Yes | Constant <code>private, no-store</code> | — |

**<code>409</code> <code>application/json</code> body**

<code>object</code> — Additional properties rejected

| Field | Required at this level | Type | Description and constraints |
| --- | --- | --- | --- |
| <code>error</code> | Yes | [ApiError](/api-reference/schemas/api-error/) | — |

Nested required fields apply when their parent object or matching union branch is present. Named types link to their complete schema.

**<code>412</code> response headers**

| Header | Required | Type | Description and constraints |
| --- | --- | --- | --- |
| <code>Cache-Control</code> | Yes | Constant <code>private, no-store</code> | — |

**<code>412</code> <code>application/json</code> body**

<code>object</code> — Additional properties rejected

| Field | Required at this level | Type | Description and constraints |
| --- | --- | --- | --- |
| <code>error</code> | Yes | [ApiError](/api-reference/schemas/api-error/) | — |

Nested required fields apply when their parent object or matching union branch is present. Named types link to their complete schema.

**<code>428</code> response headers**

| Header | Required | Type | Description and constraints |
| --- | --- | --- | --- |
| <code>Cache-Control</code> | Yes | Constant <code>private, no-store</code> | — |

**<code>428</code> <code>application/json</code> body**

<code>object</code> — Additional properties rejected

| Field | Required at this level | Type | Description and constraints |
| --- | --- | --- | --- |
| <code>error</code> | Yes | [ApiError](/api-reference/schemas/api-error/) | — |

Nested required fields apply when their parent object or matching union branch is present. Named types link to their complete schema.

**<code>429</code> response headers**

| Header | Required | Type | Description and constraints |
| --- | --- | --- | --- |
| <code>Cache-Control</code> | Yes | Constant <code>private, no-store</code> | — |

**<code>429</code> <code>application/json</code> body**

<code>object</code> — Additional properties rejected

| Field | Required at this level | Type | Description and constraints |
| --- | --- | --- | --- |
| <code>error</code> | Yes | [ApiError](/api-reference/schemas/api-error/) | — |

Nested required fields apply when their parent object or matching union branch is present. Named types link to their complete schema.

**<code>503</code> response headers**

| Header | Required | Type | Description and constraints |
| --- | --- | --- | --- |
| <code>Cache-Control</code> | Yes | Constant <code>private, no-store</code> | — |

**<code>503</code> <code>application/json</code> body**

<code>object</code> — Additional properties rejected

| Field | Required at this level | Type | Description and constraints |
| --- | --- | --- | --- |
| <code>error</code> | Yes | [ApiError](/api-reference/schemas/api-error/) | — |

Nested required fields apply when their parent object or matching union branch is present. Named types link to their complete schema.

<a id="listAgentRuns"></a>

## Recover authorized agent task history

`GET /agent-runs`

Operation ID: <code>listAgentRuns</code>

**Authentication:** <code>&#95;&#95;Host-klineo&#95;session</code> cookie (<code>sessionCookie</code>)

### Parameters

| Name | Location | Required | Type | Description and constraints |
| --- | --- | --- | --- | --- |
| <code>x-klineo-organization-id</code> | header | Yes | <code>string</code> | — |
| <code>limit</code> | query | No | <code>integer</code> | Default: <code>25</code>; Minimum: <code>1</code>; Maximum: <code>100</code> |
| <code>cursor</code> | query | No | <code>string</code> | Max length: <code>2048</code> |
| <code>kind</code> | query | No | <code>string</code> | Allowed: <code>HEALTH&#95;INVESTIGATION</code>, <code>PROPOSAL&#95;REVIEW</code>, <code>WHAT&#95;IF&#95;RESEARCH</code> |
| <code>state</code> | query | No | <code>string</code> | Allowed: <code>QUEUED</code>, <code>RUNNING</code>, <code>WAITING&#95;FOR&#95;INPUT</code>, <code>WAITING&#95;FOR&#95;CHILDREN</code>, <code>COMPLETED</code>, <code>PARTIAL</code>, <code>ABSTAINED</code>, <code>FAILED</code>, <code>CANCELLED</code> |
| <code>subjectRecordType</code> | query | No | <code>string</code> | Allowed: <code>VAULT</code>, <code>PROPOSAL</code>, <code>PROPOSAL&#95;WORKSPACE</code>, <code>ISSUER&#95;INTENT</code>, <code>SAVED&#95;PUBLIC&#95;PROJECT</code>, <code>DECISION&#95;PACK</code> |
| <code>subjectRecordId</code> | query | No | <code>string</code> | Pattern: <code>^&#91;a-zA-Z0-9&#93;&#91;a-zA-Z0-9:&#95;-&#93;{2,159}$</code> |

### Responses

| Status | Description | Content type and schema |
| --- | --- | --- |
| <code>200</code> | Current tenant-authorized projection. Activity has no model reasoning or raw evidence. | <code>application/json</code>: <code>object</code> |
| <code>400</code> | Invalid query or cursor | No response body declared |
| <code>401</code> | Session required | No response body declared |
| <code>403</code> | Current workspace access denied | No response body declared |
| <code>404</code> | Run is unavailable in this workspace | No response body declared |
| <code>503</code> | Recovery data temporarily unavailable | No response body declared |

**<code>200</code> response headers**

| Header | Required | Type | Description and constraints |
| --- | --- | --- | --- |
| <code>Cache-Control</code> | Yes | Constant <code>private, no-store</code> | — |

**<code>200</code> <code>application/json</code> body**

<code>object</code> — Additional properties rejected

| Field | Required at this level | Type | Description and constraints |
| --- | --- | --- | --- |
| <code>data</code> | Yes | [AgentRunList](/api-reference/schemas/agent-run-list/) | — |

Nested required fields apply when their parent object or matching union branch is present. Named types link to their complete schema.

<a id="getAgentRun"></a>

## Read persisted run status and pending clarification

`GET /agent-runs/{runId}`

Operation ID: <code>getAgentRun</code>

**Authentication:** <code>&#95;&#95;Host-klineo&#95;session</code> cookie (<code>sessionCookie</code>)

### Parameters

| Name | Location | Required | Type | Description and constraints |
| --- | --- | --- | --- | --- |
| <code>x-klineo-organization-id</code> | header | Yes | <code>string</code> | — |
| <code>runId</code> | path | Yes | <code>string</code> | Pattern: <code>^&#91;a-zA-Z0-9&#93;&#91;a-zA-Z0-9:&#95;-&#93;{2,159}$</code> |

### Responses

| Status | Description | Content type and schema |
| --- | --- | --- |
| <code>200</code> | Current tenant-authorized projection. Activity has no model reasoning or raw evidence. | <code>application/json</code>: <code>object</code> |
| <code>400</code> | Invalid query or cursor | No response body declared |
| <code>401</code> | Session required | No response body declared |
| <code>403</code> | Current workspace access denied | No response body declared |
| <code>404</code> | Run is unavailable in this workspace | No response body declared |
| <code>503</code> | Recovery data temporarily unavailable | No response body declared |

**<code>200</code> response headers**

| Header | Required | Type | Description and constraints |
| --- | --- | --- | --- |
| <code>Cache-Control</code> | Yes | Constant <code>private, no-store</code> | — |

**<code>200</code> <code>application/json</code> body**

<code>object</code> — Additional properties rejected

| Field | Required at this level | Type | Description and constraints |
| --- | --- | --- | --- |
| <code>data</code> | Yes | [AgentRunDetail](/api-reference/schemas/agent-run-detail/) | — |

Nested required fields apply when their parent object or matching union branch is present. Named types link to their complete schema.

<a id="listAgentRunEvents"></a>

## Read recorded run and checkpoint transitions

`GET /agent-runs/{runId}/events`

Operation ID: <code>listAgentRunEvents</code>

**Authentication:** <code>&#95;&#95;Host-klineo&#95;session</code> cookie (<code>sessionCookie</code>)

### Parameters

| Name | Location | Required | Type | Description and constraints |
| --- | --- | --- | --- | --- |
| <code>x-klineo-organization-id</code> | header | Yes | <code>string</code> | — |
| <code>runId</code> | path | Yes | <code>string</code> | Pattern: <code>^&#91;a-zA-Z0-9&#93;&#91;a-zA-Z0-9:&#95;-&#93;{2,159}$</code> |
| <code>after</code> | query | No | <code>string</code> | Default: <code>0</code>; Pattern: <code>^&#40;0&#124;&#91;1-9&#93;&#91;0-9&#93;{0,18}&#41;$</code> |
| <code>limit</code> | query | No | <code>integer</code> | Default: <code>50</code>; Minimum: <code>1</code>; Maximum: <code>100</code> |

### Responses

| Status | Description | Content type and schema |
| --- | --- | --- |
| <code>200</code> | Current tenant-authorized projection. Activity has no model reasoning or raw evidence. | <code>application/json</code>: <code>object</code> |
| <code>400</code> | Invalid query or cursor | No response body declared |
| <code>401</code> | Session required | No response body declared |
| <code>403</code> | Current workspace access denied | No response body declared |
| <code>404</code> | Run is unavailable in this workspace | No response body declared |
| <code>503</code> | Recovery data temporarily unavailable | No response body declared |

**<code>200</code> response headers**

| Header | Required | Type | Description and constraints |
| --- | --- | --- | --- |
| <code>Cache-Control</code> | Yes | Constant <code>private, no-store</code> | — |

**<code>200</code> <code>application/json</code> body**

<code>object</code> — Additional properties rejected

| Field | Required at this level | Type | Description and constraints |
| --- | --- | --- | --- |
| <code>data</code> | Yes | [AgentActivityPage](/api-reference/schemas/agent-activity-page/) | — |

Nested required fields apply when their parent object or matching union branch is present. Named types link to their complete schema.