Batch Query - v3 | Captain Docs

import requests
BASE_URL = "https://api.captain.dev"
API_KEY = "your_api_key"
response = requests.post(
    f"{BASE_URL}/v3/collections/batch-query",
    headers={
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json",
    },
    json={
        "query": "renewal terms",
        "collections": [
            {"collection": "contracts", "limit": 3, "filter": {"region": "EU"}},
            {"collection": "emails", "limit": 2, "query": "contract renewal reminder"},
        ],
    },
    timeout=60.0,
)
response.raise_for_status()
for entry in response.json()["results"]:
    if entry["status"] == "failed":
        print(entry["collection"], "failed:", entry["error"]["message"])
        continue
    for result in entry["results"]:
        print(entry["collection"], result["chunk_id"], round(result["score"], 4))

{
  "execution_time_ms": 431,
  "request_id": "req_1790600000_3f9a1c2e",
  "results": [
    {
      "status": "succeeded",
      "collection": "contracts",
      "limit": 3,
      "query": "renewal terms",
      "rerank": {
        "used": false,
        "reason": "disabled"
      },
      "results": [
        {
          "chunk_id": "7c2e9a41d5b84f0e9a3c6d18b2f47e05:4",
          "score": 0.0833,
          "text": "12.1 Renewal. This Agreement renews automatically for successive twelve-month terms unless either party gives written notice of non-renewal at least ninety days before the end of the current term.",
          "modality": "pdf",
          "match_sources": [
            "content_embedding",
            "keyword"
          ],
          "document": {
            "id": "7c2e9a41d5b84f0e9a3c6d18b2f47e05",
            "filename": "msa-northwind-2025.pdf",
            "source": {
              "type": "file",
              "uri": "captain://org_example/users/user_example/collections/contracts/msa-northwind-2025.pdf",
              "mime_type": "application/pdf"
            }
          },
          "location": {
            "page_start": 9,
            "page_end": 9,
            "chunk_index": 4,
            "parent_chunk_index": 4,
            "start_seconds": null,
            "end_seconds": null,
            "sheet_name": null,
            "row_start": null,
            "row_end": null,
            "col_start": null,
            "col_end": null
          },
          "custom_metadata": {
            "region": "EU"
          }
        }
      ],
      "timing": {
        "stages": [
          {
            "name": "preparation",
            "start_ms": 0,
            "duration_ms": 22
          },
          {
            "name": "embedding",
            "start_ms": 22,
            "duration_ms": 171
          },
          {
            "name": "retrieval",
            "start_ms": 193,
            "duration_ms": 142
          },
          {
            "name": "fusion",
            "start_ms": 335,
            "duration_ms": 9
          },
          {
            "name": "hydration",
            "start_ms": 344,
            "duration_ms": 44
          }
        ],
        "total_ms": 388
      },
      "total_results": 1,
      "boost": [],
      "exclude_chunk_types": [],
      "execution_time_ms": 388,
      "query_id": "019b8e41-6c2a-7d13-a5f0-2e7c9b4d1a60",
      "request_id": "req_1790600000_3f9a1c2e-0",
      "semantic_ratio": 0.5,
      "warnings": []
    },
    {
      "status": "succeeded",
      "collection": "emails",
      "limit": 2,
      "query": "contract renewal reminder",
      "rerank": {
        "used": false,
        "reason": "disabled"
      },
      "results": [
        {
          "chunk_id": "b41f0d7a93e2468c8e5a1f27c9d30b6e:0",
          "score": 0.0909,
          "text": "Subject: Northwind renewal notice window\n\nA reminder that the Northwind agreement renews on March 1. Notice of non-renewal is due by December 1.",
          "modality": "email",
          "match_sources": [
            "content_embedding",
            "keyword"
          ],
          "document": {
            "id": "b41f0d7a93e2468c8e5a1f27c9d30b6e",
            "filename": "northwind-renewal-reminder.eml",
            "source": {
              "type": "file",
              "uri": "captain://org_example/users/user_example/collections/emails/northwind-renewal-reminder.eml",
              "mime_type": "message/rfc822"
            }
          }
        }
      ],
      "timing": {
        "stages": [
          {
            "name": "preparation",
            "start_ms": 0,
            "duration_ms": 25
          },
          {
            "name": "embedding",
            "start_ms": 25,
            "duration_ms": 176
          },
          {
            "name": "retrieval",
            "start_ms": 201,
            "duration_ms": 150
          },
          {
            "name": "fusion",
            "start_ms": 351,
            "duration_ms": 8
          },
          {
            "name": "hydration",
            "start_ms": 359,
            "duration_ms": 43
          }
        ],
        "total_ms": 402
      },
      "total_results": 1,
      "boost": [],
      "exclude_chunk_types": [],
      "execution_time_ms": 402,
      "query_id": "019b8e41-6c2b-7a88-9d34-5b1e0f7c2a91",
      "request_id": "req_1790600000_3f9a1c2e-1",
      "semantic_ratio": 0.5,
      "warnings": []
    }
  ]
}

Query up to 10 collections in one request. Each entry in collections takes every Query parameter plus collection, and the top-level query fills any entry that omits its own.

results[i] answers collections[i] with that collection’s own ranked list. Lists are never merged, and scores from different collections are not comparable. Check each entry’s status before reading its results: errors found before any search fail the whole request, and a failure during a search stays in its own slot.

See Query Several Collections for the full guide.

Query up to 10 collections in one request. Each entry in `collections` takes every [Query](/reference/v3/query) parameter plus `collection`, and the top-level `query` fills any entry that omits its own. `results[i]` answers `collections[i]` with that collection's own ranked list. Lists are never merged, and scores from different collections are not comparable. Check each entry's `status` before reading its `results`: errors found before any search fail the whole request, and a failure during a search stays in its own slot. See [Query Several Collections](/guides/advanced-querying#query-several-collections) for the full guide.

Request

This endpoint expects an object.

collectionslist of objectsRequired

One entry per collection to query, 1 to 10. Each entry takes every v3 Query parameter plus collection. results[i] in the response answers collections[i]. The same collection may appear more than once.

querystring or nullOptional>=1 character

Query used by every entry that does not set its own query.

Response

One result per entry, in request order.

execution_time_msinteger

Wall-clock time for the whole request, in milliseconds.

request_idstring

resultslist of objects

One entry per requested collection, in request order: results[i] answers collections[i]. Each entry is its own ranked list; results are never merged across collections, and scores from different collections are not comparable. Check status before reading an entry’s results.

Errors

400

Bad Request Error

401

Unauthorized Error

403

Forbidden Error

404

Not Found Error

422

Unprocessable Entity Error

504

Gateway Timeout Error