> ## Documentation Index
> Fetch the complete documentation index at: https://docs.archetypeai.app/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Start with /introduction/getting-started. Use the Inference API's Direct Query endpoint (POST /api/inference/query) with the newton-c-2.6 or newton-fusion-1.0 model (text, image, and video reasoning) or the omega-embedding encoder (time-series embeddings). ATAI_API_ENDPOINT is the base URL https://platform.u1.archetypeai.app with no version path; every endpoint path begins with /api. Pages whose descriptions are marked (Archived) document the legacy Lens runtime — do not use them for new projects.

# Query Session

> Send one input to a serving session and get the deployed agent's answer

Requires [version 2.0.1](https://docs.archetypeai.app/release-notes/2.0.x.md#v2-0-1) or later of the Archetype platform.

## Overview

This endpoint sends one request payload to the agent of a `serving` 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](https://docs.archetypeai.app/api-reference/agents/sessions/create-session.md),
poll [Get Session](https://docs.archetypeai.app/api-reference/agents/sessions/get-session.md) until it is. Anyone who can see the
session's project can query it.

## Request

**session\_id** `string` *required*

Session `ses_` id.

**body** `object` *required*

Whatever the agent's source connector accepts, as JSON. The shape belongs to the blueprint, not
to this endpoint.

## Response

**status** `string` *required*

Whether the query produced an answer. Always `completed` in a `200` response: a query that fails
returns an error status instead.

**response** `object` *required*

The agent's answer, passed through as it came back.

**query\_response\_time\_ms** `number` *required*

Total server-side time, in milliseconds.

```bash cURL theme={"system"}
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}
    ]
  }'
```

```python Python theme={"system"}
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']}")
```

```javascript JavaScript theme={"system"}
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);
}
```

```json 200 - The agent's answer theme={"system"}
{
  "status": "completed",
  "response": {
    "predicted_state": "running",
    "p_running": 0.94,
    "p_idle": 0.06
  },
  "query_response_time_ms": 38.4
}
```

## Important Notes

> [!NOTE]
>
> * A `400` means 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 `404` means the session does not exist, belongs to another organization, or is in a project you cannot see.
> * A `409` with the code `session_not_running` means the session has ended, including because its deployment stopped or failed. Open a new session. A `409` with the code `conflict` means the session is a `batch` session or the deployment's agent has stopped. The message says why where that is known, and resending will not succeed.
> * A `429` means the agent is already answering as many queries at once as it will. Retry with backoff after the number of seconds in the `Retry-After` header.
> * A `500` with the code `agent_failed` means 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 `503` means 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 a `Retry-After` header). Retry.
> * A `504` with the code `query_timeout` means 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.