---
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
    - `custom_tags` string[] — Custom tags for the message
  - `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. Use **lowercase** for `value` and/or **field.keyword** for `field` when not using `equals` operator.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-"} Use **lowercase** for `value` when not using `equals` operator. 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' | 'wildcard', 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-"} Use **lowercase** for `value` when not using `equals` operator. 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' | 'wildcard', 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'
  - `override_configuration` AgentEvaluationConfigOverride
    - `system_prompt` string — Override the system prompt for the agent during evaluation.
    - `filter_prompt` string — Override the filter prompt for the agent during evaluation.
    - `model` string — Override the model for the agent during evaluation.
    - `max_new_tokens` integer — Override the max new tokens for the agent during evaluation.
    - `top_p` number — Override the top_p for the query. This will override the top_p for the agent during evaluation.
    - `temperature` number — Override the temperature for the query. This will override the temperature for the agent during evaluation.
    - `top_k_retrieved_chunks` integer — Override the top_k for the query. This will override the top_k for the agent during evaluation.
    - `top_k_reranked_chunks` integer — Override the rerank_top_k for the query. This will override the rerank_top_k for the agent during evaluation.
    - `enable_filter` boolean — Override the filter_retrievals for the query. This will override the filter_retrievals for the agent during evaluation.
    - `filter_model` string — Override the filter_model for the query. This will override the filter_model for the agent during evaluation.
    - `enable_rerank` boolean — Override the rerank_retrievals for the agent during evaluation.
    - `reranker` string — Override the reranker for the agent during evaluation.
    - `lexical_alpha` number — Override the lexical_alpha for the agent during evaluation.
    - `semantic_alpha` number — Override the semantic_alpha for the agent during evaluation.
    - `rerank_instructions` string — Override the rerank_instructions for the agent during evaluation.
    - `reranker_score_filter_threshold` number — Override the reranker_score_filter_threshold for the agent during evaluation.

## 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
    - `custom_tags` string[] — Custom tags for the message
  - `retrieval_contents` RetrievalContentV01[], required — Relevant content retrieved to answer the query
    - `custom_metadata` object — Custom metadata for the document, provided by the user at ingestion time.Must be a JSON-serializable dictionary with string keys and simple primitive values (str, int, float, bool). The total size must not exceed 2 KB.The strings with date format must stay in date format or be avodied if not in date format.The 'custom_metadata.url' field is automatically included in returned attributions during query time, if provided.The default maximum metadata fields that can be used is 15, contact support if more is needed.
    - `custom_metadata_config` object — A dictionary mapping metadata field names to the configuration to use for each field. If a metadata field is not present in the dictionary, the default configuration will be used. If the dictionary is not provided, metadata will be added in context for rerank and generation but will not be returned back to the user in retrievals in query API. Limits: - Maximum characters per metadata field (for prompt or rerank): **400** - Maximum number of metadata fields (for prompt or retrieval): **10** Contact support@contextual.ai to request quota increases.
    - `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
    - `datastore_id` string — Unique identifier of the datastore
    - `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
    - `ctxl_metadata` InnerRetrievableCtxlMetadata
      - `document_title` string — Title of the document.
      - `section_title` string — Title of the section.
      - `is_figure` boolean — Whether this chunk represents a figure.
      - `file_name` string — Name of the source file.
      - `chunk_size` integer — Size of the chunk in tokens or characters.
      - `file_format` string — Format of the file (e.g., PDF, DOCX).
      - `page` integer — Page number in the source document.
      - `chunk_id` string — Unique identifier for the chunk.
      - `date_created` string — Date when the document or chunk was created.
      - `section_id` string — The HTML id of the nearest element of the chunk
    - `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-10-28** `c8152db45500` — 1 breaking, 3 info
  - response property `retrieval_contents/items/custom_metadata/additionalProperties/` list-of-types was widened by adding types `array` to media type `application/json` of response `200`
  - added the new optional request property `messages/items/custom_tags`
  - added the optional property `message/custom_tags` to the response with the `200` status
  - added the optional property `retrieval_contents/items/datastore_id` to the response with the `200` status
- **2025-08-26** `db7245c74772` — 6 info
  - added the new optional request property `override_configuration`
  - added the new `wildcard` enum value to the request property `documents_filters/anyOf[subschema #1: BaseMetadataFilter]/operator`
  - added the new `wildcard` enum value to the request property `documents_filters/anyOf[subschema #2: CompositeMetadataFilter]/filters/items/anyOf[subschema #1: BaseMetadataFilter]/operator`
  - added the optional property `retrieval_contents/items/ctxl_metadata` to the response with the `200` status
  - …2 more
- **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
- …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/ca7f807eec8b/schema)