Skip to main content
POST
/
v1
/
retrievers
/
{retriever_identifier}
/
execute
Execute Retriever
curl --request POST \
  --url https://api.mixpeek.com/v1/retrievers/{retriever_identifier}/execute \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "retriever_id": "<string>",
  "inputs": {},
  "collection_ids": [
    "<string>"
  ],
  "collection_names": [
    "<string>"
  ],
  "filters": {
    "AND": [
      {
        "field": "name",
        "operator": "eq",
        "value": "John"
      },
      {
        "field": "age",
        "operator": "gte",
        "value": 30
      }
    ],
    "OR": [
      {
        "field": "status",
        "operator": "eq",
        "value": "active"
      },
      {
        "field": "role",
        "operator": "eq",
        "value": "admin"
      }
    ],
    "NOT": [
      {
        "field": "department",
        "operator": "eq",
        "value": "HR"
      },
      {
        "field": "location",
        "operator": "eq",
        "value": "remote"
      }
    ],
    "case_sensitive": true
  },
  "sorts": [
    {
      "field": "created_at",
      "direction": "desc"
    }
  ],
  "limit": 10,
  "offset": 0,
  "select": [
    "<string>"
  ],
  "session_id": "<string>",
  "return_urls": false,
  "group_by": {
    "field": "<string>",
    "max_features": 10,
    "sort": {
      "field": "created_at",
      "direction": "desc"
    }
  }
}'
{
  "execution_id": "<string>",
  "execution_time": 0,
  "stage_results": [
    {
      "stage_name": "<string>",
      "version": "<string>",
      "execution_time": 123,
      "results": [
        {
          "document_id": "<string>",
          "collection_id": "<string>",
          "object_id": "<string>",
          "enrichments": {
            "clusters": [
              "<any>"
            ],
            "taxonomies": [
              "<any>"
            ]
          },
          "internal_metadata": {},
          "metadata": {},
          "source_blobs": [
            {}
          ],
          "document_blobs": [
            {}
          ],
          "presigned_urls": [
            {}
          ],
          "score": 123
        }
      ],
      "metadata": {}
    }
  ],
  "final_results": [
    {
      "document_id": "<string>",
      "collection_id": "<string>",
      "object_id": "<string>",
      "enrichments": {
        "clusters": [
          "<any>"
        ],
        "taxonomies": [
          "<any>"
        ]
      },
      "internal_metadata": {},
      "metadata": {},
      "source_blobs": [
        {}
      ],
      "document_blobs": [
        {}
      ],
      "presigned_urls": [
        {}
      ],
      "score": 123
    }
  ]
}

Authorizations

​
Authorization
string
header
required

Bearer token authentication using your API key. Format: 'Bearer your_api_key'. To get an API key, create an account at mixpeek.com/start and generate a key in your account settings.

Headers

​
if-none-match
string | null

ETag for cache validation

​
Authorization
string | null

Bearer token authentication using your API key. Format: 'Bearer your_api_key'. To get an API key, create an account at mixpeek.com/start and generate a key in your account settings. Example: 'Bearer sk_1234567890abcdef'

​
X-Namespace
string | null

Optional namespace for data isolation. This can be a namespace name or namespace ID. Example: 'netflix_prod' or 'ns_1234567890'. To create a namespace, use the /namespaces endpoint.

Path Parameters

​
retriever_identifier
string
required

The ID or name of the retriever.

Body

application/json

The retriever query request.

​
retriever_id
string | null

Identifier of the retriever to execute. If omitted, the execution context must provide it.

​
inputs
object | null

Input values for the retriever query. If omitted, mock embeddings will be generated based on the feature's dimensions for testing purposes.

​
collection_ids
string[] | null

Optional list of collection IDs to search. If provided, overrides the retriever's default collections. Useful for dynamically filtering which collections to search at query time.

​
collection_names
string[] | null

Optional list of collection names to search. If provided, collection names will be resolved to IDs and merged with collection_ids. Allows referencing collections by human-readable names.

​
filters
object | null

Logical operations for filtering results. Can include AND, OR, NOT conditions with field comparisons. Represents a logical operation (AND, OR, NOT) on filter conditions.

Allows nesting with a defined depth limit.

Also supports shorthand syntax where field names can be passed directly as key-value pairs for equality filtering (e.g., {"metadata.title": "value"}).

​
sorts
SortOption · object[] | null

Controls the ordering of results. Can sort by score (default) or any other document field. This sorts the results from the last stage.

​
limit
integer
default:10

Maximum number of results to return. Overrides the default pagination limit in the retriever definition.

Required range: 1 <= x <= 100
​
offset
integer
default:0

Number of results to skip. Use with limit for pagination. For large offsets, consider using session_id for cursor-based pagination.

Required range: x >= 0
​
select
string[] | null

Specific fields to include in the response. If not specified, returns all fields.

​
session_id
string | null

Session identifier for interaction tracking.

​
return_urls
boolean
default:false

When true, generates pre-signed URLs for any media assets in the results. May increase response time slightly.

​
group_by
object | null

Options for grouping results by a specific field. Options for grouping results by a specific field.

Attributes: field: The field to group by. max_features: The maximum number of features (documents) to return per group. sort: Optional sorting options to apply within each group.

Response

Successful Response

Response from a retriever execution.

​
execution_id
string

Unique identifier for the retriever execution

​
execution_time
number
default:0

Total execution time of the retriever pipeline.

​
stage_results
StageResponse · object[]

Results from each stage of the retriever pipeline.

​
final_results
Final Results · array

Final sorted and paginated results of the retriever execution.

  • DocumentResult
  • GroupedResultItem
⌘I