Multi-Collection Query - v3

import requests
BASE_URL = "https://api.captain.dev"
API_KEY = "your_api_key"
response = requests.post(
    f"{BASE_URL}/v3/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 is a full v3 query against one collection: it takes every Query parameter plus collection, and the top-level query fills any entry that omits its own.

Results are per entry and never merged. results[i] answers collections[i] and holds that collection’s own ranked list. Scores from different collections are not comparable. Check each entry’s status before reading its results.

Captain runs the entries at the same time, so the request takes about as long as its slowest entry.

Errors found before any search fail the whole request and nothing is billed: a 422 for a missing or blank query or a bad number of entries, a 400 for an invalid entry setting, a 403 for a missing query permission or an inactive collection, a 404 for an unknown or deleted collection. Once searching starts, a failed entry keeps its error in its own slot and the response is still 200. Retry only the failed entries.

Billing: each succeeded entry bills as one query and appears in query history with its own query_id. Failed entries are not billed.

See Query Several Collections for the full guide.

Query up to 10 collections in one request. Each entry in `collections` is a full v3 query against one collection: it takes every [Query](/reference/v3/query) parameter plus `collection`, and the top-level `query` fills any entry that omits its own. **Results are per entry and never merged.** `results[i]` answers `collections[i]` and holds that collection's own ranked list. Scores from different collections are not comparable. Check each entry's `status` before reading its `results`. **Captain runs the entries at the same time**, so the request takes about as long as its slowest entry. **Errors found before any search fail the whole request** and nothing is billed: a 422 for a missing or blank query or a bad number of entries, a 400 for an invalid entry setting, a 403 for a missing `query` permission or an inactive collection, a 404 for an unknown or deleted collection. Once searching starts, a failed entry keeps its error in its own slot and the response is still 200. Retry only the failed entries. **Billing:** each succeeded entry bills as one query and appears in query history with its own `query_id`. Failed entries are not billed. 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

Captain runs the entries at the same time, so the request takes about as long as its slowest entry.

Billing: each succeeded entry bills as one query and appears in query history with its own query_id. Failed entries are not billed.

See Query Several Collections for the full guide.