---
title: "Fetch market details (name/category/status/ids)"
method: POST
path: "/markets/details"
tags: ["Markets"]
---

# Fetch market details (name/category/status/ids)

`POST /markets/details`

## Request

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

Looks up market details for the given `(market_id, provider_id)` pairs. The `market_id` in the request is matched against `market_id` OR `condition_id` OR `token_id` — any identifier works. Markets with an empty/missing `market_id` in the request are silently dropped before querying. Unmatched markets are simply absent from the response — there is no `found: false` sentinel here (contrast with `/markets/metadata/batch`). Hard cap: 500 markets per request.

## Request body

- MarketsDetailsRequest
  - `markets` MarketsDetailsRequestItem[], required
    - `market_id` string, required: Matched against market_id OR condition_id OR token_id.
    - `provider_id` integer, required

## Response `200`

Matched market details (unmatched inputs are simply omitted).

- MarketsDetailsResponse
  - `markets` MarketsDetail[], required
    - `market_id` string, required
    - `provider_id` integer, required
    - `event_id` string, nullable, required
    - `name` string, nullable, required
    - `category` string, nullable, required
    - `status` string, nullable, required
    - `condition_id` string, nullable, required
    - `token_id` string, nullable, required
    - `token_ids` string[], required: Full provider token roster, aligned by index with outcomes.
    - `outcomes` string[], required: Outcome labels aligned by index with token_ids.
    - `match_delay_ms` integer, nullable: Polymarket's matching delay in milliseconds, i.e. how long Polymarket holds an order before matching it. Sports markets hold every order for whole seconds (e.g. 1000 or 3000), and the value can change while a market trades, typically at game start; some crypto "Up or Down" markets hold taker orders for 250. When both apply, this is the longer one. 0 means no delay. null for non-Polymarket markets and for Polymarket markets whose delay Kairos has not observed yet.

## Other responses

- `400`: Missing/empty `markets` array, or more than 500 markets requested.
- `401`: No valid credential presented — missing/invalid API-key headers, or an invalid/expired session token.
- `403`: Authenticated but not permitted. Three distinct causes: the session user is not invited (`Invite required`), the API key lacks the operation's scope, or API-key access to the requested venue is switched off (`API access is disabled for <provider>`). Admin and API-key callers bypass the invite check; session and admin callers bypass scope and venue checks.
- `413`: Request body exceeded the 8 MiB service-wide cap, refused before the handler ran.
- `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`: Query failed.

---

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