---
title: "Run Search"
method: POST
path: "/api/v1/pipelines/{pipeline_id}/retrieve"
tags: ["Pipelines"]
---

# Run Search

`POST /api/v1/pipelines/{pipeline_id}/retrieve`

Run a retrieval query against a managed pipeline.

Searches the pipeline's vector store using the provided query
and retrieval parameters. Supports dense, sparse, and hybrid
search modes with configurable top-k and reranking.

## Path parameters

- `pipeline_id` string, uuid, required

## Query parameters

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

## Cookies

- `session` string, nullable

## Request body

- RetrievalParams — Schema for the search params for an retrieval execution.
  - `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
          - `key` string, required
          - `value` union, required
            - integer
            - number
            - string
            - string[]
            - number[]
            - integer[]
          - `operator` '==' | '>' | '<' | '!=' | '>=' | '<=' | 'in' | 'nin' | 'any' | 'all' | 'text_match' | 'text_match_insensitive' | 'contains' | 'is_empty' — Vector store filter operator.
        - 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.
  - `query` string, required — The query to retrieve against.
  - `class_name` string

## Response `200`

Successful Response

- RetrieveResults — Schema for the result of an retrieval execution.
  - `pipeline_id` string, uuid, required — The ID of the pipeline that the query was retrieved against.
  - `retrieval_nodes` TextNodeWithScore[], required — The nodes retrieved by the pipeline for the given query.
    - `node` TextNode, required — Provided for backward compatibility.
      - `id_` string — Unique ID of the node.
      - `embedding` number[], nullable — Embedding of the node.
      - `extra_info` object — A flat dictionary of metadata fields
      - `excluded_embed_metadata_keys` string[] — Metadata keys that are excluded from text for the embed model.
      - `excluded_llm_metadata_keys` string[] — Metadata keys that are excluded from text for the LLM.
      - `relationships` object — A mapping of relationships to other node information.
      - `metadata_template` string — Template for how metadata is formatted, with {key} and {value} placeholders.
      - `metadata_seperator` string — Separator between metadata fields when converting to string.
      - `text` string — Text content of the node.
      - `mimetype` string — MIME type of the node content.
      - `start_char_idx` integer, nullable — Start char index of the node.
      - `end_char_idx` integer, nullable — End char index of the node.
      - `text_template` string — Template for how text is formatted, with {content} and {metadata_str} placeholders.
      - `class_name` string
    - `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
  - `retrieval_latency` object — The end-to-end latency for retrieval and reranking.
  - `metadata` object — Metadata associated with the retrieval execution
  - `inferred_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
          - `key` string, required
          - `value` union, required
            - integer
            - number
            - string
            - string[]
            - number[]
            - integer[]
          - `operator` '==' | '>' | '<' | '!=' | '>=' | '<=' | 'in' | 'nin' | 'any' | 'all' | 'text_match' | 'text_match_insensitive' | 'contains' | 'is_empty' — Vector store filter operator.
        - MetadataFilters — recursive
    - `condition` 'and' | 'or' | 'not' — Vector store filter conditions to combine different filters.
  - `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)