API Reference

Beta

Retrieval

Copy Markdown

Open in Claude

Open in ChatGPT

Open in Cursor

---

Copy Markdown

View as Markdown

Retrieve

POST/api/v1/retrieval/retrieve

Retrieve relevant chunks via hybrid search (vector + full-text), with filtering on built-in or user-defined metadata.

Query ParametersExpand Collapse

organization_id: optional string

project_id: optional string

Cookie ParametersExpand Collapse

session: optional string

Body ParametersJSONExpand Collapse

index_id: string

ID of the index to retrieve against.

query: string

Natural-language query to retrieve relevant chunks.

custom_filters: optional map[object { operator, value } or array of object { operator, value } ]

Filters on user-defined metadata fields.

One of the following:

FilterTypeUnionStrIntBoolFloat = object { operator, value }

operator: "eq" or "ne" or "gt" or 5 more

One of the following:

"eq"

"ne"

"gt"

"lt"

"gte"

"lte"

"in"

"nin"

value: string or boolean or number or array of string or boolean or number

One of the following:

string

boolean

number

array of string or boolean or number

One of the following:

string

boolean

number

array of object { operator, value }

operator: "eq" or "ne" or "gt" or 5 more

One of the following:

"eq"

"ne"

"gt"

"lt"

"gte"

"lte"

"in"

"nin"

value: number or array of number

One of the following:

number

array of number

full_text_pipeline_weight: optional number

Weight of the full-text search pipeline (0-1).

num_candidates: optional number

Number of candidates for approximate nearest neighbor search.

rerank: optional object { enabled, top_n }

Reranking configuration applied after hybrid search. Enabled by default.

enabled: optional boolean

Set to false to disable reranking.

top_n: optional number

Number of results to return after reranking.

score_threshold: optional number

Minimum score threshold for returned results.

static_filters: optional object { parsed_directory_file_id }

Filters on built-in document fields (page range, chunk index, etc.).

parsed_directory_file_id: optional object { operator, value }

operator: "eq" or "ne" or "gt" or 5 more

One of the following:

"eq"

"ne"

"gt"

"lt"

"gte"

"lte"

"in"

"nin"

value: string or array of string

One of the following:

string

array of string

top_k: optional number

Maximum number of results to return.

vector_pipeline_weight: optional number

Weight of the vector search pipeline (0-1).

ReturnsExpand Collapse

results: array of object { content, metadata, rerank_score, 2 more }

Ordered list of retrieved chunks.

content: string

Text content of the retrieved chunk.

metadata: optional map[string or number or number or 3 more]

User-defined metadata associated with the chunk.

One of the following:

string

number

number

boolean

unknown

MetadataListValue = array of string

rerank_score: optional number

Relevance score from the reranker, if reranking was applied.

score: optional number

Hybrid search relevance score.

static_fields: optional object { attachments, chunk_end_char, chunk_index, 5 more }

Built-in fields stored for every exported chunk.

attachments: optional array of object { attachment_name, source_id, type }

Attachments associated with the chunk

attachment_name: string

Attachment-relative path, e.g. ‘screenshots/page_7.jpg’.

source_id: string

File ID to pass as source_id when fetching the attachment.

type: string

Attachment kind, e.g. ‘screenshot’, ‘items’.

chunk_end_char: optional number

End character offset of the chunk.

chunk_index: optional number

Index of the chunk within the file.

chunk_start_char: optional number

Start character offset of the chunk.

chunk_token_count: optional number

Token count of the chunk.

page_range_end: optional number

Last page number covered by this chunk.

page_range_start: optional number

First page number covered by this chunk.

parsed_directory_file_id: optional string

ID of the parsed file.

Retrieve

HTTP

HTTP

TypeScript

Python

Java

Go

CLI Tool

curl https://api.cloud.llamaindex.ai/api/v1/retrieval/retrieve \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer $LLAMA_CLOUD_API_KEY" \
    -d '{
          "index_id": "idx-abc123",
          "query": "What are the key findings?"
        }'

200 example

{
  "results": [
    {
      "content": "content",
      "metadata": {
        "foo": "string"
      },
      "rerank_score": 0,
      "score": 0,
      "static_fields": {
        "attachments": [
          {
            "attachment_name": "attachment_name",
            "source_id": "source_id",
            "type": "type"
          }
        ],
        "chunk_end_char": 0,
        "chunk_index": 0,
        "chunk_start_char": 0,
        "chunk_token_count": 0,
        "page_range_end": 0,
        "page_range_start": 0,
        "parsed_directory_file_id": "parsed_directory_file_id"
      }
    }
  ]
}

Returns Examples

200 example

{
  "results": [
    {
      "content": "content",
      "metadata": {
        "foo": "string"
      },
      "rerank_score": 0,
      "score": 0,
      "static_fields": {
        "attachments": [
          {
            "attachment_name": "attachment_name",
            "source_id": "source_id",
            "type": "type"
          }
        ],
        "chunk_end_char": 0,
        "chunk_index": 0,
        "chunk_start_char": 0,
        "chunk_token_count": 0,
        "page_range_end": 0,
        "page_range_start": 0,
        "parsed_directory_file_id": "parsed_directory_file_id"
      }
    }
  ]
}