---
title: "List graded events"
method: GET
path: "/v1/events"
---

# List graded events

`GET /v1/events`

## Query parameters

- `category` 'economics' | 'financials' | 'crypto' | 'companies' | 'technology' | 'politics' | 'geopolitics' | 'health' | 'climate'
- `platform` 'kalshi' | 'polymarket'
- `grade` 'A' | 'B' | 'C'
- `q` string
- `status` 'all' | 'active' | 'resolved'
- `limit` integer
- `offset` integer

## Response `200`

Paged event list. Unknown filter values return an empty page plus a notice naming the valid set.

- object
  - `count` integer — rows in this page
  - `total` integer — full count under the active filters
  - `limit` integer
  - `offset` integer
  - `events` Event[]
    - `event_id` string, required — ClearMarket canonical event ID. Format: 'CM-EVT-' + 9-char vowel-free base36 + 1-char mod-10 check digit. Stable forever — never changes.
    - `slug` string, required — Human-readable URL form. Can change; not a stable identifier.
    - `question` string, required — ClearMarket-canonical normalized English question text.
    - `category` 'economics' | 'financials' | 'crypto' | 'companies' | 'technology' | 'health' | 'politics' | 'geopolitics' | 'climate', required — Top-level institutional classification. 9-enum (matches classify.py CATEGORIES_IN).
    - `tags` string[] — Cross-cutting filter tags (editorial + platform).
    - `primary_market_id` string, nullable — FK to markets.market_id. The market quoted as the event's headline price. Auto-computed nightly unless locked.
    - `primary_market_locked` boolean — Editorial override flag. If true, primary_market_id is not auto-recomputed.
    - `catalyst_dates` object[] — Scheduled real-world events that drive resolution or repricing, with provenance. Macro from FRED, FOMC from the Fed calendar, earnings from API Ninjas, ad-hoc from Exa.
      - `date` string, date, required
      - `type` string — Catalyst type: fomc / cpi / jobs / gdp / ppi / corporate_earnings / etc.
      - `label` string, required — Human-readable catalyst label.
      - `source_url` string — Deep link to the authoritative source for this date (provenance).
    - `published` boolean, required — API gate. If false, event is internal-only and excluded from public API responses.
    - `editorial_notes` string, nullable — Public-facing editorial context (why this event is grouped, source quality caveats, cross-platform observations). Surfaced in API responses — this is the editorial layer platforms don't ship.
    - `venue` 'kalshi' | 'polymarket' | 'null', nullable — Primary venue this event was ingested from. (Cross-venue coverage is surfaced via venues_covered at serve time.)
    - `bundle_type` 'categorical' | 'date_ladder' | 'strike_ladder' | 'augmented_negrisk' | 'singleton' | 'null', nullable — Resolution-inheritance shape of the event's child markets (OCC class->series analog). Determines which resolution fields are event-level shared vs per-child native.
    - `resolution_reference` string, nullable — Generic, subject-free event-level resolution ontology (the OCC class-level settlement rule): the data source, mechanism, and deadline that resolve ANY outcome in this event, inherited by all children. Never names a specific child's subject; per-child references are composed from this plus each child's group_item_title.
    - `created_at` string, date-time, required — Row creation timestamp (TIMESTAMPTZ).
    - `updated_at` string, date-time, required — Last update timestamp (TIMESTAMPTZ).
    - `venues_covered` string[] — DERIVED AT API SERVE TIME. Distinct platform values across all markets linked to this event.
    - `current_primary_mark` object, nullable — DERIVED AT API SERVE TIME. Latest marks row for the event's primary_market_id. Shape matches the marks schema response.
    - `field_provenance` object — Per-field provenance. Keys are field names; values are objects with 'source' ('platform_api' / 'clearmarket_editorial' / 'derived') and optional metadata.

---

[API](https://skmtc.dev/clearmarket/apis/clearmarket-api.md) · [All operations](https://skmtc.dev/clearmarket/apis/clearmarket-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/clearmarket/clearmarket-api/revisions/1fa9b0f1663c/schema)