curl "$ATAI_API_ENDPOINT/agents/sessions?deployment_id=dpl_01jcf3n8q5vx2mt7r4k6hbzd9a" \
-H "Authorization: Bearer $ATAI_API_KEY"
curl "$ATAI_API_ENDPOINT/agents/sessions?kind=serving&sort=status&include_total=true" \
-H "Authorization: Bearer $ATAI_API_KEY"
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']}")
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);
}
{
"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
}
Sessions
List Sessions
Page through your organization’s sessions, filtered by project, deployment or status
GET
/
api
/
agents
/
sessions
curl "$ATAI_API_ENDPOINT/agents/sessions?deployment_id=dpl_01jcf3n8q5vx2mt7r4k6hbzd9a" \
-H "Authorization: Bearer $ATAI_API_KEY"
curl "$ATAI_API_ENDPOINT/agents/sessions?kind=serving&sort=status&include_total=true" \
-H "Authorization: Bearer $ATAI_API_KEY"
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']}")
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);
}
{
"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
}
Requires version 2.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 withproject_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
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.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.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).Only the sessions of this package’s deployments (
pkg_ id). v2.0.1+Only sessions of this kind, which is their deployment’s:
batch or serving. v2.0.1+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+Sort direction:
asc or desc (default). Keep it constant while paging with a cursor. v2.0.1+When
true, the response includes total. Off by default because it costs an extra count per
request. v2.0.1+Response
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 returns.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.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.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+curl "$ATAI_API_ENDPOINT/agents/sessions?deployment_id=dpl_01jcf3n8q5vx2mt7r4k6hbzd9a" \
-H "Authorization: Bearer $ATAI_API_KEY"
curl "$ATAI_API_ENDPOINT/agents/sessions?kind=serving&sort=status&include_total=true" \
-H "Authorization: Bearer $ATAI_API_KEY"
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']}")
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);
}
{
"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
- Passing both
afterandbeforereturns400, as does a malformed cursor, a cursor minted under anothersort, or an invalidproject_id,deployment_id,package_id,status,kind,sort, ororder. - A
project_idthat does not exist or that you cannot see returns404.
Was this page helpful?