curl -X POST "$ATAI_API_ENDPOINT/agents/instances/agt_01jc9q8v5nm3ry7t2bkz4dhs6f/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/instances/agt_01jc9q8v5nm3ry7t2bkz4dhs6f/query",
headers={
"Authorization": f"Bearer {api_key}",
"Content-Type": "application/json",
},
json={
"records": [
{"timestamp": "2026-09-18T11:24:03Z", "vibration": 0.41, "flow": 12.6}
]
},
)
if response.status_code == 200:
body = response.json()
print(f"{body['status']} in {body['query_response_time_ms']} ms")
print(body["response"])
else:
print(f"Error: {response.json()['errors']}")
const response = await fetch(
`${process.env.ATAI_API_ENDPOINT}/agents/instances/agt_01jc9q8v5nm3ry7t2bkz4dhs6f/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.status} in ${body.query_response_time_ms} ms`);
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
}
{
"errors": [
{
"code": "<error_code>",
"message": "The agent rejected this payload; its reason is in the message.",
"suggestion": null,
"error_uid": "err-xxxxxxxx"
}
]
}
{
"errors": [
{
"code": "<error_code>",
"message": "No agent with this id in the caller's org.",
"suggestion": null,
"error_uid": "err-xxxxxxxx"
}
]
}
{
"errors": [
{
"code": "<error_code>",
"message": "The agent was not run in serving mode, is no longer running, or has stopped on its worker.",
"suggestion": null,
"error_uid": "err-xxxxxxxx"
}
]
}
{
"errors": [
{
"code": "<error_code>",
"message": "The agent is already answering as many queries at once as it will; retry with backoff.",
"suggestion": null,
"error_uid": "err-xxxxxxxx"
}
]
}
{
"errors": [
{
"code": "<error_code>",
"message": "Serving is not enabled in this environment.",
"suggestion": null,
"error_uid": "err-xxxxxxxx"
}
]
}
{
"errors": [
{
"code": "unavailable",
"message": "The agent could not be reached or did not answer in time.",
"suggestion": null,
"error_uid": "err-xxxxxxxx"
}
]
}
{
"errors": [
{
"code": "node_at_capacity",
"message": "This node is already answering as many queries as it will.",
"suggestion": null,
"error_uid": "err-xxxxxxxx"
}
]
}
{
"errors": [
{
"code": "query_timeout",
"message": "The agent reported that its time budget ran out.",
"suggestion": null,
"error_uid": "err-xxxxxxxx"
}
]
}
{
"errors": [
{
"code": "query_timeout",
"message": "agent 'agt_01jc9q8v5nm3ry7t2bkz4dhs6f' did not answer within its time budget; send less data per query, or fewer queries at once",
"suggestion": "Send less data per query, or fewer queries at once.",
"error_uid": "err-xxxxxxxx"
}
]
}
Instances
Query Agent
Send a serving agent a payload and get its answer
POST
/
agents
/
instances
/
{agent_id}
/
query
curl -X POST "$ATAI_API_ENDPOINT/agents/instances/agt_01jc9q8v5nm3ry7t2bkz4dhs6f/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/instances/agt_01jc9q8v5nm3ry7t2bkz4dhs6f/query",
headers={
"Authorization": f"Bearer {api_key}",
"Content-Type": "application/json",
},
json={
"records": [
{"timestamp": "2026-09-18T11:24:03Z", "vibration": 0.41, "flow": 12.6}
]
},
)
if response.status_code == 200:
body = response.json()
print(f"{body['status']} in {body['query_response_time_ms']} ms")
print(body["response"])
else:
print(f"Error: {response.json()['errors']}")
const response = await fetch(
`${process.env.ATAI_API_ENDPOINT}/agents/instances/agt_01jc9q8v5nm3ry7t2bkz4dhs6f/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.status} in ${body.query_response_time_ms} ms`);
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
}
{
"errors": [
{
"code": "<error_code>",
"message": "The agent rejected this payload; its reason is in the message.",
"suggestion": null,
"error_uid": "err-xxxxxxxx"
}
]
}
{
"errors": [
{
"code": "<error_code>",
"message": "No agent with this id in the caller's org.",
"suggestion": null,
"error_uid": "err-xxxxxxxx"
}
]
}
{
"errors": [
{
"code": "<error_code>",
"message": "The agent was not run in serving mode, is no longer running, or has stopped on its worker.",
"suggestion": null,
"error_uid": "err-xxxxxxxx"
}
]
}
{
"errors": [
{
"code": "<error_code>",
"message": "The agent is already answering as many queries at once as it will; retry with backoff.",
"suggestion": null,
"error_uid": "err-xxxxxxxx"
}
]
}
{
"errors": [
{
"code": "<error_code>",
"message": "Serving is not enabled in this environment.",
"suggestion": null,
"error_uid": "err-xxxxxxxx"
}
]
}
{
"errors": [
{
"code": "unavailable",
"message": "The agent could not be reached or did not answer in time.",
"suggestion": null,
"error_uid": "err-xxxxxxxx"
}
]
}
{
"errors": [
{
"code": "node_at_capacity",
"message": "This node is already answering as many queries as it will.",
"suggestion": null,
"error_uid": "err-xxxxxxxx"
}
]
}
{
"errors": [
{
"code": "query_timeout",
"message": "The agent reported that its time budget ran out.",
"suggestion": null,
"error_uid": "err-xxxxxxxx"
}
]
}
{
"errors": [
{
"code": "query_timeout",
"message": "agent 'agt_01jc9q8v5nm3ry7t2bkz4dhs6f' did not answer within its time budget; send less data per query, or fewer queries at once",
"suggestion": "Send less data per query, or fewer queries at once.",
"error_uid": "err-xxxxxxxx"
}
]
}
Requires version 1.1.12 or later of the Archetype platform.
Starting with version 2.0.1, this endpoint is removed from the platform. Use Query Session on a serving session instead. To move existing code, see Migrating from Bundles and Instances.
Overview
This endpoint sends a payload to a running serving agent and returns its answer. The body is whatever the blueprint’s source connector accepts, and the answer is whatever its sink produces — the platform passes both through unchanged and wraps the answer in the fields every serving agent reports the same way. Some failures are final and some are worth retrying:400— the agent itself rejected the payload. Its reason is passed through, and resending the same body will not succeed.409— the agent was not run in serving mode, is no longerrunning, or has stopped on its worker. The message says why the run ended where that is known, and resending will not succeed.429— the agent is already answering as many queries at once as it will. The same request succeeds once one of them finishes, so retry it with backoff.503— the agent cannot be reached or did not answer in time (unavailable), or this node is already answering as many queries as it will (node_at_capacity). Both are worth retrying. An agent that does not answer before this service stops waiting is answered503.504— the agent reports that its time budget ran out before it had an answer (query_timeout). The budget counts from when the agent accepted the query, so it includes time spent waiting behind other queries to it; send less data per query, or fewer queries at once.501— serving is not enabled in this environment.
429 responses, and 503 responses with node_at_capacity, carry a Retry-After header giving
the number of seconds to wait before sending the query again.
Request
Whatever the agent’s source connector accepts. The shape belongs to the blueprint, not to this
endpoint — see the blueprint’s source connector for what it takes.
Response
Whether the query produced an answer:
completed or failed. Over HTTP the status line
already says so, and this is only ever completed; the failed value exists for the
/connect frame protocol, where there is no status line.The agent’s answer, passed through as it came back. Opaque to the platform — its shape belongs
to the blueprint’s connectors.
curl -X POST "$ATAI_API_ENDPOINT/agents/instances/agt_01jc9q8v5nm3ry7t2bkz4dhs6f/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/instances/agt_01jc9q8v5nm3ry7t2bkz4dhs6f/query",
headers={
"Authorization": f"Bearer {api_key}",
"Content-Type": "application/json",
},
json={
"records": [
{"timestamp": "2026-09-18T11:24:03Z", "vibration": 0.41, "flow": 12.6}
]
},
)
if response.status_code == 200:
body = response.json()
print(f"{body['status']} in {body['query_response_time_ms']} ms")
print(body["response"])
else:
print(f"Error: {response.json()['errors']}")
const response = await fetch(
`${process.env.ATAI_API_ENDPOINT}/agents/instances/agt_01jc9q8v5nm3ry7t2bkz4dhs6f/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.status} in ${body.query_response_time_ms} ms`);
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
}
{
"errors": [
{
"code": "<error_code>",
"message": "The agent rejected this payload; its reason is in the message.",
"suggestion": null,
"error_uid": "err-xxxxxxxx"
}
]
}
{
"errors": [
{
"code": "<error_code>",
"message": "No agent with this id in the caller's org.",
"suggestion": null,
"error_uid": "err-xxxxxxxx"
}
]
}
{
"errors": [
{
"code": "<error_code>",
"message": "The agent was not run in serving mode, is no longer running, or has stopped on its worker.",
"suggestion": null,
"error_uid": "err-xxxxxxxx"
}
]
}
{
"errors": [
{
"code": "<error_code>",
"message": "The agent is already answering as many queries at once as it will; retry with backoff.",
"suggestion": null,
"error_uid": "err-xxxxxxxx"
}
]
}
{
"errors": [
{
"code": "<error_code>",
"message": "Serving is not enabled in this environment.",
"suggestion": null,
"error_uid": "err-xxxxxxxx"
}
]
}
{
"errors": [
{
"code": "unavailable",
"message": "The agent could not be reached or did not answer in time.",
"suggestion": null,
"error_uid": "err-xxxxxxxx"
}
]
}
{
"errors": [
{
"code": "node_at_capacity",
"message": "This node is already answering as many queries as it will.",
"suggestion": null,
"error_uid": "err-xxxxxxxx"
}
]
}
{
"errors": [
{
"code": "query_timeout",
"message": "The agent reported that its time budget ran out.",
"suggestion": null,
"error_uid": "err-xxxxxxxx"
}
]
}
{
"errors": [
{
"code": "query_timeout",
"message": "agent 'agt_01jc9q8v5nm3ry7t2bkz4dhs6f' did not answer within its time budget; send less data per query, or fewer queries at once",
"suggestion": "Send less data per query, or fewer queries at once.",
"error_uid": "err-xxxxxxxx"
}
]
}
Important Notes
- Start the agent with
mode: servingon Run Bundle. Abatchrun never answers this endpoint. - Both the request body and
responseare opaque to the platform: their shapes are the blueprint’s source and sink connectors, not this endpoint’s. - A
404covers both an unknown id and one belonging to another organization — the two are indistinguishable by design. - Retry
429and503with backoff, honoringRetry-Afterwhen it is sent. Don’t resend a400or409unchanged; it will not succeed. - Use Connect to Agent when you want one open session for many payloads instead of a request per payload.
- A
409means the agent is not a running serving agent. When the agent has stopped, the message says why:agent '<agent_id>' is no longer running: <reason>. A failed run gives its error as the reason. A serving agent that the platform released after going unused for the deployment’s idle window endscompleted, and its reason readsreleased after <idle window> without a query; run the agent again. A released agent does not come back: start a new one withmode: servingonPOST /agents/bundles/{bundle_id}/run. v2.0.0+ - A
504with codequery_timeoutmeans the agent ran out of its time budget before it had an answer. The budget starts when the agent accepts the query, so it includes time spent waiting behind other queries to the same agent. Resending the same query unchanged times out again, and the response carries noRetry-Afterheader. Send less data per query, or fewer queries at once. v2.0.0+ - A
500with codeagent_failedmeans the agent processed the query and failed it. The message carries the agent’s reason unchanged, and the response has noRetry-Afterheader. Don’t retry it: the same query fails the same way. Change the query instead. v2.0.1+ - A
503means the agent could not be reached or did not answer before the platform stopped waiting. It is worth retrying with backoff. - Use
GET /agents/instances/{agent_id}/connectwhen you want one open session for many payloads instead of a request per payload.
Was this page helpful?