Sign in
Home | API Docs
GET

/v1/backtest

v1

Replay historical WebSocket events

Replay historical WebSocket events for backtesting trading strategies and news analysis pipelines. Returns events in chronological order with cursor-based pagination. Mirrors the WebSocket subscribe filter system — filter by topics, categories, sources, keywords, and entities. Requires **Pro tier or higher**. Use `topics` to select event classes: `"articles"` maps to `item.new` and `item.enriched` events; `"stories"` maps to `story.development`, `story.priority_changed`, and `cluster.event`. The `clusters.ranked` event type is excluded by default and must be explicitly listed in `types` to include. Events are retained for 90 days. Each request can span at most 7 days (`to - from`).

Parameters

from required integer (int64)
query

Start of time range (Unix milliseconds). Must be within the last 90 days.

e.g. 1740000000000

to required integer (int64)
query

End of time range (Unix milliseconds). Max 7-day window from `from`.

e.g. 1740604800000

topics string
query

Comma-separated topic classes: `articles`, `stories`. Maps to underlying event types.

e.g. articles,stories

types string
query

Comma-separated event types (overrides `topics`): `item.new`, `item.enriched`, `story.development`, `story.priority_changed`, `cluster.event`, `clusters.ranked`.

e.g. item.new,item.enriched

categories string
query

Comma-separated category filter (OR logic)

e.g. politics,business

sources string
query

Comma-separated source ID filter (OR logic)

e.g. reuters,ap-news

keywords string
query

Comma-separated keyword filter — matches against article titles (OR logic, case-insensitive)

e.g. climate,carbon

entities string
query

Comma-separated entity IDs to filter by (matches `item.enriched` events)

e.g. 42,108

cluster_id integer (int64)
query

Filter by a specific story cluster ID

e.g. 1523

include_embeddings boolean
query

Attach embedding vectors to article events in the response

Default: false

cursor integer (int64)
query

Pagination cursor — pass `next_cursor` from the previous response

Default: 0

e.g. 0

limit integer
query

Events per page (max 5000)

Default: 1000

e.g. 1000

Request Examples

bash 
curl "https://api.newsrank.ai/v1/backtest?from=1740000000000&to=1740604800000&topics=articles%2Cstories&types=item.new%2Citem.enriched&categories=politics%2Cbusiness&sources=reuters%2Cap-news&keywords=climate%2Ccarbon&entities=42%2C108&cluster_id=1523&cursor=0&limit=1000" \
  -H "Authorization: Bearer nrf_your_api_key"

Response

json 
{
  "ok": true,
  "events": [
    {
      "id": 12345,
      "ts": 1740000000000,
      "event_type": "item.new",
      "cluster_id": 1523,
      "payload": null,
      "similarity": 0.82,
      "embedding": []
    }
  ],
  "next_cursor": 12399,
  "has_more": true,
  "meta": {
    "from": 1740000000000,
    "to": 1740604800000,
    "topics": [
      "articles"
    ],
    "filters_applied": null,
    "event_count": 1000
  }
}

Try it

Server

Using sandbox demo key (5 req/min) — no signup required

Authentication
Demo key (sandbox)
Endpoint
GET /v1/backtest
Default: false
Default: 0
Default: 1000