curl -X POST "$ATAI_API_URL/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_URL"]
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_URL}/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": "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, or is no longer running.",
"suggestion": null,
"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_URL/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_URL"]
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_URL}/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": "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, or is no longer running.",
"suggestion": null,
"error_uid": "err-xxxxxxxx"
}
]
}
Requires version 1.1.12 or later of the Archetype platform.
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.Request
string
required
Serving agent
agt_ id to query.object
required
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
string
required
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.object
required
The agent’s answer, passed through as it came back. Opaque to the platform — its shape belongs
to the blueprint’s connectors.
number
required
Total server-side time, in milliseconds.
curl -X POST "$ATAI_API_URL/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_URL"]
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_URL}/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": "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, or is no longer running.",
"suggestion": null,
"error_uid": "err-xxxxxxxx"
}
]
}
Important Notes
- Start the agent with
mode: servingonPOST /agents/bundles/{bundle_id}/run. 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. - 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?