---
title: "List Retrievers"
method: POST
path: "/v1/retrievers/list"
tags: ["Retrievers"]
---

# List Retrievers

`POST /v1/retrievers/list`

List all retrievers in the namespace.

## Query parameters

- `limit` integer, nullable
- `page_size` integer, nullable
- `offset` integer, nullable
- `page` integer, nullable
- `cursor` string, nullable
- `next_cursor` string, nullable
- `after` string, nullable
- `include_total` boolean

## Request body

- ListRetrieversRequest — Request to list retrievers.
  - `search` string, nullable — Search term for wildcard search across retriever_id, retriever_name, description, and other text fields
  - `filters` object, nullable — Filters applied directly to the query — any stored field works, e.g. {"collection_ids": {"$in": ["col_x"]}} to filter by collection, or {"retriever_name": "..."}.
  - `sorts` object[], nullable — Sort options for the retriever list
  - `sort` SortOption — Specifies how to sort query results. Attributes: field: Field to sort by direction: Sort direction (ascending or descending)
    - `field` string, required — Field to sort by, supports dot notation for nested fields
    - `direction` 'asc' | 'desc' — Sort direction options.
  - `case_sensitive` boolean — If True, filters and search will be case-sensitive

## Response `200`

Successful Response

- ListRetrieversResponse — Response from listing retrievers.
  - `results` RetrieverModelOutput[] — List of retrievers in the namespace.
    - `retriever_id` string — Stable retriever identifier (REQUIRED).
    - `retriever_name` string, required — Unique retriever name within namespace (REQUIRED).
    - `description` string, nullable — Detailed description of retriever behaviour (OPTIONAL).
    - `collection_ids` string[] — Collections queried by the retriever. Can be empty for query-only inference mode.
    - `stages` StageConfigOutput[], required — Ordered list of stage configurations (REQUIRED).
      - `stage_name` string, required — Human-readable stage instance name (REQUIRED).
      - `stage_type` 'filter' | 'sort' | 'reduce' | 'apply' | 'enrich' — Categorisation of stage behaviour within a retrieval flow. These functional categories describe how stages transform the document stream: - FILTER: N → ≤N documents (subset, same schema) - SORT: N → N documents (same docs, different order, same schema) - REDUCE: N → 1 document (aggregation, new schema) - APPLY: N → N or N*M documents (enrichment/expansion, expanded/new schema) - ENRICH: N → N documents (enrichment with computed fields)
      - `config` object, required — Stage implementation parameters (REQUIRED). Must include `stage_id` key referencing a registered retriever stage. Supports template expressions using Jinja2 syntax resolved at execution time. Template namespaces support both uppercase and lowercase formats: {{INPUT.field}} or {{inputs.field}}, {{DOC.field}} or {{doc.field}}, {{CONTEXT.field}} or {{context.field}}, {{STAGE.field}} or {{stage.field}}. All formats work identically. Provide stage-specific configuration under `parameters`. Optional `pre_filters` and `post_filters` are placed as SIBLINGS of `parameters` (NOT nested inside). Pre-filters require payload indexes on the filtered fields.
      - `batch_size` string, nullable — Optional templated batch size expression evaluated per execution. Supports template variables: {{INPUT.page_size}}, {{inputs.page_size}}, {{CONTEXT.budget_remaining}}, etc. Both uppercase and lowercase namespace names are supported (e.g., INPUT/inputs, DOC/doc, CONTEXT/context, STAGE/stage). Defaults to stage-specific value when omitted.
      - `description` string, nullable — User-facing description of the stage (OPTIONAL).
      - `on_error` string, nullable — Behavior when this stage fails. 'skip' continues execution with results from previous stages (graceful degradation). 'error' (default) fails the entire retriever. Useful for optional enrichment or multi-modal stages where one modality may not apply (e.g., face search on logo-only images).
      - `output_alias` string, nullable — Optional alias to persist this stage's results in the execution context. When set, results are stored in CONTEXT.<alias> in addition to replacing current_results. Downstream stages can reference them via {{CONTEXT.<alias>}} in templates. Useful for multi-stage pipelines where later stages should not overwrite earlier results (e.g., face search + logo search producing independent result sets).
      - `parameters` object, required — Mirror of config.parameters at the stage top level, so anything round-tripping a stage (clone-by-GET, UI re-save, an agent verifying its own write) reads a populated stage instead of an empty one. Always equal to config['parameters'] (FRUSTRATIONS 2026-07-22: a retriever cloned from GET output was created with NO searches because the real stage config only lived under config.parameters). Read-only — on input this key is ignored and recomputed from config, so the two can't drift; config stays the source of truth.
    - `input_schema` object — JSON Schema describing expected user inputs (REQUIRED). Properties must use RetrieverInputSchemaField which supports all bucket types plus document_reference.
    - `budget_limits` BudgetLimits — User-defined limits for time and credits during execution.
      - `max_credits` number, nullable — Maximum credits allowed for a single execution (OPTIONAL).
      - `max_time_ms` integer, nullable — Maximum wall-clock time in milliseconds before forcing halt (OPTIONAL).
    - `feature_dependencies` FeatureAddress[], nullable — Feature addresses required by stages (OPTIONAL, aids validation).
      - `scheme` string
      - `extractor` string, required
      - `version` string, required
      - `output` string, nullable
    - `tags` string[] — Arbitrary tags to help organise retrievers (OPTIONAL).
    - `metadata` object — Custom key-value metadata (OPTIONAL). Round-trips on create/get/list and is updatable via PATCH — useful for automation markers like seed/config versions.
    - `display_config` object, nullable — Display configuration for public retriever UI rendering (OPTIONAL). Defines how the search interface should appear when the retriever is published, including input fields, theme, layout, exposed result fields, and field formatting. This configuration is used as the default when publishing the retriever.
    - `version` integer — Version number that increments on each update (REQUIRED).
    - `created_at` string, date-time — Creation timestamp in UTC (REQUIRED).
    - `updated_at` string, date-time — Last update timestamp in UTC (REQUIRED).
    - `created_by` string, nullable — Identifier of the user who created the retriever (OPTIONAL).
    - `updated_by` string, nullable — Identifier of the user who last updated the retriever (OPTIONAL).
    - `is_published` boolean — Whether this retriever is currently published (either as public retriever or in marketplace)
    - `marketplace_listing_id` string, nullable — Marketplace listing ID if this retriever is published to the marketplace, None otherwise
    - `fusion` string, nullable, required — Fusion strategy used by this retriever's feature_search stage (e.g. 'learned', 'rrf', 'dbsf'). Null if no feature_search stage.
    - `collection_identifiers` string[], required — Mirror of collection_ids under the field name CREATE accepts (collection_identifiers), so a create → read round-trip reads back the field it wrote. Always equal to collection_ids (FRUSTRATIONS 2026-07-16: SDKs/agents re-reading their own write saw collection_identifiers null and concluded the retriever was unscoped).
  - `total` integer — Total number of retrievers.
  - `pagination` PaginationResponse — PaginationResponse. Cursor-based pagination response: - Use next_cursor for navigation - Total count fields only populated when include_total=true
    - `total` integer, nullable
    - `page` integer, nullable
    - `page_size` integer, nullable
    - `total_pages` integer, nullable
    - `next_page` string, nullable
    - `previous_page` string, nullable
    - `next_cursor` string, nullable

## Other responses

- `400` — Bad Request
- `401` — Unauthorized
- `403` — Forbidden
- `404` — Not Found
- `422` — Validation Error
- `500` — Internal Server Error

---

[API](https://skmtc.net/mixpeek/apis/mixpeek-api.md) · [All operations](https://skmtc.net/mixpeek/apis/mixpeek-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/mixpeek/mixpeek-api/revisions/220a3b263fda/schema)