> ## Documentation Index
> Fetch the complete documentation index at: https://docs.limitless.exchange/llms.txt
> Use this file to discover all available pages before exploring further.

# Market Timeline

> Look ahead to upcoming slots of a recurring market (e.g. 5-minute crypto) before they open

Recurring markets (5-minute, hourly, daily crypto, etc.) run as a series of timed slots. `/markets/active` only ever returns the slot that is currently open, so it cannot be used to pre-fetch the next one. The timeline endpoints return the upcoming and past slots for a recurring series, including each slot's `slug` and a `tradable` flag, so you can resolve the next slug and warm up an orderbook subscription before it opens.

Both endpoints are public and require no authentication.

## By current slug

If you already have the current slug (e.g. from `/markets/active`):

* Route: `GET /markets/{slug}/timeline`
* Query: `before` (default `1`), `after` (default `24`) — number of slots to return on each side of the anchor.

```bash theme={null}
curl "https://api.limitless.exchange/markets/btc-up-or-down-5-min-1771934700/timeline?before=1&after=24"
```

## By symbol and frequency

If you do not have a current slug, anchor on the recurring series directly:

* Route: `GET /markets/timeline`

| Query param    | Type     | Required                           | Description                                           |
| -------------- | -------- | ---------------------------------- | ----------------------------------------------------- |
| `symbol`       | `string` | Yes                                | Underlying symbol, e.g. `BTC`.                        |
| `frequency`    | `string` | Yes                                | One of `minutely`, `hourly`, `daily`, `weekly`.       |
| `subFrequency` | `string` | Required for `minutely` / `hourly` | Slot size, e.g. `minutes_5`, `minutes_15`, `hours_1`. |
| `before`       | `number` | No                                 | Past slots to return (default `10`, max `500`).       |
| `after`        | `number` | No                                 | Future slots to return (default `10`, max `500`).     |

```bash theme={null}
# Upcoming 5-minute BTC slots
curl "https://api.limitless.exchange/markets/timeline?symbol=BTC&frequency=minutely&subFrequency=minutes_5&before=2&after=10"
```

## Response

```json theme={null}
{
  "current": {
    "slotId": 4821,
    "slug": "btc-up-or-down-5-min-1771934700",
    "state": "OPEN",
    "tradable": true,
    "startAt": "2026-05-28T12:05:00.000Z",
    "endAt": "2026-05-28T12:10:00.000Z",
    "countdownSec": 142
  },
  "next": {
    "slotId": 4822,
    "slug": "btc-up-or-down-5-min-1771935000",
    "state": "PRE_OPEN",
    "tradable": false,
    "startAt": "2026-05-28T12:10:00.000Z",
    "endAt": "2026-05-28T12:15:00.000Z",
    "countdownSec": 442
  },
  "batch": [
    {
      "slotId": 4822,
      "index": 1,
      "slug": "btc-up-or-down-5-min-1771935000",
      "state": "PRE_OPEN",
      "tradable": false,
      "startAt": "2026-05-28T12:10:00.000Z",
      "endAt": "2026-05-28T12:15:00.000Z"
    }
  ]
}
```

### Slot fields

| Field               | Type      | Description                                                                             |
| ------------------- | --------- | --------------------------------------------------------------------------------------- |
| `slug`              | `string`  | Market slug for this slot. Use it to fetch the orderbook or place orders once tradable. |
| `state`             | `string`  | `PRE_OPEN`, `OPEN`, `SETTLING`, `SETTLED`, or `FAILED`.                                 |
| `tradable`          | `boolean` | Whether orders are currently accepted for this slot.                                    |
| `startAt` / `endAt` | `string`  | ISO 8601 slot window bounds.                                                            |
| `countdownSec`      | `number`  | Seconds to the next boundary (`current` / `next` only).                                 |
| `index`             | `number`  | Slot offset from the anchor (`batch` only).                                             |

The `GET /markets/{slug}/timeline` variant additionally returns `anchor` and `job` metadata describing the recurring series.

<Note>
  A slot can exist in `PRE_OPEN` before orders are accepted. Gate order submission on `tradable: true` / `state: "OPEN"` rather than on `startAt` alone.
</Note>

## Pre-fetch pattern

1. Poll the timeline a few seconds before the current slot ends.
2. Read `next.slug` and open its orderbook subscription early.
3. Submit the moment `next` flips to `state: "OPEN"` / `tradable: true`.

Responses are cached for a few seconds, so polling once per second per series is safe.