---
title: "Retrieve"
method: POST
path: "/api/v1/retrieval/retrieve"
tags: ["Retrieval"]
---

# 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 parameters

- `project_id` string, uuid, nullable
- `organization_id` string, uuid, nullable

## Cookies

- `session` string, nullable

## Request body

- RetrieveParams — Hybrid retrieval request combining vector and full-text search.
  - `index_id` string, required — ID of the index to retrieve against.
  - `query` string, required — Natural-language query to retrieve relevant chunks.
  - `top_k` integer, nullable — Maximum number of results to return.
  - `num_candidates` integer, nullable — Number of candidates for approximate nearest neighbor search.
  - `vector_pipeline_weight` number, nullable — Weight of the vector search pipeline (0-1).
  - `full_text_pipeline_weight` number, nullable — Weight of the full-text search pipeline (0-1).
  - `score_threshold` number, nullable — Minimum score threshold for returned results.
  - `static_filters` MongoStaticFilters
    - `parsed_directory_file_id` FilterTypeStr
      - `operator` 'eq' | 'ne' | 'gt' | 'lt' | 'gte' | 'lte' | 'in' | 'nin', required
      - `value` union, required
        - string
        - string[]
  - `custom_filters` object, nullable — Filters on user-defined metadata fields.
  - `rerank` RerankConfig — Reranking configuration to apply after hybrid search.
    - `enabled` boolean — Set to false to disable reranking.
    - `top_n` integer, nullable — Number of results to return after reranking.

## Response `200`

Successful Response

- RetrieveResult — Response containing retrieval results.
  - `results` RetrievalResult[], required — Ordered list of retrieved chunks.
    - `content` string, required — Text content of the retrieved chunk.
    - `score` number, nullable — Hybrid search relevance score.
    - `rerank_score` number, nullable — Relevance score from the reranker, if reranking was applied.
    - `metadata` MetadataDict
    - `static_fields` StaticFields — Built-in fields stored for every exported chunk.
      - `parsed_directory_file_id` string, nullable — ID of the parsed file.
      - `page_range_start` integer, nullable — First page number covered by this chunk.
      - `page_range_end` integer, nullable — Last page number covered by this chunk.
      - `chunk_start_char` integer, nullable — Start character offset of the chunk.
      - `chunk_end_char` integer, nullable — End character offset of the chunk.
      - `chunk_index` integer, nullable — Index of the chunk within the file.
      - `chunk_token_count` integer, nullable — Token count of the chunk.
      - `attachments` AttachmentRef[] — Attachments associated with the chunk
        - `type` string, required — Attachment kind, e.g. 'screenshot', 'items'.
        - `attachment_name` string, required — Attachment-relative path, e.g. 'screenshots/page_7.jpg'.
        - `source_id` string, required — File ID to pass as source_id when fetching the attachment.

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.net/run-llama/apis/llama-platform.md) · [All operations](https://skmtc.net/run-llama/apis/llama-platform/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/run-llama/llama-platform/versions/b17341164de9/schema)