---
title: "Query"
method: POST
path: "/agents/{agent_id}/query"
tags: ["/agents/{id}/query"]
---

# Query

`POST /agents/{agent_id}/query`

Start a conversation with an `Agent` and receive its generated response, along with relevant retrieved data and attributions.

## Path parameters

- `agent_id` string, uuid, required — Agent ID of the agent to query

## Query parameters

- `retrievals_only` boolean — Set to `true` to fetch retrieval content and metadata, and then skip generation of the response.
- `include_retrieval_content_text` boolean — Set to `true` to include the text of the retrieved contents in the response. If `false`, only metadata about the retrieved contents will be included, not content text. This parameter is ignored if `retrievals_only` is `true`, in which case `content_text` will always be returned. Content text and other metadata can also be fetched separately using the `/agents/{agent_id}/query/{message_id}/retrieval/info` endpoint.

## Request body

- QueryRequestV1 — Request body for a POST `/agents/{agent_id}/query` request
  - `messages` MessageAndRole[], required — Messages sent so far in the conversation, ending in the latest user message. Add multiple objects to provide conversation history. Last message in the list must be a `user`-sent message (i.e. `role` equals `"user"`).
    - `content` string, required — Content of the message
    - `role` 'user' | 'system' | 'assistant' | 'knowledge', required
  - `stream` boolean — Set to `true` to receive a streamed response
  - `conversation_id` string, uuid — An optional alternative to providing message history in the `messages` field. If provided, all messages in the `messages` list prior to the latest user-sent query will be ignored.
  - `llm_model_id` string — Model ID of the specific fine-tuned or aligned LLM model to use. Defaults to base model if not specified.

## Response `200`

Successful Response

- QueryResponse — Response body for POST /query
  - `conversation_id` string, uuid, required — A unique identifier for the conversation. Can be passed to future `/query` calls to continue a conversation with the same message history.
  - `message_id` string, uuid — A unique identifier for this specific message
  - `message` MessageAndRole — Message object for a message sent or received in a /query and /generate conversation
    - `content` string, required — Content of the message
    - `role` 'user' | 'system' | 'assistant' | 'knowledge', required
  - `retrieval_contents` RetrievalContentV01[], required — Relevant content retrieved to answer the query
    - `number` integer — Index of the retrieved item in the retrieval_contents list (starting from 1)
    - `type` string, required — Source type of the content. Will be `file` for any docs ingested through ingestion API.
    - `format` 'pdf' | 'html' | 'htm', required — Format of the content, such as `pdf` or `html`
    - `content_id` string, required — Unique identifier of the retrieved content
    - `doc_id` string, required — Unique identifier of the document
    - `doc_name` string, required — Name of the document
    - `page` integer — Page number of the content in the document
    - `content_text` string — Text of the retrieved content. Included in response to a query if `include_retrieval_content_text` is True
    - `url` string — URL of the source content, if applicable
  - `attributions` AttributionV01[] — Attributions for the response
    - `start_idx` integer, required — Start index of the attributed text in the generated message
    - `end_idx` integer, required — End index of the attributed text in the generated message
    - `content_ids` string[], required — Content IDs of the sources for the attributed text

## Other responses

- `422` — Validation Error

## Changes

- **2025-02-26** `5298551c424b` — 2 warning, 1 info
  - added the new `htm` enum value to the `retrieval_contents/items/format` response property for the response status `200`
  - added the new `knowledge` enum value to the `message/role` response property for the response status `200`
  - added the new `knowledge` enum value to the request property `messages/items/role`
- **2025-02-08** `d79ccb778953` — 2 warning, 2 info
  - removed the optional property `retrieval_contents/items/content` from the response with the `200` status
  - removed the optional property `retrieval_contents/items/extras` from the response with the `200` status
  - added the new optional `query` request parameter `include_retrieval_content_text`
  - added the optional property `retrieval_contents/items/content_text` to the response with the `200` status
- **2025-01-15** `4ed32c3243ce` — 1 warning, 1 info
  - removed the request property `model_id`
  - added the new optional request property `llm_model_id`
- **2025-01-14** `4dd01a1cc34b` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/contextualai/apis/endpoints/changes/agents/:agent_id/query/post.md)

---

[API](https://skmtc.dev/contextualai/apis/endpoints.md) · [All operations](https://skmtc.dev/contextualai/apis/endpoints/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/contextualai/endpoints/revisions/5298551c424b/schema)