---
title: "Query Retrievers"
method: GET
path: "/api/v1/beta/retrievers"
tags: ["Beta", "Retrievers"]
---

# Query Retrievers

`GET /api/v1/beta/retrievers`

## 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/beta/retrievers`
- Auth: HTTP bearer

List the retrievers in a project, newest first.

## Query parameters

- `name` string, nullable
- `page_size` integer: Number of items per page
- `page_token` string, nullable: Cursor from the previous page's `next_page_token`.
- `include_total` boolean: Return `total_size`, a count of every row matching the filter. It is a second query on every page, so it is off unless asked for.
- `project_id` string, uuid, nullable
- `organization_id` string, uuid, nullable

## Cookies

- `session` string, nullable

## Response `200`

Successful Response

- RetrieverQueryResponse: A page of retrievers.
  - `items` Retriever[], required: The list of items.
    - `name` string, required: A name for the retriever tool. Will default to the pipeline name if not provided.
    - `pipelines` RetrieverPipeline[]: The pipelines this retriever uses.
      - `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
              - …
          - `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
    - `id` string, uuid, required: Unique identifier
    - `created_at` string, date-time, nullable: Creation datetime
    - `updated_at` string, date-time, nullable: Update datetime
    - `project_id` string, uuid, required: The ID of the project this retriever resides in.
  - `next_page_token` string, nullable: A token, which can be sent as page_token to retrieve the next page. If this field is omitted, there are no subsequent pages.
  - `total_size` integer, nullable: The total number of items available. This is only populated when specifically requested. The value may be an estimate and can be used for display purposes only.

## Other responses

- `422`: Validation Error

## Changes

- **2026-10-16** `a38b684f8e1b`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/run-llama/apis/llama-platform/changes/api/v1/beta/retrievers/get.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)