# Start a run

POST /v1/sessions/{session_id}/runs: Start one run inside an existing session.

POST<code>/v1/sessions/&#123;session_id&#125;/runs</code>

Start one run inside an existing session. The session serializes its runs. `idempotency_key` is scoped to the session and prevents a retry from starting a second run; a request without a key always creates a new run. By default the endpoint returns `202 Accepted` with the admitted run; set `Accept: text/event-stream` or add `?stream=true` to stream immediately, or reconnect later through the run's events endpoint.

Generated from the Platform API specification on 2026-09-04.

## Path parameters

| Parameter | Type | Description |
|---|---|---|
| `session_id` | string | The session, as returned by Create a session. |

## Query parameters

| Parameter | Type | Description |
|---|---|---|
| `stream` | boolean | Stream the run's events instead of returning the admitted run. |

## Headers

| Header | Required | Description |
|---|---|---|
| `Authorization` | yes | `Bearer` plus a short-lived OAuth access token issued for the Tanomis API audience. Backends obtain tokens with an [organization automation client](/guides/run/authenticate-your-backend); the CLI's human login is not an application credential. |
| `X-Organization-ID` | yes | The `organization_id` from the workspace projection you selected in `GET /v1/me/workspaces`. |
| `X-Workspace-Tenant-ID` | yes | The nested `tenant_id` from the same projection. A header cannot widen what the token grants. Some single-workspace or self-hosted environments take `X-Tenant-ID` instead, as supplied by their administrator. |

## Request body

| Field | Type | Required | Description |
|---|---|---|---|
| `input` | object | required | Passed to the agent as JSON. The shape is defined by your agent's entrypoint. |
| `idempotency_key` | string | optional | Scoped to the session; a retry with the same key returns the original run. At most 255 bytes. |
| `attachments` | array | optional | Files prepared and uploaded in this session, as `{ "file_id": ... }` objects. |
| `work` | object | optional | Settlement-mode agents only. Send either `subject` (open new work) or `work_id` (continue work opened by an earlier session). |
| `work.subject` | string | optional | Opens new work, for example `invoice:INV-1842`. |
| `work.work_id` | string | optional | Continues work opened by an earlier session. |
| `work.contract_ref` | string | optional | Sent together with `contract_version` when opening work. Cannot be added or changed later. |
| `work.contract_version` | string | optional | Sent together with `contract_ref`. |

## Responses

| Status | Meaning |
|---|---|
| `200` | With streaming requested: the run's server-sent event stream. |
| `202` | The run was admitted. Poll it or open the event stream. |
| `404` | No such session in the selected tenant. |
| `409` | The idempotency key matched a run with a different body, or the session cannot admit a run. |

## Request

```bash
curl -X POST "https://api.tanomis.com/v1/sessions/ses_7d4f9c/runs" \
  -H "Authorization: Bearer $TANOMIS_TOKEN" \
  -H "X-Organization-ID: $TANOMIS_ORG" \
  -H "X-Workspace-Tenant-ID: $TANOMIS_WORKSPACE" \
  -H "Content-Type: application/json" \
  -d '{
    "input": {
      "prompt": "Draft a concise reply for the customer."
    },
    "idempotency_key": "support-case-1842-reply-1"
  }'
```

```python
import httpx

response = httpx.post(
    f"https://api.tanomis.com/v1/sessions/{session_id}/runs",
    headers={
        "Authorization": f"Bearer {token}",
        "X-Organization-ID": organization_id,
        "X-Workspace-Tenant-ID": tenant_id,
    },
    json={
        "input": {
            "prompt": "Draft a concise reply for the customer.",
        },
        "idempotency_key": "support-case-1842-reply-1",
    },
)
response.raise_for_status()
result = response.json()
```

```typescript
const response = await fetch(`https://api.tanomis.com/v1/sessions/${sessionId}/runs`, {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${token}`,
    "X-Organization-ID": organizationId,
    "X-Workspace-Tenant-ID": tenantId,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "input": {
      "prompt": "Draft a concise reply for the customer."
    },
    "idempotency_key": "support-case-1842-reply-1"
  }),
});
if (!response.ok) throw new Error(`${response.status} ${await response.text()}`);
const result = await response.json();
```

## Response

```json title="202 Accepted"
{
  "id": "run_a12bc3",
  "session_id": "ses_7d4f9c",
  "status": "running",
  "started_at": "2026-09-02T11:43:02Z"
}
```

## Attach files

Reference files that were prepared and uploaded in this session (see Prepare a file) when starting the run.

```json title="Request"
{
  "input": {
    "prompt": "Summarize the attached case."
  },
  "attachments": [
    {
      "file_id": "file_b172c9"
    }
  ],
  "idempotency_key": "case-summary-run-v1"
}
```

## Settlement-mode agents

For a settlement-mode agent, the first run in a new session must declare the work it serves. Use `work.subject` to open new work, or `work.work_id` to continue work opened by an earlier session; send either, never both. When opening work, `contract_ref` and `contract_version` may establish a contract and must be sent together. Later requests may omit the
contract or restate that exact pair, but cannot add or change it. The admitted run includes `settlement_work_id`; store it if another session may need to continue the same work. Standard-mode agents do not require a `work` object. Durable work and settlement are tenant capabilities: for a version in `settlement` mode, an unavailable settlement boundary fails session activation rather than silently running without it.

```json title="Request"
{
  "input": {
    "prompt": "Reconcile invoice INV-1842."
  },
  "work": {
    "subject": "invoice:INV-1842",
    "contract_ref": "billing/reconciliation",
    "contract_version": "2026-09"
  },
  "idempotency_key": "invoice-1842-attempt-1"
}
```

```json title="Response"
{
  "id": "run_a12bc3",
  "session_id": "ses_7d4f9c",
  "status": "running",
  "started_at": "2026-09-02T11:43:02Z",
  "settlement_work_id": "work_f61ca9"
}
```