curl -X POST "$ATAI_API_ENDPOINT/agents/sessions/ses_01jcg8s3v0yc6rx4n9p7mgad5e/query" \
-H "Authorization: Bearer $ATAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"records": [
{"timestamp": "2026-09-18T11:24:03Z", "vibration": 0.41, "flow": 12.6}
]
}'
import os
import requests
base_url = os.environ["ATAI_API_ENDPOINT"]
api_key = os.environ["ATAI_API_KEY"]
response = requests.post(
f"{base_url}/agents/sessions/ses_01jcg8s3v0yc6rx4n9p7mgad5e/query",
headers={"Authorization": f"Bearer {api_key}"},
json={
"records": [
{"timestamp": "2026-09-18T11:24:03Z", "vibration": 0.41, "flow": 12.6}
]
},
)
if response.status_code == 200:
print(response.json()["response"])
elif response.status_code in (429, 503):
print(f"Busy; retry after {response.headers.get('Retry-After')} seconds")
else:
print(f"Error: {response.json()['errors']}")
const response = await fetch(
`${process.env.ATAI_API_ENDPOINT}/agents/sessions/ses_01jcg8s3v0yc6rx4n9p7mgad5e/query`,
{
method: 'POST',
headers: {
'Authorization': `Bearer ${process.env.ATAI_API_KEY}`,
'Content-Type': 'application/json'
},
body: JSON.stringify({
records: [{ timestamp: '2026-09-18T11:24:03Z', vibration: 0.41, flow: 12.6 }]
})
}
);
const body = await response.json();
if (response.ok) {
console.log(body.response);
} else {
console.error('Error:', body.errors);
}
{
"status": "completed",
"response": {
"predicted_state": "running",
"p_running": 0.94,
"p_idle": 0.06
},
"query_response_time_ms": 38.4
}
Sessions
Query Session
Send one input to a serving session and get the deployed agent’s answer
POST
/
api
/
agents
/
sessions
/
{session_id}
/
query
curl -X POST "$ATAI_API_ENDPOINT/agents/sessions/ses_01jcg8s3v0yc6rx4n9p7mgad5e/query" \
-H "Authorization: Bearer $ATAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"records": [
{"timestamp": "2026-09-18T11:24:03Z", "vibration": 0.41, "flow": 12.6}
]
}'
import os
import requests
base_url = os.environ["ATAI_API_ENDPOINT"]
api_key = os.environ["ATAI_API_KEY"]
response = requests.post(
f"{base_url}/agents/sessions/ses_01jcg8s3v0yc6rx4n9p7mgad5e/query",
headers={"Authorization": f"Bearer {api_key}"},
json={
"records": [
{"timestamp": "2026-09-18T11:24:03Z", "vibration": 0.41, "flow": 12.6}
]
},
)
if response.status_code == 200:
print(response.json()["response"])
elif response.status_code in (429, 503):
print(f"Busy; retry after {response.headers.get('Retry-After')} seconds")
else:
print(f"Error: {response.json()['errors']}")
const response = await fetch(
`${process.env.ATAI_API_ENDPOINT}/agents/sessions/ses_01jcg8s3v0yc6rx4n9p7mgad5e/query`,
{
method: 'POST',
headers: {
'Authorization': `Bearer ${process.env.ATAI_API_KEY}`,
'Content-Type': 'application/json'
},
body: JSON.stringify({
records: [{ timestamp: '2026-09-18T11:24:03Z', vibration: 0.41, flow: 12.6 }]
})
}
);
const body = await response.json();
if (response.ok) {
console.log(body.response);
} else {
console.error('Error:', body.errors);
}
{
"status": "completed",
"response": {
"predicted_state": "running",
"p_running": 0.94,
"p_idle": 0.06
},
"query_response_time_ms": 38.4
}
Requires version 2.0.1 or later of the Archetype platform.
Overview
This endpoint sends one request payload to the agent of aserving session’s deployment and
returns its answer.
The body is whatever the blueprint’s source connector accepts, and response is whatever its sink
produces. Both shapes belong to the blueprint, not to this API.
The session must be running. After Create Session,
poll Get Session until it is. Anyone who can see the
session’s project can query it.
Request
Whatever the agent’s source connector accepts, as JSON. The shape belongs to the blueprint, not
to this endpoint.
Response
Whether the query produced an answer. Always
completed in a 200 response: a query that fails
returns an error status instead.curl -X POST "$ATAI_API_ENDPOINT/agents/sessions/ses_01jcg8s3v0yc6rx4n9p7mgad5e/query" \
-H "Authorization: Bearer $ATAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"records": [
{"timestamp": "2026-09-18T11:24:03Z", "vibration": 0.41, "flow": 12.6}
]
}'
import os
import requests
base_url = os.environ["ATAI_API_ENDPOINT"]
api_key = os.environ["ATAI_API_KEY"]
response = requests.post(
f"{base_url}/agents/sessions/ses_01jcg8s3v0yc6rx4n9p7mgad5e/query",
headers={"Authorization": f"Bearer {api_key}"},
json={
"records": [
{"timestamp": "2026-09-18T11:24:03Z", "vibration": 0.41, "flow": 12.6}
]
},
)
if response.status_code == 200:
print(response.json()["response"])
elif response.status_code in (429, 503):
print(f"Busy; retry after {response.headers.get('Retry-After')} seconds")
else:
print(f"Error: {response.json()['errors']}")
const response = await fetch(
`${process.env.ATAI_API_ENDPOINT}/agents/sessions/ses_01jcg8s3v0yc6rx4n9p7mgad5e/query`,
{
method: 'POST',
headers: {
'Authorization': `Bearer ${process.env.ATAI_API_KEY}`,
'Content-Type': 'application/json'
},
body: JSON.stringify({
records: [{ timestamp: '2026-09-18T11:24:03Z', vibration: 0.41, flow: 12.6 }]
})
}
);
const body = await response.json();
if (response.ok) {
console.log(body.response);
} else {
console.error('Error:', body.errors);
}
{
"status": "completed",
"response": {
"predicted_state": "running",
"p_running": 0.94,
"p_idle": 0.06
},
"query_response_time_ms": 38.4
}
Important Notes
- A
400means the body is not JSON or is larger than the service accepts (invalid_request_body), or the agent rejected the payload, with its reason in the message. Resending the same body will not succeed. - A
404means the session does not exist, belongs to another organization, or is in a project you cannot see. - A
409with the codesession_not_runningmeans the session has ended, including because its deployment stopped or failed. Open a new session. A409with the codeconflictmeans the session is abatchsession or the deployment’s agent has stopped. The message says why where that is known, and resending will not succeed. - A
429means the agent is already answering as many queries at once as it will. Retry with backoff after the number of seconds in theRetry-Afterheader. - A
500with the codeagent_failedmeans the agent processed the query and failed it, with its reason in the message. The same request produces the same answer, so do not retry it. - A
503means the agent could not be reached or did not answer in time (unavailable), or the service is already answering as many queries as it will (node_at_capacity, with aRetry-Afterheader). Retry. - A
504with the codequery_timeoutmeans the agent’s time budget ran out before it had an answer. The budget includes time spent waiting behind other queries to the same deployment, from this session or another. Send less data per query, or fewer queries at once.
Was this page helpful?