Skip to content
Developer Documentation
API Reference
Beta
Retrieval

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, float, bool, 2 more]]]

User-defined metadata associated with the chunk.

One of the following:
str
float
bool
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

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