> ## Documentation Index
> Fetch the complete documentation index at: https://docs.attensira.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Sessions

> List the agent's sessions, stop one, delete one, or hand it more context: the REST endpoints behind list_sessions, cancel_session, delete_session and add_context.

A **session** is one piece of agent work: an `ask`, an automation run, a chat, or the [set-up run](/start/set-up-run). `GET /v1/sessions/{id}` reads one (see [Endpoints](/api/endpoints#get-v1sessionsid)). The endpoints on this page list them and act on them.

Each has an MCP twin with the same payload: `list_sessions`, `cancel_session`, `delete_session` and `add_context`. See the [tool reference](/mcp/tools#sessions).

## GET /v1/sessions

<Info>Read-only. No credits. MCP tool: `list_sessions`.</Info>

Sessions, newest first.

| Parameter | In    | Type    | Default | Notes                                                                                                                                                                               |
| --------- | ----- | ------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `status`  | query | string  | —       | `complete`, `running` or `failed`, or a stored state: `queued`, `running`, `awaiting_person`, `suspended`, `completed`, `failed`, `cancelled`. Comma-separate or repeat for several |
| `origin`  | query | string  | —       | `user`, `automation`, `mcp` or `setup`. Comma-separate or repeat                                                                                                                    |
| `since`   | query | string  | —       | RFC 3339 timestamp or `YYYY-MM-DD`                                                                                                                                                  |
| `limit`   | query | integer | 50      | 1–200                                                                                                                                                                               |

```bash Shell theme={null}
curl -G https://api.attensira.com/v1/sessions \
  --data-urlencode "status=running" --data-urlencode "origin=automation" \
  -H "Authorization: Bearer atn_live_<your key>"
```

```json Response theme={null}
{
  "sessions": [
    {
      "id": "ses_9d02",
      "title": "Daily win plan",
      "origin": "automation",
      "status": "running",
      "state": "running",
      "automation_id": "aut_71cd",
      "created_at": "2026-09-23T06:00:02Z",
      "ended_at": null
    }
  ]
}
```

`status` is the three-word vocabulary (`complete`, `running`, `failed`); `state` is the finer stored word. A cancelled session reads `failed` under `status` and `cancelled` under `state`.

## POST /v1/sessions/\{id}/cancel

<Info>No credits. Works on a spent balance. MCP tool: `cancel_session`.</Info>

Stops a running session before its next step. Credits already spent on it stay spent.

Idempotent: cancelling twice is the same as cancelling once. If the run already finished, the call returns that real ending unchanged; a cancel never rewrites a finished run.

```json Response theme={null}
{ "id": "ses_9d02", "status": "failed", "state": "cancelled" }
```

## DELETE /v1/sessions/\{id}

<Warning>Destructive. MCP tool: `delete_session`.</Warning>

Permanently deletes a finished session and its trace. A running session answers `409`: cancel it first.

```json Response theme={null}
{ "id": "ses_9d02", "deleted": true }
```

## POST /v1/sessions/\{id}/context

<Warning>Spends credits only with `run: true`. MCP tool: `add_context`.</Warning>

Gives a session text or links it cannot find itself. The agent reads it as a message in the thread.

| Field  | Type      | Notes                         |
| ------ | --------- | ----------------------------- |
| `text` | string    | At most 20,000 characters     |
| `urls` | string\[] | `http` or `https`, at most 10 |
| `run`  | boolean   | Default `false`               |

Send `text`, `urls`, or both.

* **`run: false`** (default): nothing starts. The session's next turn reads the context, and a run already in flight picks it up when its current turn ends.
* **`run: true`**: the session is queued again to act on it now. That is a new turn, and it costs credits.

A cancelled session refuses new context.

```bash Shell theme={null}
curl -X POST https://api.attensira.com/v1/sessions/ses_9d02/context \
  -H "Authorization: Bearer atn_live_<your key>" \
  -H "Content-Type: application/json" \
  -d '{"text":"Our pricing page moved to /plans last week.","urls":["https://acme.com/plans"],"run":false}'
```

```json Response theme={null}
{ "session_id": "ses_9d02", "status": "running" }
```