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

# List Queries

GET https://api.captain.dev/v2/queries

List your stored queries, newest first, scoped to the environment of the API key you call with (a production key lists production queries).

Page with `cursor` until `next_cursor` is null; there is no total count. A page can be shorter than `limit` while `next_cursor` is still set when a filter trimmed it. Your key's environment is part of the index, so pages come back full in either direction; `collection` and `status` are applied while reading, so a page can be shorter than `limit` while `next_cursor` is still set, and the API keeps reading to fill it. `from` and `to` bound the window on the index, so pair them with the other filters on large histories.

`include` inlines the same bodies `GET /v2/queries/{query_id}` returns, per row, so a feed and its previews can come from one request: `results` (retrieved chunks in one normalised shape), `request`, `response`. Each costs a stored-body read, so `limit` is capped at 25 when `include` is set. The four body fields are always present on every row and null unless requested.

History contains completed, non-streamed queries. Bodies are archived 90 days after the query (`body_status: archived`); the summary rows are kept.

Reference: https://docs.captain.dev/reference/queries/list

## Request

### Query parameters

- `collection` (string, optional, nullable) — Only queries against this collection.
- `status` (string, optional, nullable) — Filter by query status (`completed` or `failed`). Only completed queries are recorded today.
- `from` (string, optional, nullable) — Only queries created at or after this ISO-8601 date or timestamp (UTC when no offset is given).
- `to` (string, optional, nullable) — Only queries created before this ISO-8601 date or timestamp (exclusive).
- `sort` (string, optional, nullable, default: desc) — Order by creation time: `desc` (newest first, default) or `asc`.
- `limit` (integer, optional, default: 25) — Queries per page (1–100; at most 25 when `include` is set).
- `cursor` (string, optional, nullable) — Continue from a previous page's `next_cursor`.
- `include` (string, optional, nullable) — Comma-separated bodies to inline on each row: `results` (normalised retrieved chunks), `request`, `response`. Each costs a stored-body read; without it a row is a summary.

### Headers

- `authorization` (string, optional, nullable)

## Response

### 200

Successful Response

- `queries` (list of QuerySummaryV2, required)
- `count` (integer, required)
- `next_cursor` (string, optional, nullable)

## Errors

### 400 Bad Request Error

Invalid status, sort, include, time range, limit, or cursor

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

### 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)

## Types

### QuerySummaryV2

- `query_id` (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` (QuerySummaryV2Request, optional, nullable)
- `response` (QuerySummaryV2Response, optional, nullable)
- `body_status` (string, optional, nullable)

### ErrorResponseV2Details

### 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)

### QuerySummaryV2Request

### QuerySummaryV2Response

### 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

### List recent queries

**Response**

```json
{
  "queries": [
    {
      "query_id": "019a0e2a-7b31-7c4e-9d2f-3a8c1e5b6f90",
      "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": null,
      "request": null,
      "response": null,
      "body_status": null
    }
  ],
  "count": 1,
  "next_cursor": "eyJ2IjoxLCJrIjp7InF1ZXJ5X2lkIjoiMDE5YTBlMmEtN2IzMS03YzRlLTlkMmYtM2E4YzFlNWI2ZjkwIiwib3JnYW5pemF0aW9uX2lkIjoib3JnIiwiY3JlYXRlZF9hdCI6IjIwMjYtMDktMDVUMTg6NDY6MjUifSwicyI6ImRlc2MifQ"
}
```

**SDK Code**

```python Python REST
import requests

BASE_URL = "https://api.captain.dev"
API_KEY = "your_api_key"

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

response = requests.get(
    f"{BASE_URL}/v2/queries",
    headers=headers,
    params={
        "limit": 25,
        "sort": "desc"
    },
    timeout=30.0
)

if response.status_code == 200:
    data = response.json()
    for q in data["queries"]:
        print(f"{q['created_at']}  {q['latency_ms']} ms  "
              f"{q['result_count']} results  {q['query_text']!r}")
    # Page until next_cursor is null
    print(f"next_cursor={data['next_cursor']}")
else:
    print(f"Error: {response.status_code}")
```

```typescript TypeScript REST
const BASE_URL = "https://api.captain.dev";
const API_KEY = "your_api_key";

const query = new URLSearchParams({
    limit: "25",
    sort: "desc"
});

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

if (response.ok) {
    const data = await response.json();
    for (const q of data.queries) {
        console.log(`${q.created_at}  ${q.latency_ms} ms  ` +
            `${q.result_count} results  ${JSON.stringify(q.query_text)}`);
    }
    // Page until next_cursor is null
    console.log(`next_cursor=${data.next_cursor}`);
} else {
    console.error(`Error: ${response.status}`);
}
```

### Feed and previews in one request

**Response**

```json
{
  "queries": [
    {
      "query_id": "019a0e2a-7b31-7c4e-9d2f-3a8c1e5b6f90",
      "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": null,
      "response": null,
      "body_status": "available"
    }
  ],
  "count": 1,
  "next_cursor": null
}
```

**SDK Code**

```python Python REST
import requests

BASE_URL = "https://api.captain.dev"
API_KEY = "your_api_key"

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

response = requests.get(
    f"{BASE_URL}/v2/queries",
    headers=headers,
    params={
        "collection": "clinical-docs",
        "from": "2026-09-01",
        "include": "results",
        "limit": 25
    },
    timeout=30.0
)

if response.status_code == 200:
    data = response.json()
    for q in data["queries"]:
        print(q["query_text"], q["body_status"])
        for r in q["results"] or []:
            print(f"  #{r['rank']} {r['filename']} p.{(r['location'] or {}).get('page_start')} {r['score']:.3f}")
    # Page until next_cursor is null
    print(f"next_cursor={data['next_cursor']}")
else:
    print(f"Error: {response.status_code}")
```

```typescript TypeScript REST
const BASE_URL = "https://api.captain.dev";
const API_KEY = "your_api_key";

const query = new URLSearchParams({
    collection: "clinical-docs",
    from: "2026-09-01",
    include: "results",
    limit: "25"
});

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

if (response.ok) {
    const data = await response.json();
    for (const q of data.queries) {
        console.log(q.query_text, q.body_status);
        for (const r of q.results ?? []) {
            console.log(`  #${r.rank} ${r.filename} p.${r.location?.page_start} ${r.score?.toFixed(3)}`);
        }
    }
    // Page until next_cursor is null
    console.log(`next_cursor=${data.next_cursor}`);
} else {
    console.error(`Error: ${response.status}`);
}
```