# Runs
Source: https://docs.simpleserve.ai/docs/runs
Summary: Start work, continue a session, stream progress, and stop a run.
Availability: available
Last reviewed: 2026-08-30

A run is one request to one agent. It contains the current status, output, usage, final cost, and any error.

## Start new work

```python
run = client.runs.create(
    agent="publisher/agent-name",
    input="Prepare the finished report.",
    max_cost_usd=4,
)
```

The default request waits for a terminal result. The API can return `202` if the work continues after that wait ends.

## Continue prior work

Pass the returned `session_id` to a new run.

```python
next_run = client.runs.create(
    agent="publisher/agent-name",
    input="Add a one-page executive summary.",
    session_id=run["session_id"],
    max_cost_usd=2,
)
```

There is no separate session resource. Each follow-up is a new run in the same session.

## Run in the background

```python
run = client.runs.create(
    agent="publisher/agent-name",
    input="Complete the full review.",
    max_cost_usd=5,
    background=True,
)

current = client.runs.retrieve(run["id"])
```

Use the `location` response header and `retry-after` value when a REST request returns `202`.

## Stream events

```python
for event in client.runs.stream(
    agent="publisher/agent-name",
    input="Investigate the incident.",
    max_cost_usd=3,
):
    print(event["type"])
```

The stream uses Server-Sent Events. Reconnect with `Last-Event-ID` if the connection closes.

## Cancel a run

```python
cancelled = client.runs.cancel(run["id"])
print(cancelled["status"])
```

Completed work remains in `usage` and can still have a cost.

## Status values

| Status          | Meaning                                    |
| --------------- | ------------------------------------------ |
| `queued`        | The request is waiting to start.           |
| `running`       | The agent is working.                      |
| `completed`     | The run has finished successfully.         |
| `limit_reached` | The agent stopped at the cost limit.       |
| `cancelled`     | The cancellation request stopped the work. |
| `failed`        | The run ended with an error.               |

## Safe retries

Send a unique `Idempotency-Key` with run and cancellation requests. Reusing the same key and body returns the same operation.

If you reuse the key with another body, the API returns `idempotency_conflict`.