API Reference

Retrievers

Copy Markdown

Open in Claude

Open in ChatGPT

Open in Cursor

---

Copy Markdown

View as Markdown

Query Retrievers

GET/api/v1/beta/retrievers

List the retrievers in a project, newest first.

Query ParametersExpand Collapse

include_total: optional 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.

name: optional string

organization_id: optional string

page_size: optional number

Number of items per page

maximum1000

minimum1

page_token: optional string

Cursor from the previous page’s next_page_token.

project_id: optional string

Cookie ParametersExpand Collapse

session: optional string

ReturnsExpand Collapse

items: array of Retriever { id, name, project_id, 3 more }

The list of items.

id: string

Unique identifier

formatuuid

name: string

A name for the retriever tool. Will default to the pipeline name if not provided.

maxLength3000

minLength1

project_id: string

The ID of the project this retriever resides in.

formatuuid

created_at: optional string

Creation datetime

formatdate-time

pipelines: optional array of RetrieverPipeline { description, name, pipeline_id, preset_retrieval_parameters }

The pipelines this retriever uses.

description: string

A description of the retriever tool.

maxLength15000

name: string

A name for the retriever tool. Will default to the pipeline name if not provided.

maxLength3000

minLength1

pipeline_id: string

The ID of the pipeline this tool uses.

formatuuid

preset_retrieval_parameters: optional PresetRetrievalParams { alpha, class_name, dense_similarity_cutoff, 11 more }

Parameters for retrieval configuration.

alpha: optional number

Alpha value for hybrid retrieval to determine the weights between dense and sparse retrieval. 0 is sparse retrieval and 1 is dense retrieval.

maximum1

minimum0

class_name: optional string

dense_similarity_cutoff: optional number

Minimum similarity score wrt query for retrieval

maximum1

minimum0

dense_similarity_top_k: optional number

Number of nodes for dense retrieval.

maximum100

minimum1

enable_reranking: optional boolean

Enable reranking for retrieval

files_top_k: optional number

Number of files to retrieve (only for retrieval mode files_via_metadata and files_via_content).

maximum5

minimum1

rerank_top_n: optional number

Number of reranked nodes for returning.

maximum100

minimum1

retrieval_mode: optional RetrievalMode

The retrieval mode for the query.

One of the following:

"auto_routed"

"chunks"

"files_via_content"

"files_via_metadata"

Deprecatedretrieve_image_nodes: optional boolean

Whether to retrieve image nodes.

retrieve_page_figure_nodes: optional boolean

Whether to retrieve page figure nodes.

retrieve_page_screenshot_nodes: optional boolean

Whether to retrieve page screenshot nodes.

search_filters: optional MetadataFilters { filters, condition }

Metadata filters for vector stores.

filters: array of object { key, value, operator } or MetadataFilters { filters, condition }

One of the following:

MetadataFilter object { key, value, operator }

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

value: number or string or array of string or 2 more

One of the following:

number

string

StringArray = array of string

NumberArray = array of number

IntegerArray = array of number

operator: optional "!=" or "<" or "<=" or 11 more

Vector store filter operator.

One of the following:

"!="

"<"

"<="

"=="

">"

">="

"all"

"any"

"contains"

"in"

"is_empty"

"nin"

"text_match"

"text_match_insensitive"

MetadataFilters object { filters, condition }

Metadata filters for vector stores.

condition: optional "and" or "not" or "or"

Vector store filter conditions to combine different filters.

One of the following:

"and"

"not"

"or"

search_filters_inference_schema: optional map[map[unknown] or array of unknown or string or 2 more]

JSON Schema that will be used to infer search_filters. Omit or leave as null to skip inference.

One of the following:

map[unknown]

array of unknown

string

number

boolean

sparse_similarity_top_k: optional number

Number of nodes for sparse retrieval.

maximum100

minimum1

updated_at: optional string

Update datetime

formatdate-time

next_page_token: optional string

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: optional number

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.

Query Retrievers

HTTP

HTTP

TypeScript

Python

Go

Java

C#

CLI Tool

curl https://api.cloud.llamaindex.ai/api/v1/beta/retrievers \
    -H "Authorization: Bearer $LLAMA_CLOUD_API_KEY"

200 example

{
  "items": [
    {
      "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
      "name": "x",
      "project_id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
      "created_at": "2019-12-27T18:11:19.117Z",
      "pipelines": [
        {
          "description": "description",
          "name": "x",
          "pipeline_id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
          "preset_retrieval_parameters": {
            "alpha": 0,
            "class_name": "class_name",
            "dense_similarity_cutoff": 0,
            "dense_similarity_top_k": 1,
            "enable_reranking": true,
            "files_top_k": 1,
            "rerank_top_n": 1,
            "retrieval_mode": "auto_routed",
            "retrieve_image_nodes": true,
            "retrieve_page_figure_nodes": true,
            "retrieve_page_screenshot_nodes": true,
            "search_filters": {
              "filters": [
                {
                  "key": "key",
                  "value": 0,
                  "operator": "!="
                }
              ],
              "condition": "and"
            },
            "search_filters_inference_schema": {
              "foo": {
                "foo": "bar"
              }
            },
            "sparse_similarity_top_k": 1
          }
        }
      ],
      "updated_at": "2019-12-27T18:11:19.117Z"
    }
  ],
  "next_page_token": "next_page_token",
  "total_size": 0
}

Returns Examples

200 example

{
  "items": [
    {
      "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
      "name": "x",
      "project_id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
      "created_at": "2019-12-27T18:11:19.117Z",
      "pipelines": [
        {
          "description": "description",
          "name": "x",
          "pipeline_id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
          "preset_retrieval_parameters": {
            "alpha": 0,
            "class_name": "class_name",
            "dense_similarity_cutoff": 0,
            "dense_similarity_top_k": 1,
            "enable_reranking": true,
            "files_top_k": 1,
            "rerank_top_n": 1,
            "retrieval_mode": "auto_routed",
            "retrieve_image_nodes": true,
            "retrieve_page_figure_nodes": true,
            "retrieve_page_screenshot_nodes": true,
            "search_filters": {
              "filters": [
                {
                  "key": "key",
                  "value": 0,
                  "operator": "!="
                }
              ],
              "condition": "and"
            },
            "search_filters_inference_schema": {
              "foo": {
                "foo": "bar"
              }
            },
            "sparse_similarity_top_k": 1
          }
        }
      ],
      "updated_at": "2019-12-27T18:11:19.117Z"
    }
  ],
  "next_page_token": "next_page_token",
  "total_size": 0
}