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

# Direct Retrieve

`POST /api/v1/retrievers/retrieve`

Retrieve data using specified pipelines without creating a persistent retriever.

## Query parameters

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

## Cookies

- `session` string, nullable

## Request body

- DirectRetrievalParams
  - `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.
  - `pipelines` RetrieverPipeline[] — The pipelines to use for retrieval.
    - `name` string, nullable, required — A name for the retriever tool. Will default to the pipeline name if not provided.
    - `description` string, nullable, required — A description of the retriever tool.
    - `pipeline_id` string, uuid, required — The ID of the pipeline this tool uses.
    - `preset_retrieval_parameters` PresetRetrievalParams — Schema for the search params for an retrieval execution that can be preset for a pipeline.
      - `dense_similarity_top_k` integer, nullable — Number of nodes for dense retrieval.
      - `dense_similarity_cutoff` number, nullable — Minimum similarity score wrt query for retrieval
      - `sparse_similarity_top_k` integer, nullable — Number of nodes for sparse retrieval.
      - `enable_reranking` boolean, nullable — Enable reranking for retrieval
      - `rerank_top_n` integer, nullable — Number of reranked nodes for returning.
      - `alpha` number, nullable — Alpha value for hybrid retrieval to determine the weights between dense and sparse retrieval. 0 is sparse retrieval and 1 is dense retrieval.
      - `search_filters` MetadataFilters — Metadata filters for vector stores.
        - `filters` union[], required
          - union
            - MetadataFilter — Comprehensive metadata filter for vector stores to support more operators. Value uses Strict types, as int, float and str are compatible types and were all converted to string before. See: https://docs.pydantic.dev/latest/usage/types/#strict-types
              - …
            - MetadataFilters — recursive
        - `condition` 'and' | 'or' | 'not' — Vector store filter conditions to combine different filters.
      - `search_filters_inference_schema` object, nullable — JSON Schema that will be used to infer search_filters. Omit or leave as null to skip inference.
      - `files_top_k` integer, nullable — Number of files to retrieve (only for retrieval mode files_via_metadata and files_via_content).
      - `retrieval_mode` 'chunks' | 'files_via_metadata' | 'files_via_content' | 'auto_routed'
      - `retrieve_image_nodes` boolean — Whether to retrieve image nodes.
      - `retrieve_page_screenshot_nodes` boolean — Whether to retrieve page screenshot nodes.
      - `retrieve_page_figure_nodes` boolean — Whether to retrieve page figure nodes.
      - `class_name` string

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

---

[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/revisions/b17341164de9/schema)