> ## 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 Direct Query API (POST /query) with the Newton Fusion model (text, image, and video reasoning) or the Newton Omega encoder (time-series embeddings). ATAI_API_ENDPOINT must include the version path: /v0.5 for most APIs, /v0.6 for the Fine-Tuning Service. Pages whose descriptions are marked (Archived) document the legacy Lens runtime — do not use them for new projects.

# Query Agent

> Send a serving agent a payload and get its answer

<Callout icon="clock" color="#3064E3" iconType="solid">
  Requires [version 1.1.12](/release-notes/1.1.x#v1-1-12) or later of the Archetype platform.
</Callout>

## 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

<ParamField path="agent_id" type="string" required>
  Serving agent `agt_` id to query.
</ParamField>

<ParamField body="body" type="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.
</ParamField>

## Response

<ResponseField name="status" type="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.
</ResponseField>

<ResponseField name="response" type="object" required>
  The agent's answer, passed through as it came back. Opaque to the platform — its shape belongs
  to the blueprint's connectors.
</ResponseField>

<ResponseField name="query_response_time_ms" type="number" required>
  Total server-side time, in milliseconds.
</ResponseField>

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

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

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

<ResponseExample>
  ```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
  }
  ```

  ```json 404 - No agent with this id theme={"system"}
  {
    "errors": [
      {
        "code": "<error_code>",
        "message": "No agent with this id in the caller's org.",
        "suggestion": null,
        "error_uid": "err-xxxxxxxx"
      }
    ]
  }
  ```

  ```json 409 - Not a running serving agent theme={"system"}
  {
    "errors": [
      {
        "code": "<error_code>",
        "message": "The agent was not run in serving mode, or is no longer running.",
        "suggestion": null,
        "error_uid": "err-xxxxxxxx"
      }
    ]
  }
  ```
</ResponseExample>

## Important Notes

<Note>
  * Start the agent with `mode: serving` on `POST /agents/bundles/{bundle_id}/run`. A `batch` run never answers this endpoint.
  * Both the request body and `response` are opaque to the platform: their shapes are the blueprint's source and sink connectors, not this endpoint's.
  * A `404` covers both an unknown id and one belonging to another organization — the two are indistinguishable by design.
  * Use `GET /agents/instances/{agent_id}/connect` when you want one open session for many payloads instead of a request per payload.
</Note>


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