Batched form of GET /v1/candles: fetches up to 200 independent (provider, contract_id, timeframe_seconds, start, end, outcome) series concurrently and returns them in request order, with per-index partial failure — one item's validation or fetch error does not fail the others.

Each item is validated and aligned exactly as in GET /v1/candles (same clamping, rollup, and inversion rules). Body accepts either a requests array or a legacy items alias; if requests is non-empty it is used, otherwise items is used. timeframe_seconds and outcome in each item may be a JSON number or a numeric string. The request body is capped at 4 MiB.

Rate limiting / cost. Priced like the equivalent run of single GET /v1/candles calls: 1 light-bucket unit per item plus 1 per 5,000 requested bars, so a 200-item batch costs at least 200 units. The first unit is admitted up front; the rest is charged as a deferred extra charge against your next request.

Caching. Batch responses are always Cache-Control: no-store and never carry an ETag.

Binary format. Pass ?fmt=binary or Accept: application/x-kairos-candles to receive a single multi-result binary frame (num_results = len(requests)) — one columnar result section per request index, in input order. An item that failed sets the high bit (0x80000000) of its section's count, so it stays distinguishable from a genuinely empty window; mask the bit off to read the (always zero) count. Per-item error messages are only available in the JSON response.

Failure semantics. Returns 500 only when every item in the batch failed. Otherwise 200 with a mix of populated and empty/errored entries.

{
  "requests": [
    {
      "provider": "polymarket",
      "contract_id": "21742633143463906290569050155826241533067272736897614950488156847949938836455",
      "start": "2026-07-15T00:00:00Z",
      "end": "2026-07-16T00:00:00Z"
    }
  ],
  "items": [
    {
      "provider": "polymarket",
      "contract_id": "21742633143463906290569050155826241533067272736897614950488156847949938836455",
      "start": "2026-07-15T00:00:00Z",
      "end": "2026-07-16T00:00:00Z"
    }
  ]
}

{
  "results": [
    {
      "candles": [
        {
          "contract_id": "21742633143463906290569050155826241533067272736897614950488156847949938836455",
          "timeframe_seconds": 3600,
          "bucket_start": "2026-07-15T00:00:00+00:00",
          "open": 61.5,
          "high": 63,
          "low": 60.8,
          "close": 62.4,
          "volume": 184230,
          "token_id": "704721957297303853272349184"
        }
      ],
      "error": "unknown provider \"acme\""
    }
  ]
}