API Reference

Beta

Retrieval

Copy Markdown

Open in Claude

Open in ChatGPT

Open in Cursor

---

Copy Markdown

View as Markdown

Retrieve

beta.retrieval.retrieve(RetrievalRetrieveParams**kwargs) -> RetrievalRetrieveResponse

POST/api/v1/retrieval/retrieve

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

ParametersExpand Collapse

index_id: str

ID of the index to retrieve against.

query: str

Natural-language query to retrieve relevant chunks.

organization_id: Optional[str]

project_id: Optional[str]

custom_filters: Optional[Dict[str, Optional[CustomFilters]]]

Filters on user-defined metadata fields.

One of the following:

class CustomFiltersFilterTypeUnionStrIntBoolFloat: …

operator: Literal["eq", "ne", "gt", 5 more]

One of the following:

"eq"

"ne"

"gt"

"lt"

"gte"

"lte"

"in"

"nin"

value: Union[str, bool, float, SequenceNotStr[Union[str, bool, float]]]

One of the following:

str

bool

float

SequenceNotStr[Union[str, bool, float]]

One of the following:

str

bool

float

Iterable[CustomFiltersUnionMember1]

operator: Literal["eq", "ne", "gt", 5 more]

One of the following:

"eq"

"ne"

"gt"

"lt"

"gte"

"lte"

"in"

"nin"

value: Union[float, Iterable[float]]

One of the following:

float

Iterable[float]

full_text_pipeline_weight: Optional[float]

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

num_candidates: Optional[int]

Number of candidates for approximate nearest neighbor search.

rerank: Optional[Rerank]

Reranking configuration applied after hybrid search. Enabled by default.

enabled: Optional[bool]

Set to false to disable reranking.

top_n: Optional[int]

Number of results to return after reranking.

score_threshold: Optional[float]

Minimum score threshold for returned results.

static_filters: Optional[StaticFilters]

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

parsed_directory_file_id: Optional[StaticFiltersParsedDirectoryFileID]

operator: Literal["eq", "ne", "gt", 5 more]

One of the following:

"eq"

"ne"

"gt"

"lt"

"gte"

"lte"

"in"

"nin"

value: Union[str, SequenceNotStr[str]]

One of the following:

str

SequenceNotStr[str]

top_k: Optional[int]

Maximum number of results to return.

vector_pipeline_weight: Optional[float]

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

ReturnsExpand Collapse

class RetrievalRetrieveResponse: …

Response containing retrieval results.

results: List[Result]

Ordered list of retrieved chunks.

content: str

Text content of the retrieved chunk.

metadata: Optional[Dict[str, Union[str, int, float, 3 more]]]

User-defined metadata associated with the chunk.

One of the following:

str

int

float

bool

None

List[str]

rerank_score: Optional[float]

Relevance score from the reranker, if reranking was applied.

score: Optional[float]

Hybrid search relevance score.

static_fields: Optional[ResultStaticFields]

Built-in fields stored for every exported chunk.

attachments: Optional[List[ResultStaticFieldsAttachment]]

Attachments associated with the chunk

attachment_name: str

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

source_id: str

File ID to pass as source_id when fetching the attachment.

type: str

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

chunk_end_char: Optional[int]

End character offset of the chunk.

chunk_index: Optional[int]

Index of the chunk within the file.

chunk_start_char: Optional[int]

Start character offset of the chunk.

chunk_token_count: Optional[int]

Token count of the chunk.

page_range_end: Optional[int]

Last page number covered by this chunk.

page_range_start: Optional[int]

First page number covered by this chunk.

parsed_directory_file_id: Optional[str]

ID of the parsed file.

Retrieve

Python

HTTP

TypeScript

Python

Java

Go

CLI Tool

import os
from llama_cloud import LlamaCloud

client = LlamaCloud(
    api_key=os.environ.get("LLAMA_CLOUD_API_KEY"),  # This is the default and can be omitted
)
retrieval = client.beta.retrieval.retrieve(
    index_id="idx-abc123",
    query="What are the key findings?",
)
print(retrieval.results)

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"
      }
    }
  ]
}