> ## 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.

# Get Session

> Fetch one session by id to follow its 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 one session by its `ses_` id. Poll it to follow a batch session from
`pending` to `running` and then to `completed`, `failed`, or `cancelled`.

## Request

**session\_id** `string` *required*

Session `ses_` id.

## Response

Returns the session, with the same fields as [Create
Session](https://docs.archetypeai.app/api-reference/agents/sessions/create-session.md) returns.

**id** `string` *required*

The session's `ses_` id.

**deployment\_id** `string` *required*

The deployment the session runs in.

**status** `string` *required*

Where the session is in its lifecycle: `pending`, `running`, `completed`, `failed`, or
`cancelled`.

**job\_id** `string`

The job running a batch session, once it has been dispatched; `null` before that and for a
serving session.

**error** `string`

Why the session `failed`, or why the platform cancelled it; `null` otherwise.

**values** `object`

The session's own `values`; `null` when it has none. [v2.0.1+](https://docs.archetypeai.app/release-notes/2.0.x.md#v2-0-1)

### How a serving session ends on its own

Besides being cancelled or ended with its deployment, a `serving` session can end on its own. Its
`status` and `error` then say how:

| What happened | `status` | `error` |
| - | - | - |
| Unused for its idle timeout, or completed | `completed` | `null` |
| Closed on its worker | `cancelled` | `session closed on the worker` |
| A node failed | `failed` | ``node `<node>` failed`` |
| Failed otherwise | `failed` | `the session failed` |
| The agent stopped | `failed` | `the deployment's agent stopped` |
| The worker lost it | `failed` | `the worker no longer knows this session` |
| The worker no longer runs the deployment | `failed` | `the worker no longer runs this deployment` |
| The worker left | `failed` | `the worker holding this session left` |
| An unknown cause | `failed` | `the session ended for a reason the service does not know` |

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

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

base_url = os.environ["ATAI_API_ENDPOINT"]
api_key = os.environ["ATAI_API_KEY"]
url = f"{base_url}/agents/sessions/ses_01jcf4p9r6wy3nv8s5m7jcae0b"

while True:
    response = requests.get(url, headers={"Authorization": f"Bearer {api_key}"})
    if response.status_code != 200:
        print(f"Error: {response.json()['errors']}")
        break

    session = response.json()
    if session["status"] in ("completed", "failed", "cancelled"):
        print(session["status"], session["error"])
        break
    time.sleep(10)
```

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

const body = await response.json();

if (response.ok) {
  console.log(body.status);
} else {
  console.error('Error:', body.errors);
}
```

```json 200 - The session theme={"system"}
{
  "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": "completed",
  "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": "2026-10-29T16:12:40Z",
  "values": null
}
```

## Important Notes

> [!NOTE]
>
> * A `404` means the session does not exist, belongs to another organization, or is in a project you cannot see.


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