# Get candles

Source: https://langbot.ai/docs/api/history/get-candles

`GET /v1/history/candles`

One market's price history as candles, oldest first, paged by time.

**Auth.** An API token: `Authorization: Bearer lb_…` ([create one](https://langbot.ai/app/tokens)). Signed-in web sessions work too.

**Limits.** One history query per call (500 a day on Free; unlimited on Builder and Standard).

## Parameters

### Query parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `ticker` | string | yes | The venue ticker or `pm_<id>`. |
| `period` | string | no | Seconds, or `1m`, `1h` or `1d`; default the finest stored. `periods_available` lists them. |
| `since` | integer | no | ms epoch; candles whose period ends at or after it. |
| `until` | integer | no | ms epoch; candles whose period ends at or before it. |
| `limit` | integer | no | Candles per page. 1 to 5000. Default `1000`. |

## Request

**curl**

```bash
curl "https://api.langbot.ai/v1/history/candles?ticker=SENATETX-26-R&period=1h&limit=2" \
  -H "Authorization: Bearer $LANGBOT_API_TOKEN"
```

**Python**

```python
from langbot import LangbotClient

async with LangbotClient() as lb:  # reads LANGBOT_API_TOKEN
    page = await lb.candles("SENATETX-26-R", period="1h", limit=2)
    for c in page.candles:
        print(c.ts, c.close, c.volume)
```

**TypeScript**

```ts
const res = await fetch("https://api.langbot.ai/v1/history/candles?ticker=SENATETX-26-R&period=1h&limit=2", {
  headers: { Authorization: `Bearer ${process.env.LANGBOT_API_TOKEN}` },
});
console.log(await res.json());
```

## Response

`200 OK`

```json
{
  "ticker": "SENATETX-26-R",
  "venue": "kalshi",
  "period_s": 3600,
  "periods_available": [60, 3600, 86400],
  "since": null,
  "until": null,
  "count": 2,
  "candles": [
    { "ts": 1793520000000, "open": 0.27, "high": 0.28, "low": 0.26, "close": 0.27, "volume": 18210, "open_interest": 2410000, "bid_close": 0.26, "ask_close": 0.27 },
    { "ts": 1793523600000, "open": 0.27, "high": 0.27, "low": 0.26, "close": 0.265, "volume": 9930, "open_interest": 2412000, "bid_close": 0.26, "ask_close": 0.27 }
  ],
  "next_since": 1793527200000
}
```

`ts` is the end of each period. Prices are YES probabilities (0 to 1). Pass `next_since` back as `since` for the next page (`null` on the last). `iter_candles()` in the Python SDK follows the pages for you.

## Errors

| Status | `code` | When |
|---|---|---|
| 404 | `not_found` | The market has no candles, or none at `period`. |
| 401 | `auth_required` | No token was sent. |
| 401 | `token_invalid` | The token was not recognised (mistyped, revoked or expired). |
| 422 | `validation_error` | A parameter failed validation; `detail[].loc` names it. |
| 429 | `quota_exceeded` | Today's history queries are spent; `quota.resets_at` says when they reset. |
| 429 | `rate_limited` | Over your request budget; wait `Retry-After` seconds. |

Every error body is `{"detail": …, "code": "…"}`; branch on `code`. All codes: [Errors](https://langbot.ai/docs/api#errors).