curl "$ATAI_API_ENDPOINT/agents/sessions/ses_01jcf4p9r6wy3nv8s5m7jcae0b" \
-H "Authorization: Bearer $ATAI_API_KEY"
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)
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);
}
{
"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
}
Sessions
Get Session
Fetch one session by id to follow its status
GET
/
api
/
agents
/
sessions
/
{session_id}
curl "$ATAI_API_ENDPOINT/agents/sessions/ses_01jcf4p9r6wy3nv8s5m7jcae0b" \
-H "Authorization: Bearer $ATAI_API_KEY"
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)
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);
}
{
"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
}
Requires version 2.0.1 or later of the Archetype platform.
Overview
This endpoint returns one session by itsses_ id. Poll it to follow a batch session from
pending to running and then to completed, failed, or cancelled.
Request
Response
Returns the session, with the same fields as Create Session returns.Where the session is in its lifecycle:
pending, running, completed, failed, or
cancelled.The job running a batch session, once it has been dispatched;
null before that and for a
serving session.The session’s own
values; null when it has none. v2.0.1+How a serving session ends on its own
Besides being cancelled or ended with its deployment, aserving 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 |
curl "$ATAI_API_ENDPOINT/agents/sessions/ses_01jcf4p9r6wy3nv8s5m7jcae0b" \
-H "Authorization: Bearer $ATAI_API_KEY"
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)
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);
}
{
"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
- A
404means the session does not exist, belongs to another organization, or is in a project you cannot see.
Was this page helpful?