Query - v2 (Legacy) | Captain Docs

import requests
url = "https://host.com/v2/collections/collection_name/query"
payload = { "query": "latest advancements in renewable energy" }
headers = {"Content-Type": "application/json"}
response = requests.post(url, json=payload, headers=headers)
print(response.json())

{
  "success": true,
  "query": "latest advancements in renewable energy",
  "search_results": [
    {
      "score": 0.95,
      "content": "Recent studies show significant improvements in solar panel efficiency and wind turbine design.",
      "chunk_id": "chunk_7890",
      "document_id": "doc_4567",
      "filename": "renewable_energy_report_2024.pdf",
      "uri": "https://example.com/reports/renewable_energy_report_2024.pdf",
      "chunk_index": 3,
      "metadata": {
        "key": "energy"
      },
      "rerank_score": 0.92
    }
  ],
  "total_results": 1,
  "top_k": 1,
  "warnings": [
    "Rerank was enabled for this query."
  ],
  "tokens_used": {
    "key": 134
  },
  "execution_time_ms": 245,
  "request_id": "req_1234567890abcdef",
  "token_balance": {
    "credit_limit": 100000,
    "total_used": 45200,
    "remaining": 54800,
    "unlimited": false
  }
}

Execute the v2 File Search endpoint against a collection. Returns retrieved chunks in search_results with content fields.

Path parameters

collection_namestringRequired

Request

This endpoint expects an object.

querystringRequired

Natural-language search query.

top_kintegerOptional

Maximum number of search results to return.

metadata_filtermap from strings to anyOptional

Filter expression for indexed document metadata. Supports $eq,$ ne, $gt,$ gte, $lt,$ lte, $in,$ nin, $and, and$ or.

Filter expression for indexed document metadata. Supports $eq, $ne, $gt, $gte, $lt, $lte, $in, $nin, $and, and $or.

rerankbooleanOptional

Enable reranking for text-only collections. Multimodal collections always rerank and return a warning if rerank=false is ignored.

include_bboxbooleanOptional

Legacy v2 layout option retained for clients that already depend on bounding boxes.

Response

Successful Response

successboolean

querystring

search_resultslist of objects

total_resultsinteger

top_kinteger

warningslist of strings

tokens_usedmap from strings to optional integers

execution_time_msinteger

request_idstring

token_balanceobject