API Reference

Beta

Copy Markdown

Open in Claude

Open in ChatGPT

Open in Cursor

---

Copy Markdown

View as Markdown

Retrieval

Retrieve

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

POST/api/v1/retrieval/retrieve

Find Files

beta.retrieval.find(RetrievalFindParams**kwargs) -> SyncPaginatedCursorPost[RetrievalFindResponse]

POST/api/v1/retrieval/files/find

Grep File

beta.retrieval.grep(RetrievalGrepParams**kwargs) -> SyncPaginatedCursorPost[RetrievalGrepResponse]

POST/api/v1/retrieval/files/grep

Read File

beta.retrieval.read(RetrievalReadParams**kwargs) -> RetrievalReadResponse

POST/api/v1/retrieval/files/read

ModelsExpand 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.

class RetrievalFindResponse: …

A file returned by find.

file_id: str

ID of the file.

file_name: str

Display name of the file.

class RetrievalGrepResponse: …

A single grep match within a file.

content: str

Matched text content.

end_char: int

End character offset of the match.

start_char: int

Start character offset of the match.

class RetrievalReadResponse: …

File read result.

content: str

Parsed text content of the file.