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

> ## Agent Instructions
> Start with /introduction/getting-started. Use the Inference API's Direct Query endpoint (POST /api/inference/query) with the newton-c-2.6 or newton-fusion-1.0 model (text, image, and video reasoning) or the omega-embedding encoder (time-series embeddings). ATAI_API_ENDPOINT is the base URL https://platform.u1.archetypeai.app with no version path; every endpoint path begins with /api. Pages whose descriptions are marked (Archived) document the legacy Lens runtime — do not use them for new projects.

# List Sessions

> Page through your organization's sessions, filtered by project, deployment or status

Requires [version 2.0.1](https://docs.archetypeai.app/release-notes/2.0.x.md#v2-0-1) or later of the Archetype platform.

## Overview

This endpoint returns a cursor-paginated page of the sessions of every project you can see,
newest first by default. Narrow it to one project with `project_id`, to one deployment with
`deployment_id`, to the deployments of one package with `package_id`, to one `status`, and to one
`kind`.

Choose a different ordering with `sort` and `order`. Sessions with no start or no duration come
last in either direction. Under `status`, running sessions come first in either direction. Each
group is ordered by when the session was opened.

## Request

**limit** `integer` (default: 100)

Page size. Minimum `1`, maximum `1000`.

**after** `string`

Forward cursor: return the sessions ranked after it in the current sort order. Pass the
`next_cursor` of the previous page. The cursor is opaque: never build it from session fields. Mutually exclusive with
`before`.

**before** `string`

Backward cursor: return the sessions ranked before it in the current sort order. Pass the
`prev_cursor` of the current page. The cursor is opaque: never build it from session fields. Mutually exclusive with `after`.

**project\_id** `string`

Filter by project. Omitted: the sessions of every project you can see. A project's `prj_` id:
that project's sessions only (`404` when it does not exist or you cannot see it).

**deployment\_id** `string`

Only the sessions of this deployment (`dpl_` id).

**package\_id** `string`

Only the sessions of this package's deployments (`pkg_` id). [v2.0.1+](https://docs.archetypeai.app/release-notes/2.0.x.md#v2-0-1)

**status** `string`

Only sessions in this status: `pending`, `running`, `completed`, `failed`, or `cancelled`.

**kind** `string`

Only sessions of this kind, which is their deployment's: `batch` or `serving`. [v2.0.1+](https://docs.archetypeai.app/release-notes/2.0.x.md#v2-0-1)

**sort** `string` (default: created\_at)

Sort field: `created_at` (default) by when the session was opened, `started_at` by when it
started running, `duration` by how long it ran, or `status` to put running sessions ahead of
every other. A cursor is only valid under the sort it was minted for. Replaying it with a
different `sort` returns `400`. [v2.0.1+](https://docs.archetypeai.app/release-notes/2.0.x.md#v2-0-1)

**order** `string` (default: desc)

Sort direction: `asc` or `desc` (default). Keep it constant while paging with a cursor. [v2.0.1+](https://docs.archetypeai.app/release-notes/2.0.x.md#v2-0-1)

**include\_total** `boolean` (default: false)

When `true`, the response includes `total`. Off by default because it costs an extra count per
request. [v2.0.1+](https://docs.archetypeai.app/release-notes/2.0.x.md#v2-0-1)

## Response

**data** `array` *required*

The page, in the requested `sort` and `order` (by default newest first) in both cursor
directions. Each entry is a session, with the same fields
as [Get Session](https://docs.archetypeai.app/api-reference/agents/sessions/get-session.md) returns.

**has\_more** `boolean` *required*

True when more results exist beyond this page in the direction of travel.

**next\_cursor** `string`

Cursor for the next page in the same direction. Pass it as `after` when paging forward, or as
`before` when you supplied `before`. `null` when `has_more` is false.

**prev\_cursor** `string`

Cursor to step back the way this page was reached. Pass it as `before` after paging forward, or
as `after` after paging backward. `null` on a request that carried no cursor.

**total** `integer`

How many sessions match the request's filters across all pages, ignoring `limit` and the cursor.
Present only when you set `include_total=true`. [v2.0.1+](https://docs.archetypeai.app/release-notes/2.0.x.md#v2-0-1)

```bash cURL theme={"system"}
curl "$ATAI_API_ENDPOINT/agents/sessions?deployment_id=dpl_01jcf3n8q5vx2mt7r4k6hbzd9a" \
  -H "Authorization: Bearer $ATAI_API_KEY"
```

```bash cURL - Running Serving Sessions First theme={"system"}
curl "$ATAI_API_ENDPOINT/agents/sessions?kind=serving&sort=status&include_total=true" \
  -H "Authorization: Bearer $ATAI_API_KEY"
```

```python Python theme={"system"}
import os
import requests

base_url = os.environ["ATAI_API_ENDPOINT"]
api_key = os.environ["ATAI_API_KEY"]

response = requests.get(
    f"{base_url}/agents/sessions",
    headers={"Authorization": f"Bearer {api_key}"},
    params={"deployment_id": "dpl_01jcf3n8q5vx2mt7r4k6hbzd9a", "limit": 20},
)

if response.status_code == 200:
    page = response.json()
    for session in page["data"]:
        print(session["id"], session["status"])
else:
    print(f"Error: {response.json()['errors']}")
```

```javascript JavaScript theme={"system"}
const response = await fetch(
  `${process.env.ATAI_API_ENDPOINT}/agents/sessions?deployment_id=dpl_01jcf3n8q5vx2mt7r4k6hbzd9a`,
  {
    headers: {
      'Authorization': `Bearer ${process.env.ATAI_API_KEY}`
    }
  }
);

const body = await response.json();

if (response.ok) {
  body.data.forEach((session) => console.log(session.id, session.status));
} else {
  console.error('Error:', body.errors);
}
```

```json 200 - Page of sessions theme={"system"}
{
  "data": [
    {
      "id": "ses_01jcf4p9r6wy3nv8s5m7jcae0b",
      "deployment_id": "dpl_01jcf3n8q5vx2mt7r4k6hbzd9a",
      "package_id": "pkg_01jcb2x7m4qv8n3h5t6rk9dzs0",
      "org_id": "org_01jc8m5r2vq9xt4bn7h3kdzs6w",
      "project_id": "prj_01jcd4m8t2vq6xn3r7k5hbzw9e",
      "created_by": "usr_01jc8m6t3wr0yv5cp8j4mezt7x",
      "kind": "batch",
      "status": "running",
      "connectors": {
        "source": [{"type": "file", "id": "file_abc123", "format": "csv"}]
      },
      "job_id": "job_01jcf4q2s7xz4pw9t6n8kdbf1c",
      "error": null,
      "created_at": "2026-10-29T16:05:00Z",
      "started_at": "2026-10-29T16:05:02Z",
      "completed_at": null
    }
  ],
  "has_more": false,
  "next_cursor": null,
  "prev_cursor": null
}
```

## Important Notes

> [!NOTE]
>
> * Passing both `after` and `before` returns `400`, as does a malformed cursor, a cursor minted under another `sort`, or an invalid `project_id`, `deployment_id`, `package_id`, `status`, `kind`, `sort`, or `order`.
> * A `project_id` that does not exist or that you cannot see returns `404`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.