---
title: "Fetch multiple markets by id, one provider at a time"
method: POST
path: "/v1/markets/batch"
tags: ["Markets"]
---

# Fetch multiple markets by id, one provider at a time

`POST /v1/markets/batch`

## Request

- Base URL: `https://md.kairos.trade`
- URL: `https://md.kairos.trade/v1/markets/batch`
- Auth: one of:
  - none
  - API key in header `X-Client-Id` and API key in header `X-Api-Key` and API key in header `X-Api-Secret`

Fetches metadata for one provider and up to 200 market ids in a single call. Rate-limit bucket: LIGHT, flat cost of 1 unit regardless of batch size (unlike `/v1/market-identifiers/resolve`, this endpoint does NOT charge per-item). Not cached (`Cache-Control: no-store`) — every call returns live data.

Request body is capped at 1 MiB, and `market_ids` is capped at 200 entries per request (`market_ids exceeds maximum 200`).

Ids that cannot be found are omitted from `markets` and listed in `misses`.

## Request body

- MarketBatchRequest: Request body for POST /v1/markets/batch.
  - `provider` 'kalshi' | 'polymarket' | 'opinion' | 'predictfun' | 'hyperliquid' | 'kalshi_offchain' | 'dome', required
  - `market_ids` string[], required: Up to 200 market ids for the given provider.

## Response `200`

Batch lookup result, keyed by market_id.

- MarketBatchResponse: Response body for POST /v1/markets/batch.
  - `exchange_id` string, required
  - `markets` object, required: Map of market_id → Market, for every requested id that was found.
  - `misses` string[], required: market_ids from the request that were not found.

## Other responses

- `400`: Unreadable/invalid JSON body, unknown provider, missing `market_ids`, or `market_ids` exceeds the maximum of 200.
- `401`: No valid credential presented. Every path returns `code: unauthorized`; the triggers differ: - An `Authorization` header on a deployment where bearer auth is not enabled (`bearer authentication is not enabled`). - A bearer token that fails verification (`invalid or expired session`), or whose token/session has been revoked (`session has been revoked`). - An incomplete or wrong API-key header set. Sending *any* of `X-Client-Id`, `X-Api-Key`, `X-Api-Secret` commits the request to the API-key path, so a partial set is rejected rather than silently degrading to anonymous limits (`valid X-Client-Id, X-Api-Key, and X-Api-Secret headers are required`). - No credential material at all while the anonymous free tier is unavailable — switched off for the deployment, forced off through the runtime kill switch, or not yet resolvable on a replica that has never read the flag (it fails closed).
- `403`: API key presented from a source IP not in that credential's whitelist.
- `404`: The upstream metadata cache answered the batch lookup with 404. Individual ids that are simply absent come back in `misses` with a 200 instead.
- `429`: Two different gates return this status, both with `code: rate_limited`: - **Per-credential (or per-IP, when anonymous) weighted budget exhausted.** The message is `rate limit exceeded`, or, for anonymous callers, `anonymous rate limit exceeded — request an API key for higher limits (…)`. `Retry-After` is the whole number of seconds until the current one-minute window rolls over, floored at 1. All four `X-RateLimit-*` headers are present. - **Per-IP admission gate.** An in-process, pre-authentication guard that keeps a flood off the shared credential cache and database. The message is `too many requests from this address` and `Retry-After` is a flat `60`. Because this fires *before* authentication, the response carries **no** `X-RateLimit-*` headers at all.
- `500`: `internal` / `authentication backend unavailable` — the API-key path could not reach the credential store.
- `502`: The metadata cache answered with an unexpected status (`upstream` / `metadata cache request failed`).
- `503`: `cache_cold` — the metadata cache is still warming (with `Retry-After: 5`); `unavailable` — no metadata cache is configured for this deployment; or `rate_limiter_unavailable`.

---

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