Run multiple list-documents queries concurrently.

Execute up to 10 POST /v1/documents/list queries in parallel against the same namespace and return their responses together.

Collapses dossier / multi-collection N+1 fan-outs into one round-trip. Each sub-query is independent; a failure in one does not fail the batch — the failing entry’s response is null and error carries a short message.

POST /v1/documents/list/batch

Run multiple list-documents queries concurrently.

cURL

curl --request POST \
  --url https://api.mixpeek.com/v1/documents/list/batch \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-Namespace: <api-key>' \
  --data '
{
  "queries": [
    {
      "key": "<string>",
      "request": {
        "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
        },
        "sort": {
          "field": "created_at",
          "direction": "desc"
        },
        "search": "<string>",
        "cursor": "<string>",
        "include_total": true,
        "return_presigned_urls": false,
        "return_vectors": false,
        "return_vector_names": false,
        "group_by": "source_object_id",
        "select": [
          "metadata.title",
          "content"
        ],
        "expand": [
          "customer_id"
        ],
        "limit": 10,
        "offset": 0,
        "collection_ids": [
          "<string>"
        ]
      }
    }
  ]
}
'

200

{
  "results": [
    {
      "key": "<string>",
      "response": {
        "pagination": {
          "has_more": false,
          "limit": 10,
          "offset": 0,
          "total_count": 1
        },
        "results": [
          {
            "collection_id": "col_articles",
            "document_id": "doc_123",
            "metadata": {
              "title": "AI Article"
            }
          }
        ],
        "stats": {
          "avg_blobs_per_document": 1,
          "total_documents": 1
        }
      },
      "error": "<string>"
    }
  ]
}

Authorizations

Authorization · string · header · required

Mixpeek API key, sent as Authorization: Bearer mxp_sk_.... Create one in Studio under Settings → API Keys, or with an admin key via POST /v1/organizations/users/{user_email}/api-keys. A missing header returns 403; an invalid or revoked key returns 401.

X-Namespace · string · header · required

Namespace id (ns_...), not the namespace name. This scopes the request rather than authenticating it, and it is required on every operation marked x-mixpeek-namespace-scoped.

Body

application/json

Batch-execute multiple namespace-scoped list-documents queries in parallel.

Intended to collapse dossier / multi-collection UI N+1 patterns into one round-trip. Canvas pages that fan out 5–10 parallel list_documents calls (e.g., scene counts + face clusters + scene archetypes filtered by the same brand_slug) should bundle them here instead.

queries · BatchListQuery · object[] · required

Queries to execute concurrently against the same namespace.

Required array length: 1 - 10 elements

Show child attributes

Response

200

application/json

Successful Response

Response for POST /v1/documents/list/batch.

results · BatchListResult · object[] · required

One entry per input query, in the same order as requested.

Show child attributes