---
title: "Fetch volume and outcome-pressure metrics for a contract"
method: GET
path: "/trades/metrics"
tags: ["Trades"]
---

# Fetch volume and outcome-pressure metrics for a contract

`GET /trades/metrics`

## Request

- Base URL: `https://data.kairos.trade`
- URL: `https://data.kairos.trade/trades/metrics`
- Auth: API key in header `X-Client-Id` and API key in header `X-Api-Key` and API key in header `X-Api-Secret`

Returns aggregate trade metrics (volume, per-outcome volume split, trade count) for a single `(provider, contract_id)` over a lookback window, computed from Kairos's own ingested trade store — same data source as `/trades/history`, not a live upstream proxy. There is no buy/sell-side breakdown: metrics are split by outcome (`outcome_0`/`outcome_1`) rather than trade direction, since trade direction cannot be reliably determined from exchange data for all providers.

**Auth**: requires the `trade:read` scope (admin/JWT bypass the scope check; API keys need `trade:read`), plus API access to the requested provider being enabled for API-key callers — 403 if disabled.

**Staleness**: if `trigger_ingest=true` and ingestion coverage for the window is low, the service triggers a backfill/ingestion job and reports it via the `indexing` flag on the returned metrics object.

## Query parameters

- `provider` string, required
- `contract_id` string, required
- `window_seconds` integer
- `trigger_ingest` boolean

## Response `200`

Aggregate volume/pressure metrics for the window.

- TradesMetricsResponse
  - `metrics` TradesMetrics, required: Aggregate volume/pressure metrics. Split by outcome (outcome_0 vs outcome_1), not by buy/sell direction — trade direction is not reliably derivable from every provider's exchange data.
    - `volume_usd` number, required: Total notional volume in the window, in USD.
    - `outcome_0_volume_usd` number, required: Notional volume attributed to the first/primary outcome (e.g. "yes").
    - `outcome_1_volume_usd` number, required: Notional volume attributed to the second outcome (e.g. "no").
    - `outcome_0_pressure_pct` number, required: Share of total volume_usd attributed to outcome_0, as a percentage (0-100).
    - `trade_count` integer, required: Number of trades included in the aggregation.
    - `window_seconds` integer, required: Window width the metrics were computed over, in seconds.
    - `coverage_pct` number, required: Estimated data coverage for the window as a percentage (0-100); 100 for live upstream proxies (Kalshi/Polymarket) and for fully-ingested windows.
    - `source` string, required: Opaque internal marker indicating how the response was produced. NOT a stable part of the contract — its value may change without notice; do not depend on or switch on it.
    - `indexing` boolean, required: True if an ingestion/backfill job was triggered or is in progress for this window (only meaningful when the caller passed `trigger_ingest=true`); coverage may be incomplete when true.

## Other responses

- `400`: Invalid trade metrics request (unknown provider, invalid contract_id, or a request the service itself rejected as malformed).
- `401`: No valid credential presented — missing/invalid API-key headers, or an invalid/expired session token.
- `403`: API-key credential lacks the `trade:read` scope, or API access to the requested provider is currently disabled.
- `422`: Request failed FastAPI parameter validation.
- `429`: Rate limit exceeded for this route's sliding window, keyed on the session `sub` when authenticated and on the trusted client IP otherwise. Honor `Retry-After`. A per-API-key data ceiling (set per credential) rejects with `{"detail": "API key data rate limit exceeded"}` instead of the `error` envelope below.
- `500`: Trade metrics fetch failed on the backend.
- `503`: Per-venue API-access flag could not be read or validated.

---

[API](https://skmtc.dev/kairos/apis/kairos-data-api.md) - [All operations](https://skmtc.dev/kairos/apis/kairos-data-api/llms.txt) - [OpenAPI document](https://skmtc.dev/kairos/apis/kairos-data-api/revisions/cf6b76079e38?raw)