Get Query Latency

import requests
BASE_URL = "https://api.captain.dev"
API_KEY = "your_api_key"
response = requests.get(
    f"{BASE_URL}/v2/queries/latency",
    headers={"Authorization": f"Bearer {API_KEY}"},
    params={
        "from": "2026-09-01",
        "to": "2026-09-08",
        "bins": 6,
    },
    timeout=30.0
)
if response.status_code == 200:
    data = response.json()
    p = data["percentiles"]
    counts = data["counts"]
    print(f"p50={p['p50']} ms  p95={p['p95']} ms  p99={p['p99']} ms")
    print(f"{counts['measured']} of {counts['matching']} queries measured, "
          f"{counts['missing']} without a recorded duration")
    for c in data["collections"]:
        # The "Other" bucket carries counts but no percentiles: a summed
        # histogram cannot yield an exact quantile.
        shown = f"p95={c['p95']} ms" if c["p95"] is not None else "no percentiles"
        print(f"  {c['collection_name']:24s} {c['count']:6d} queries  {shown}")
    if not data["completeness"]["complete"]:
        print(f"Partial: usage is written up to {data['completeness']['watermark']}")
else:
    print(f"Error: {response.status_code}")

{
  "completeness": {
    "complete": true,
    "watermark": "2026-09-07T23:58:11.402Z"
  },
  "counts": {
    "matching": 2614,
    "measured": 2611,
    "missing": 3
  },
  "filters_applied": {
    "api_version": null,
    "collection": null,
    "has_filter": null,
    "query_environment": null,
    "rerank": null,
    "search_mode": null
  },
  "generated_at": "2026-09-08T00:04:02.118Z",
  "histogram": {
    "counts": [
      104,
      1387,
      702,
      298,
      81,
      39
    ],
    "edges": [
      0,
      200,
      400,
      600,
      800,
      1000,
      1200
    ]
  },
  "percentiles": {
    "p50": 287,
    "p95": 715,
    "p99": 1204
  },
  "population": "Completed, non-evaluation queries. A failed query records no usage row, and evaluation units are excluded.",
  "window": {
    "from": "2026-09-01T00:00:00Z",
    "to": "2026-09-08T00:00:00Z"
  },
  "collections": [
    {
      "collection_name": "customer_forms",
      "count": 1902,
      "counts": [
        88,
        1094,
        486,
        190,
        30,
        14
      ],
      "is_other": false,
      "p50": 271,
      "p95": 668,
      "p99": 1122
    },
    {
      "collection_name": "policy_library",
      "count": 512,
      "counts": [
        12,
        221,
        158,
        83,
        27,
        11
      ],
      "is_other": false,
      "p50": 352,
      "p95": 790,
      "p99": 1290
    },
    {
      "collection_name": "Other",
      "count": 197,
      "counts": [
        4,
        72,
        58,
        25,
        24,
        14
      ],
      "is_other": true,
      "p50": null,
      "p95": null,
      "p99": null
    }
  ],
  "coverage": {
    "rerank": 0.99,
    "search_mode": 0.69,
    "has_filter": 0.15
  },
  "metric": "query_processing_time",
  "metric_version": "1",
  "percentile_method": "exact",
  "unit": "ms"
}

Latency percentiles and a histogram for a window of your stored queries.

Unlike GET /v2/queries, which pages through individual records, this summarises the whole filtered population in one bounded response: counts, exact p50/p95/p99, explicit histogram edges, and the same bins per collection so their shapes can be compared.

Two numbers are reported separately on purpose. counts.measured are the queries with a recorded processing time; counts.missing are matching queries without one, which are left out of the percentiles rather than counted as zero milliseconds. coverage says how much of the population recorded each filterable setting, because older queries predate some of them and answer unknown.

Windows are capped at 90 days. Use GET /v2/queries to drill into individual queries.

Query parameters

fromstring or nullOptional

Start of the window, inclusive. ISO-8601 date or timestamp (UTC when no offset is given).

tostring or nullOptional

End of the window, exclusive.

collectionstring or nullOptional

Only queries against this collection.

api_versionstring or nullOptional

v3, v2, or unknown for queries that recorded no version.

rerankstring or nullOptional

The recorded rerank setting: on, off, or unknown. A setting of on does not mean reranking ran.

search_modestring or nullOptional

keyword, semantic, hybrid, or unknown, derived from the recorded semantic ratio.

has_filterstring or nullOptional

true, false, or unknown for queries that recorded no filter setting.

binsinteger or nullOptional

Histogram resolution (4-64; default 16). Edges are returned explicitly.

refreshbooleanOptionalDefaults to false

Recompute instead of serving a briefly cached result.

Response

Successful Response

completenessobject

countsobject

filters_appliedobject

generated_atstring

When these numbers were computed. A cached response keeps its original value.

histogramobject

percentilesobject

populationstring

Which queries the metric covers. Completed, non-evaluation queries: a failed query records no usage row, and evaluation units are excluded.

windowobject

collectionslist of objectsOptional

coveragemap from strings to doublesOptional

Per filter, the share of matching queries that recorded that dimension (0.0-1.0). A low value means most of the population answers unknown.

metric"query_processing_time"OptionalDefaults to query_processing_time

What is being measured: server-side query processing time, not end-to-end client latency.

metric_versionstringOptionalDefaults to 1

percentile_method"exact"OptionalDefaults to exact

Percentiles come from the measurements themselves, not an approximate sketch.

unit"ms"OptionalDefaults to ms

Errors

400

Bad Request Error

401

Unauthorized Error

403

Forbidden Error

422

Unprocessable Entity Error

503

Service Unavailable Error