Skip to main content
GET
/
v1
/
events
List events with their markets (event-first shape).
curl --request GET \
  --url https://api.polysimulator.com/v1/events \
  --header 'X-API-Key: <api-key>'
{
  "events": [
    {}
  ],
  "total": 123,
  "limit": 123,
  "offset": 123,
  "cache_source": "<string>",
  "has_sports": true,
  "message": "<string>"
}

Authorizations

​
X-API-Key
string
header
required

Issue from /v1/keys (or admin-issued for enterprise tier).

Headers

​
X-API-Key
string | null

Your PolySimulator API key

​
POLY_API_KEY
string | null

Polymarket-CLOB-compat alias for X-API-Key (underscore form). SDK clients ported from Polymarket can authenticate without changing header names. X-API-Key takes precedence when both are provided.

​
Poly-API-Key
string | null

PM-CLOB-compat dashed-form alias for X-API-Key. Same value semantics as POLY_API_KEY but with HTTP-conventional dash separators. Audit P1 (staging audit 2026-05-16 0817 PR #1296): the per-tier middleware accepts both spellings but the auth dependency originally only matched the underscore form — now both work end-to-end.

​
authorization
string | null

PM-CLOB-compat: Authorization: Bearer ps_live_... (or ps_test_...) is accepted as an alias for X-API-Key so py-clob-client and other ported SDKs authenticate without header name changes. Bearer JWTs are NOT accepted here — use the dashboard-auth endpoints for those.

Query Parameters

​
limit
integer
default:50
Required range: 1 <= x <= 200
​
offset
integer
default:0
Required range: x >= 0
​
hot_only
boolean
default:false

Only show high-volume events.

​
markets_per_event
integer
default:20

Cap on child markets returned per event. The poller stores all child markets per event in Redis; this trims the per-event payload at response time for callers that only need the top-N markets.

Required range: 1 <= x <= 100
​
category
string | null

Filter to a single category slug (e.g. crypto, sports, politics). Case-insensitive substring match against the event's classified category. Categories are populated by the background poller (~5 min cadence) from the event's tags via classify_event. Use unquoted values: ?category=crypto — leading/trailing single or double quotes are stripped defensively for users pasting from Postman.

Maximum string length: 50
​
search
string | null

Free-text search over event titles + market questions. Case-insensitive substring match with no operator support.

Maximum string length: 120
​
include_sports
boolean
default:true

When false, suppress sports events from the response. Defaults to true for back-compat with the legacy /events endpoint.

Response

Successful Response

Envelope returned by GET /v1/events.

Per-event payloads are typed as Dict[str, Any] deliberately: the legacy app.main.list_events returns a heterogeneous event dict whose fields evolve with the poller (markets, enriched prices, classified category, weather_category, ...). Modelling the envelope alone is enough to move the OpenAPI output off "schema": {}; SDK consumers consult the docs for per-event fields.

​
events
Events · object[]
required

Events on this page (one dict per parent event, with capped child markets).

​
total
integer
required

Total event count matching the filter (across all pages).

​
limit
integer
required

Echo of the requested limit.

​
offset
integer
required

Echo of the requested offset.

​
cache_source
string
required

Internal cache tier (e.g. homepage_prebuilt, redisearch_all, empty).

​
has_sports
boolean | null

True when sports events were filtered out (include_sports=false path).

​
message
string | null

Set on 503 (cache warming) and other operational states; absent on success.