---
title: "Retrieve"
method: POST
path: "/api/v1/retrievers/{retriever_id}/retrieve"
tags: ["Retrievers"]
---

# Retrieve

`POST /api/v1/retrievers/{retriever_id}/retrieve`

## Request

- Base URL: `https://api.cloud.llamaindex.ai` (the document declares no server; this is the origin it was published from)
- URL: `https://api.cloud.llamaindex.ai/api/v1/retrievers/{retriever_id}/retrieve`
- Auth: HTTP bearer

Retrieve data using a Retriever.

## Path parameters

- `retriever_id` string, uuid, required

## Query parameters

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

## Cookies

- `session` string, nullable

## Request body

- CompositeRetrievalParams
  - `mode` 'routing' | 'full': Enum for the mode of composite retrieval.
  - `rerank_top_n` integer, nullable: (use rerank_config.top_n instead) The number of nodes to retrieve after reranking over retrieved nodes from all retrieval tools.
  - `rerank_config` ReRankConfig
    - `top_n` integer: The number of nodes to retrieve after reranking over retrieved nodes from all retrieval tools.
    - `type` 'system_default' | 'llm' | 'cohere' | 'bedrock' | 'score' | 'disabled': Enum for the reranker type.
  - `query` string, required: The query to retrieve against.

## Response `200`

Successful Response

- CompositeRetrievalResult
  - `nodes` CompositeRetrievedTextNodeWithScore[]: The retrieved nodes from the composite retrieval.
    - `node` CompositeRetrievedTextNode, required
      - `id` string, uuid, required: The ID of the retrieved node.
      - `retriever_id` string, uuid, required: The ID of the retriever this node was retrieved from.
      - `retriever_pipeline_name` string, required: The name of the retrieval pipeline this node was retrieved from.
      - `pipeline_id` string, uuid, required: The ID of the pipeline this node was retrieved from.
      - `metadata` object: Metadata associated with the retrieved node.
      - `text` string, required: The text of the retrieved node.
      - `start_char_idx` integer, nullable, required: The start character index of the retrieved node in the document
      - `end_char_idx` integer, nullable, required: The end character index of the retrieved node in the document
    - `score` number, nullable
    - `class_name` string
  - `image_nodes` PageScreenshotNodeWithScore[]: The image nodes retrieved by the pipeline for the given query. Deprecated - will soon be replaced with 'page_screenshot_nodes'.
    - `node` PageScreenshotMetadata, required
      - `page_index` integer, required: The index of the page for which the screenshot is taken (0-indexed)
      - `file_id` string, uuid, required: The ID of the file that the page screenshot was taken from
      - `image_size` integer, required: The size of the image in bytes
      - `metadata` object, nullable: Metadata for the screenshot
    - `score` number, required: The score of the screenshot node
    - `class_name` string
  - `page_figure_nodes` PageFigureNodeWithScore[]: The page figure nodes retrieved by the pipeline for the given query.
    - `node` PageFigureMetadata, required
      - `figure_name` string, required: The name of the figure
      - `file_id` string, uuid, required: The ID of the file that the figure was taken from
      - `page_index` integer, required: The index of the page for which the figure is taken (0-indexed)
      - `figure_size` integer, required: The size of the figure in bytes
      - `is_likely_noise` boolean: Whether the figure is likely to be noise
      - `confidence` number, required: The confidence of the figure
      - `metadata` object, nullable: Metadata for the figure
    - `score` number, required: The score of the figure node
    - `class_name` string

## Other responses

- `422`: Validation Error

## Changes

- **2026-10-16** `a38b684f8e1b`: 2 info
  - added the optional property `detail/items/ctx` to the response with the `422` status
  - added the optional property `detail/items/input` to the response with the `422` status
- **2026-06-09** `614771991b52`: 2 warning
  - removed the optional property `detail/items/ctx` from the response with the `422` status
  - removed the optional property `detail/items/input` from the response with the `422` status
- **2026-06-09** `b17341164de9`: 2 info
  - added the optional property `detail/items/ctx` to the response with the `422` status
  - added the optional property `detail/items/input` to the response with the `422` status

[Operation history](https://skmtc.dev/run-llama/apis/llama-platform/changes/api/v1/retrievers/:retriever_id/retrieve/post.md)

---

[API](https://skmtc.dev/run-llama/apis/llama-platform.md) · [All operations](https://skmtc.dev/run-llama/apis/llama-platform/llms.txt) · [OpenAPI document](https://skmtc.dev/run-llama/apis/llama-platform/revisions/809d302cdb1e?raw)