---
title: "Sessions · Ataris docs"
description: "What a session is, how the CLI starts and ends one, its states, and its tags."
canonical: "https://ataris.dev/docs/concepts/sessions"
last-updated: 2026-10-12
---
# Sessions

What a session is, how the CLI starts and ends one, its states, and its tags.

Every traced run in Ataris is a **session**: one run, one timeline. The [`ataris` CLI](/docs/guides/cli) starts a session when it starts the agent, and finishes it when the agent exits.

```bash
ataris --tag team:infra claude -p "Fix the failing tests"
```

## Lifecycle

1. **Start.** The CLI creates the session in your workspace, with the command, the mission it read from the prompt, and the session's tags. The session starts in `running`. On Starter, a new session needs credit left for the cycle; without it the CLI stops with a `plan_limit` error before the agent starts.
2. **Record.** Events stream to the session in batches as the agent works, so the timeline fills in live.
3. **Finish.** When the agent exits, the CLI finishes the session: `succeeded` on exit code 0, `failed` otherwise. The CLI exits with the agent's exit code, so a CI step still passes or fails on the agent's result.

## Session states

| State | Meaning |
| --- | --- |
| `running` | The agent is live. |
| `succeeded` | The agent exited with code 0. |
| `failed` | The agent exited non-zero, or couldn't start. `stateReason` says why. |
| `stopped` | The session was stopped before the agent finished. |

`succeeded`, `failed`, and `stopped` are terminal. Finishing a session that has already ended returns `409 conflict`.

## Tags

Every session carries `key:value` tags. The dashboard filters and groups sessions by tag, and [policies](/docs/concepts/policies) target sessions by tag. See [Tags and missions](/docs/concepts/agents).

## What a session records

Each session holds the run's [trace events](/docs/concepts/trace-events), the skills and MCP tools the agent used, the models it ran on, and counts of its events and flagged events. Read them in the dashboard, with the [SDK](/docs/reference/sdk), or over the [REST API](/docs/reference/api).