---
title: "Query Agent Knowledge Base Rag"
method: POST
path: "/v1/convai/agents/{agent_id}/knowledge-base/rag-query"
tags: ["Agents Platform"]
---

# Query Agent Knowledge Base Rag

`POST /v1/convai/agents/{agent_id}/knowledge-base/rag-query`

Run the agent's exact RAG retrieval for an ad-hoc query and return the ranked chunks the agent would retrieve. Read-only: no conversation is created. The response reflects current retrieval internals and may evolve.

## Path parameters

- `agent_id` string, required — The id of an agent. This is returned on agent creation.

## Query parameters

- `branch_id` string, nullable — The ID of the branch to use

## Headers

- `xi-api-key` string, nullable — Your API key. This is required by most endpoints to access our API programmatically. You can view your xi-api-key using the 'Profile' tab on the website.

## Request body

- AgentKnowledgeBaseRagQueryRequestModel
  - `query` string, required — Query to run against the agent's knowledge base RAG index.
  - `use_agent_defaults` boolean — When true (the default), retrieval uses the agent's own RAG settings, reproducing exactly what the agent would retrieve. Set to false to retrieve with neutral default RAG settings instead (the agent's embedding model is always kept, since it determines which vector index exists). Useful for auditing the knowledge base independently of how a particular agent is tuned.

## Response `200`

Successful Response

- AgentKnowledgeBaseRagQueryResponseModel
  - `retrieval_query` string, required — Raw query used for retrieval (echoes the request query).
  - `chunks` AgentKnowledgeBaseRagChunkResponseModel[], required — Ranked chunks the agent would retrieve, after distance and length filtering.
    - `document_id` string, required — ID of the source knowledge base document.
    - `document_name` string, required — Name of the source knowledge base document.
    - `chunk_id` string, required — ID of the retrieved chunk.
    - `text` string, required — Text content of the retrieved chunk.
    - `vector_distance` number, nullable, required — Similarity distance when exposed by the retrieval strategy.

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.net/elevenlabs/apis/elevenlabs-api-documentation.md) · [All operations](https://skmtc.net/elevenlabs/apis/elevenlabs-api-documentation/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/elevenlabs/elevenlabs-api-documentation/versions/57d56f34628a/schema)