> For the complete documentation index, see [llms.txt](https://docs.currents.dev/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.currents.dev/ai/reference/sessions.md).

# Sessions

What a Currents session holds, which keys can create and read one, how to list and delete sessions with the API, and their limits

This page is the reference for sessions. To record one, start at [Agent evidence](/ai/agent-evidence.md).

A session is one recording that an agent or a person saved to Currents: the files of a task, such as screenshots, videos, Playwright traces and logs, with a title and a status.

A session holds:

* A title, a passed or failed status, an error, and tags
* The commit, branch and pull request
* The files

A session is not a test run. It has no spec files or tests, and it does not appear in run lists, analytics or flakiness.

## Create a session

| From                                          | Use                                                                                                                       |
| --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| A shell                                       | The Currents CLI: [`currents session start`, `attach` and `share`](/resources/reporters/currents-cmd/currents-session.md) |
| An agent connected to the Currents MCP server | The Currents MCP tools. See [Record without the Currents CLI](/ai/agent-evidence/mcp-tools.md).                           |
| A script                                      | The [Sessions API](https://docs.currents.dev/api/resources/sessions)                                                      |

<figure><img src="https://3745692499-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FqmFDEiUa9mr11LUlxDnt%2Fuploads%2Fgit-blob-9df1ba8bfdac07439c1c458f2b061e50633c41bb%2Fterminal-session-cli.gif?alt=media" alt="A terminal: currents session start, attach with a folder of evidence, and share, which prints the session link and its Markdown link"><figcaption></figcaption></figure>

## Keys

| Key                                                           | Can                                                                                            |
| ------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
| [Record key](/guides/record-key.md)                           | Create a session, attach files, and share it                                                   |
| Read & Write [API key](/dashboard/administration/api-keys.md) | Everything: create, attach, share, list, read and delete                                       |
| Read Only API key                                             | List and read sessions, and create [trace API links](/ai/agentic-artifacts/explore-a-trace.md) |

## List and delete sessions

The dashboard has no list of sessions. Use the API:

* `GET /v1/projects/:projectId/sessions` lists a project's sessions, newest first. It filters by branch, tag, pull request, date and text, as the run list does.
* `DELETE /v1/sessions/:sessionId` deletes a session, its files and its links.

## Limits

* A session holds up to 200 files, of up to 1 GiB each.
* A [session link](/ai/reference/share-links.md) lasts 1, 3 or 7 days, 7 by default. A link posted in a pull request stops working after that; share the session again for a new link. See [Share links](/ai/reference/share-links.md).
* The files stay until you delete the session, within your plan's [data retention](/resources/data-privacy/data-retention.md).
* A trace holds request bodies, headers and cookies, and anyone with the link can read them. Record with test accounts.
* Anyone who has your record key can create sessions and share links in your organization. Keep it in your CI secrets, as you do for runs.
* Self-hosted Currents has no trace API, so the session page has no trace player there.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.currents.dev/ai/reference/sessions.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.