---
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' | '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-"} 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
  - `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 chunks but will not be retrievable. 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
    - `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-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
- **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
- …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/db7245c74772/schema)