---
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.
  - `structured_output` StructuredOutput
    - `type` 'JSON' — This captures type of the structured data.
    - `json_schema` object, required — The output json structure.
  - `documents_filters` union — Defines an Optional custom metadata filter, which can be a list of filters or nested filters. The expected input is a nested JSON object that can represent a single filter or a composite (logical) combination of filters. Unnested Example: ```json { "operator": "AND", "filters": [ {"field": "status", "operator": "equals", "value": "active"}, ] } ``` Nested example: ```json { "operator": "AND", "filters": [ {"field": "status", "operator": "equals", "value": "active"}, { "operator": "OR", "filters": [ {"field": "category", "operator": "containsany", "value": ["policy", "HR"]}, {"field": "tags", "operator": "exists"} ] } ] } ```
    - BaseMetadataFilter — Defines a custom metadata filter. The expected input is a dict which can have different operators, fields and values. For example: {"field": "title", "operator": "startswith", "value": "hr-"} For document_id and date_created the query is built using direct query without nesting.
      - `field` string, required — Field name to search for in the metadata
      - `operator` 'equals' | 'containsany' | 'exists' | 'startswith' | 'gt' | 'gte' | 'lt' | 'lte' | 'notequals' | 'between', required
      - `value` union — The value to be searched for in the field. In case of exists operator, it is not needed.
        - string
        - integer
        - number
        - boolean
        - union[]
          - union
            - string
            - integer
            - number
            - boolean
    - CompositeMetadataFilter — "Defines a custom metadata filter as a Composite MetadataFilter. Which can be be a list of filters or nested filters.
      - `filters` union[], required — Filters added to the query for filtering docs
        - union
          - BaseMetadataFilter — Defines a custom metadata filter. The expected input is a dict which can have different operators, fields and values. For example: {"field": "title", "operator": "startswith", "value": "hr-"} For document_id and date_created the query is built using direct query without nesting.
            - `field` string, required — Field name to search for in the metadata
            - `operator` 'equals' | 'containsany' | 'exists' | 'startswith' | 'gt' | 'gte' | 'lt' | 'lte' | 'notequals' | 'between', required
            - `value` union — The value to be searched for in the field. In case of exists operator, it is not needed.
              - …
          - CompositeMetadataFilter — recursive
      - `operator` 'AND' | 'OR' | 'AND_NOT'

## 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 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' | 'mhtml' | 'doc' | 'docx' | 'ppt' | 'pptx', 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
    - `score` number — Score of the retrieval, 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
  - `groundedness_scores` GroundednessScore[] — Groundedness scores for the response
    - `start_idx` integer, required — Start index of the span in the generated message
    - `end_idx` integer, required — End index of the span in the generated message
    - `score` integer, required — Groundedness score for the span

## Other responses

- `422` — Validation Error

## Changes

- **2025-05-08** `17bdb8a33fb4` — 2 info
  - added the new optional request property `structured_output`
  - added the optional property `retrieval_contents/items/score` to the response with the `200` status
- **2025-03-11** `194878b194cd` — 5 warning, 2 info
  - added the new `doc` enum value to the `retrieval_contents/items/format` response property for the response status `200`
  - added the new `docx` enum value to the `retrieval_contents/items/format` response property for the response status `200`
  - added the new `mhtml` enum value to the `retrieval_contents/items/format` response property for the response status `200`
  - added the new `ppt` enum value to the `retrieval_contents/items/format` response property for the response status `200`
  - …3 more
- **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`
- …earlier changes not shown

[Full 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/17bdb8a33fb4/schema)