> For a complete page index of the Captain API documentation, fetch https://docs.captain.dev/llms.txt?excludeSpec=true

# Get Query

GET https://api.filesearch.dev/v2/queries/{query_id}

One stored query with its request body, response body and the retrieved chunks in one normalised shape (`results[]`: rank, score, text, filename, document id and a page, time or sheet location, whether the query ran on v2 or v3).

`query_id` is the id from `GET /v2/queries` or the `query_id` field of a query response. The `request_id` a query response returns (`req_...`) is accepted in its place, so a query can be fetched straight after running it.

`body_status` says what came back: `available`, `archived` (bodies are archived 90 days after the query and only the summary remains) or `missing`. A query from another organization or environment is a 404, the same as an unknown id.

Reference: https://docs.runcaptain.com/reference/queries/get

## Request

### Path parameters

- `query_id` (string, required)

### Headers

- `authorization` (string, optional, nullable)

## Response

### 200

Successful Response

- `query_id` (string, required)
- `body_status` (string, required)
- `query_text` (string, optional, nullable)
- `collection_name` (string, optional, nullable)
- `environment` (string, optional, nullable)
- `status` (string, optional, nullable)
- `api_version` (string, optional, nullable)
- `created_at` (string, optional, nullable)
- `latency_ms` (integer, optional, nullable)
- `result_count` (integer, optional, nullable)
- `request_id` (string, optional, nullable)
- `params` (QueryParamsV2, optional, nullable)
- `results` (list of QueryResultV2, optional, nullable)
- `request` (QueryDetailV2Request, optional, nullable)
- `response` (QueryDetailV2Response, optional, nullable)
- `error_message` (string, optional, nullable)
- `error_type` (string, optional, nullable)

## Errors

### 401 Unauthorized Error

Missing or invalid API key

- `error` (string, required)
- `message` (string, required)
- `details` (ErrorResponseV2Details, optional, nullable)
- `path` (string, optional, nullable)
- `success` (boolean, optional, default: false)

### 403 Forbidden Error

The API key does not have query permission

- `error` (string, required)
- `message` (string, required)
- `details` (ErrorResponseV2Details, optional, nullable)
- `path` (string, optional, nullable)
- `success` (boolean, optional, default: false)

### 404 Not Found Error

No query with this id (query_id or request_id) in the key's organization and environment.

- `code` (string, required) — Stable error code, for example `invalid_time_range`.
- `message` (string, required) — What went wrong.
- `path` (string, required) — The request path.

## Types

### QueryParamsV2

- `limit` (integer, optional, nullable)
- `semantic_ratio` (double, optional, nullable)
- `has_filter` (boolean, optional, nullable)
- `has_boost` (boolean, optional, nullable)
- `exclude_chunk_types` (list of string, optional, nullable)
- `include` (QueryParamsV2Include, optional, nullable)

### QueryResultV2

- `rank` (integer, required)
- `chunk_id` (string, optional, nullable)
- `score` (double, optional, nullable)
- `rerank_score` (double, optional, nullable)
- `text` (string, optional, default: )
- `filename` (string, optional, nullable)
- `document_id` (string, optional, nullable)
- `modality` (string, optional, nullable)
- `chunk_type` (string, optional, nullable)
- `location` (QueryResultLocationV2, optional, nullable)

### QueryDetailV2Request

### QueryDetailV2Response

### ErrorResponseV2Details

### QueryParamsV2Include

### QueryResultLocationV2

- `page_start` (integer, optional, nullable)
- `page_end` (integer, optional, nullable)
- `start_seconds` (double, optional, nullable)
- `end_seconds` (double, optional, nullable)
- `sheet_name` (string, optional, nullable)
- `row_start` (integer, optional, nullable)

## Examples

### Get a stored query

**Response**

```json
{
  "query_id": "019a0e2a-7b31-7c4e-9d2f-3a8c1e5b6f90",
  "body_status": "available",
  "query_text": "What are the adverse reactions listed for metformin?",
  "collection_name": "clinical-docs",
  "environment": "production",
  "status": "completed",
  "api_version": "v3",
  "created_at": "2026-09-05T18:46:25.660882Z",
  "latency_ms": 412,
  "result_count": 5,
  "request_id": "req_1788633985_84509ca6",
  "params": {
    "limit": 5,
    "semantic_ratio": 0.5,
    "has_filter": false,
    "has_boost": false,
    "exclude_chunk_types": null,
    "include": null,
    "rerank": true
  },
  "results": [
    {
      "rank": 1,
      "chunk_id": "chk_7d0c2b",
      "score": 0.9134,
      "rerank_score": 0.88,
      "text": "Common adverse reactions (≥5%) include diarrhea, nausea/vomiting, flatulence, asthenia, indigestion, abdominal discomfort, and headache.",
      "filename": "metformin-label.pdf",
      "document_id": "2f517447a1b22714dcdbd80dd777fd07",
      "modality": "pdf",
      "chunk_type": "body",
      "location": {
        "page_start": 4,
        "page_end": 4,
        "start_seconds": null,
        "end_seconds": null,
        "sheet_name": null,
        "row_start": null
      }
    }
  ],
  "request": {
    "query": "What are the adverse reactions listed for metformin?",
    "limit": 5,
    "rerank": true,
    "semantic_ratio": 0.5
  },
  "response": {
    "results": [
      {
        "chunk_id": "chk_7d0c2b",
        "score": 0.9134,
        "rerank_score": 0.88,
        "text": "Common adverse reactions (≥5%) include diarrhea, nausea/vomiting, flatulence, asthenia, indigestion, abdominal discomfort, and headache.",
        "document": {
          "id": "2f517447a1b22714dcdbd80dd777fd07",
          "filename": "metformin-label.pdf"
        },
        "location": {
          "page_start": 4,
          "page_end": 4
        },
        "modality": "pdf",
        "chunk_type": "body"
      }
    ],
    "total_results": 5
  },
  "error_message": null,
  "error_type": null
}
```

**SDK Code**

```python Python REST
import requests
import json

BASE_URL = "https://api.filesearch.dev"
API_KEY = "your_api_key"
QUERY_ID = "019a0e2a-7b31-7c4e-9d2f-3a8c1e5b6f90"

headers = {
    "Authorization": f"Bearer {API_KEY}",
}

response = requests.get(
    f"{BASE_URL}/v2/queries/{QUERY_ID}",
    headers=headers,
    timeout=30.0,
)

q = response.json()
print(q["query_text"], q["body_status"])
for r in q["results"]:
    print(f"#{r['rank']} {r['filename']} {r['score']:.3f}: {r['text'][:80]}")
print(json.dumps(q["request"], indent=2))
```

```typescript TypeScript REST
const BASE_URL = "https://api.filesearch.dev";
const API_KEY = "your_api_key";
const query_id = "019a0e2a-7b31-7c4e-9d2f-3a8c1e5b6f90";

const response = await fetch(`${BASE_URL}/v2/queries/${query_id}`, {
  method: "GET",
  headers: { "Authorization": `Bearer ${API_KEY}` },
});

const q = await response.json();
console.log(q.query_text, q.body_status);
for (const r of q.results) {
  console.log(`#${r.rank} ${r.filename} ${r.score?.toFixed(3)}: ${r.text.slice(0, 80)}`);
}
console.log(JSON.stringify(q.request, null, 2));
```

### Get a query by its request_id

**Response**

```json
{
  "query_id": "019a0e2a-7b31-7c4e-9d2f-3a8c1e5b6f90",
  "body_status": "available",
  "query_text": "What are the adverse reactions listed for metformin?",
  "collection_name": "clinical-docs",
  "environment": "production",
  "status": "completed",
  "api_version": "v3",
  "created_at": "2026-09-05T18:46:25.660882Z",
  "latency_ms": 412,
  "result_count": 5,
  "request_id": "req_1788633985_84509ca6",
  "params": {
    "limit": 5,
    "semantic_ratio": 0.5,
    "has_filter": false,
    "has_boost": false,
    "exclude_chunk_types": null,
    "include": null,
    "rerank": true
  },
  "results": [
    {
      "rank": 1,
      "chunk_id": "chk_7d0c2b",
      "score": 0.9134,
      "rerank_score": 0.88,
      "text": "Common adverse reactions (≥5%) include diarrhea, nausea/vomiting, flatulence, asthenia, indigestion, abdominal discomfort, and headache.",
      "filename": "metformin-label.pdf",
      "document_id": "2f517447a1b22714dcdbd80dd777fd07",
      "modality": "pdf",
      "chunk_type": "body",
      "location": {
        "page_start": 4,
        "page_end": 4,
        "start_seconds": null,
        "end_seconds": null,
        "sheet_name": null,
        "row_start": null
      }
    }
  ],
  "request": {
    "query": "What are the adverse reactions listed for metformin?",
    "limit": 5,
    "rerank": true,
    "semantic_ratio": 0.5
  },
  "response": {
    "results": [
      {
        "chunk_id": "chk_7d0c2b",
        "score": 0.9134,
        "rerank_score": 0.88,
        "text": "Common adverse reactions (≥5%) include diarrhea, nausea/vomiting, flatulence, asthenia, indigestion, abdominal discomfort, and headache.",
        "document": {
          "id": "2f517447a1b22714dcdbd80dd777fd07",
          "filename": "metformin-label.pdf"
        },
        "location": {
          "page_start": 4,
          "page_end": 4
        },
        "modality": "pdf",
        "chunk_type": "body"
      }
    ],
    "total_results": 5
  },
  "error_message": null,
  "error_type": null
}
```

**SDK Code**

```python Python REST
import requests
import json

BASE_URL = "https://api.filesearch.dev"
API_KEY = "your_api_key"
QUERY_ID = "019a0e2a-7b31-7c4e-9d2f-3a8c1e5b6f90"

headers = {
    "Authorization": f"Bearer {API_KEY}",
}

response = requests.get(
    f"{BASE_URL}/v2/queries/{QUERY_ID}",
    headers=headers,
    timeout=30.0,
)

q = response.json()
print(q["query_text"], q["body_status"])
for r in q["results"]:
    print(f"#{r['rank']} {r['filename']} {r['score']:.3f}: {r['text'][:80]}")
print(json.dumps(q["request"], indent=2))
```

```typescript TypeScript REST
const BASE_URL = "https://api.filesearch.dev";
const API_KEY = "your_api_key";
const query_id = "019a0e2a-7b31-7c4e-9d2f-3a8c1e5b6f90";

const response = await fetch(`${BASE_URL}/v2/queries/${query_id}`, {
  method: "GET",
  headers: { "Authorization": `Bearer ${API_KEY}` },
});

const q = await response.json();
console.log(q.query_text, q.body_status);
for (const r of q.results) {
  console.log(`#${r.rank} ${r.filename} ${r.score?.toFixed(3)}: ${r.text.slice(0, 80)}`);
}
console.log(JSON.stringify(q.request, null, 2));
```