# Historical API

Source: [Official documentation](<https://newlistings.pro/docs/v2/history>)

STARTER and PRO can request stored Full events:

```text
GET https://tokyo.newlistings.pro/v2/full
GET https://ny.newlistings.pro/v2/full
```

STARTER can query up to 30 days and PRO up to 365 days. FREE keys do not include history.

## Request

Send the same bearer key used for the WebSocket:

```bash
curl -H "authorization: Bearer YOUR_KEY" \
  "https://tokyo.newlistings.pro/v2/full?exchange=upbit,binance&market_type=spot&limit=50"
```

## Query parameters

| Parameter | Type | Notes |
| --- | --- | --- |
| `before` | integer | Exclusive upper bound in Unix epoch **milliseconds**. Defaults to the present. |
| `after` | integer | Inclusive lower bound in Unix epoch **milliseconds**. Defaults to the start of the plan's history window. |
| `limit` | integer | Maximum records per page. Defaults to `50`; maximum `100`. |
| `cursor` | string | Opaque `next_cursor` from the previous page. Omit it for the first request. |
| `exchange` | string | Up to 32 comma-separated exchange identifiers, trimmed and case-insensitive. |
| `data_type` | string | `announcement`, `tweet`, or both as a comma-separated list. |
| `market_type` | string | Comma-separated parser market types, such as `spot,futures`. |
| `category` | string | `crypto`, `rwa`, or both as a comma-separated list. Defaults to `crypto`. |
| `username` | string | One exact, case-insensitive post username. |

`before`, `after` and `limit` must be positive safe integers. If both time bounds are supplied, `after` must be less than `before`. Time bounds and plan windows apply to `detected_time_us`. Requests are restricted to the plan's history window and the present; an interval outside that window returns an empty page.

Filters follow the [Full filter rules](<https://newlistings.pro/docs/v2/filter-values>). `data_type` and `market_type` are independent and can be combined. `category` follows the stream default: without it, history returns crypto records and records that carry no category, including older records that predate the field; `category=rwa` returns real-world-asset records only. Unknown values may return no records; invalid queries return `400 INVALID_REQUEST`.

## Response

`data` contains Full events, newest first by `detected_time_us`. `next_cursor` identifies the next page, or is `null` when no more events match. An empty result is:

```json
{
  "data": [],
  "next_cursor": null
}
```

Response timestamps are epoch **microseconds**, even though request bounds are milliseconds. `sent_time_us`, when present, is the recorded publication timestamp, not the time of the HTTP response. Imported records without a recorded publication timestamp omit this field.



### How stored events differ from WebSocket events

History is not a byte-for-byte replay of WebSocket messages.

- Older records can retain earlier `parser.classification` shapes, including an absent `category` or a `markets` array for exchanges other than Upbit. Treat these fields as optional in history.
- Older records can use a storage row ID when no event ID is stored.
- Tied detection timestamps are ordered by descending storage row ID.
- Do not use IDs to join records across endpoints or regional edges.



See [Full event fields](<https://newlistings.pro/docs/v2/full#event-fields>) for the field meanings. See the [Binance Alpha Live example](<https://newlistings.pro/docs/v2/full#examples>) for a real history response.

## Cursor pagination

Pass the returned `next_cursor` as `cursor` to request the next page. Repeat the same filters and any `before` / `after` bounds. Continue until `next_cursor` is `null`.

For the request above, replace `NEXT_CURSOR` with the value from its response:

```bash
curl --get "https://tokyo.newlistings.pro/v2/full" \
  -H "authorization: Bearer YOUR_KEY" \
  --data-urlencode "exchange=upbit,binance" \
  --data-urlencode "market_type=spot" \
  --data-urlencode "limit=50" \
  --data-urlencode "cursor=NEXT_CURSOR"
```

Use the cursor unchanged. It preserves the position between records that share a timestamp; you do not need to calculate a new `before` value.

See [Limits and errors](<https://newlistings.pro/docs/v2/rate-limits#request-errors>) for HTTP errors and retry handling.