Agent-readable docs index: /llms.txt. Full docs in one file: /llms-full.txt. Download /docs.zip to grep all markdown files locally.
/api/v1/eventsGET
List all events, filterable by category, region, venue, and scope. Pass embed=markets to include each event's child markets on the list row. expires_after / expires_before are markets-only and return 400. Combining search with the deprecated election-date start / end returns 400.
Authorization
bearerAuth *Bearer <token>
Session token from the app, or an API key (the ak_ prefix), sent as a Bearer token or an ?api_key= query parameter.. Token in: header
Query Parameters
scope?"constituents" | "all"
constituents keeps events that have at least one market in a public index. all or absent returns every event.
embed?"markets"
markets includes each event's child markets on the list row, the same shape as a markets-list row. When scope=constituents, only constituent children are included.
category?string
Filter by category
region?string
Filter by region: a two-letter US state code for a state-level race, or US for a federal one.
search?string
Case-insensitive word match over an event's member markets (question, description, series title, market ID, and market slug) plus the event name and ID.
venue?string
Filter by venue: a comma-separated list of platforms (kalshi, polymarket, gemini). Keeps events with at least one market on a listed venue. platform is an accepted alias.
platform?string
Alias for venue.
expires_before?string
Not accepted on events. Returns 400. Date windows apply to markets only.
expires_after?string
Not accepted on events. Returns 400. Date windows apply to markets only.
created_since?string
Filters events first listed on this platform at or after this ISO date or datetime.
created_until?string
Filters events first listed on this platform at or before this ISO date or datetime.
start?string (date-time)
Deprecated.
end?string (date-time)
Deprecated.
sort?"created" | "election_date" | "title" | "volume" | "open_interest" | "market_count"
Sort key.
Default: "created"
sort_dir?"asc" | "desc"
Sort direction, asc or desc (default desc).
Default: "desc"
page?integer
Default: 1
per_page?integer
Default: 100Max: 500
Response
200 · List of events
data?object[]
Show item properties
event_id?string
Stable identifier for the event, formed as <venue>:<venue event ticker> (for example kalshi:KXPRESPARTY-2028). Use it to fetch the event's detail and to group markets by their parent event.
name?string
The event's title as published by its venue, intended for display.
category?string
The event's category, folded into a fixed cross-venue taxonomy (Politics, Elections, Economics, Crypto, Sports and similar, with Other as the catch-all). Every market under the event inherits this value.
region?stringnull
Geographic scope of the event: a two-letter US state code for state-level races, or US for federal ones. Null whenever the event carries no geographic anchor, which covers non-election events and all Polymarket events.
election_date?string,null (date)
The election day this event resolves against, derived from the event's identifier for election markets and null for everything else. Pass sort=election_date to order the events list by it (undated events last).
description?stringnull
Longer description of the event as published by its venue. Omitted when the venue supplies none.
created_at?string,null (date-time)
When this event was first recorded by the API. It is a first-seen timestamp on our side, not a venue publication date.
updated_at?string,null (date-time)
When this event's record was last written. The record is rewritten every time the event is re-read from its venue, so this advances even when no field actually changed.
market_count?integer
Number of child markets under this event within the requested scope. Settled and closed markets are included.
volume?numbernull
Summed all-time contract/share volume across the event's markets, not dollars. Unit is in volume_unit. Omitted when no market reports volume.
volume_unit?object | null
Wire unit for volume, from the event's venue (every market shares the event's venue). See QuantityUnit.
open_interest?numbernull
Summed open interest across the event's markets. Unit is in open_interest_unit. Omitted when no market reports open interest.
open_interest_unit?object | null
Wire unit for open_interest, from the event's venue. See QuantityUnit.
markets?object[]
Child markets of this event, each the same shape as a markets-list row. Present only when the request includes embed=markets.
Show item properties
market_id?string
Canonical identifier for the market, formed as <platform>:<venue ticker> (for example kalshi:SENATEPA-26-R). This is the id every other endpoint accepts, so use it rather than ticker when looking a market up.
ticker?string
The venue's own symbol for the market, without the <platform>: prefix. Not guaranteed unique across venues, so use market_id as the lookup key and display_ticker as the human-readable label.
display_ticker?string
Human-readable market label, Polymarket market slug when present, else the raw ticker.
platform?string
The venue that lists this market: kalshi, polymarket, polymarket-us, or gemini. It is also the prefix of market_id, and it determines what the volume and open interest figures are counted in (see the companion volume_unit, volume_24h_unit, and open_interest_unit fields).
question?string
The market's question, worded as the venue words it. When a venue supplies no title we fall back to the raw ticker, so this is never empty.
probability?numbernull
Implied yes-side probability on the 0-100 scale, where 48.5 means 48.5 percent. This is the market's latest traded price.
volume?numbernull
All-time traded volume as a contract/share count (Kalshi contracts, Polymarket shares), not dollars. Unit is in volume_unit.
volume_unit?object | null
Wire unit for volume. See QuantityUnit.
volume_24h?numbernull
Trailing 24h volume. Platform-native: Kalshi and Gemini contracts, Polymarket shares. Unit is in volume_24h_unit.
volume_24h_unit?object | null
Wire unit for volume_24h. See QuantityUnit.
open_interest?numbernull
Open interest: a Kalshi contract count; Polymarket's is USD. Unit is in open_interest_unit.
open_interest_unit?object | null
Wire unit for open_interest. See QuantityUnit.
status?string
Lifecycle state of the market: pending (listed, open_time still in the future), active (trading), closed (trading has ended, outcome not yet published), resolved (settled with a known outcome), expired (ended long ago and never settled by the venue), or unknown (the venue reported no status we recognize).
category?stringnull
Topic category of this market's parent event, normalized across venues (for example Politics, Sports, Crypto). Every market under the same event shares it.
is_constituent?boolean
True when the market is a constituent of at least one index. The public markets list exposes every tracked market; default to constituents by filtering on this flag.
indices?string[]
Index ids this market is a constituent of, ascending. Omitted when the market is in no index. Populated only on the authenticated /api/v1/markets list.
end_date?string,null (date-time)
When trading closes on the venue. This is not the settlement time; a market can sit in closed for a while before its outcome is published.
created_at?string (date-time)
When we first recorded this market, not when the venue listed it. Only the authenticated markets list returns it; the public markets list omits it.
updated_at?string (date-time)
When any stored field on this market last changed on our side, so it also moves on routine metadata refreshes and is not a price-move timestamp. Only the authenticated markets list returns it; the public markets list omits it.
link?stringnull
URL of the venue's public page for this contract. Kalshi is the parent event page. Polymarket is /event/<event-slug>/<market-slug> when both slugs exist and differ, /event/<event-slug> when only the event slug is usable, and /market/<market-slug> when only the market slug is usable. Gemini is /predictions/<eventTicker>/<slug>. Null when no working URL can be built.
state_code?stringnull
Two-letter US state code when the contract is tied to a state race. Absent for national contests and for markets with no state on record.
city_code?stringnull
Mayoral city code parsed at ingest; present for Mayoral markets, absent otherwise.
is_constituent?boolean
True when any returned child market belongs to a public index. Omitted when false.
meta?object
Show properties
total?integernull
Total number of records matching the request across every page, not just the current one. null on an uncounted list; page using has_next. A relevance-ranked search is uncounted, and a searched events list stays uncounted even with sort. A searched markets list with sort returns a total over the ranked matches (at most 10,000).
page?integer
The 1-based page number this response covers.
per_page?integer
Maximum number of items on a page. The last page may hold fewer.
total_pages?integernull
Total number of pages available at the current per_page. null whenever total is null; page using has_next.
has_next?boolean
True when a page exists after this one.
has_prev?boolean
True when this is not the first page.
total_capped?boolean
True when total and total_pages reflect the server's counting ceiling rather than the exact matched count: the real set is at least total large. Render such totals as a lower bound (for example "10,000+"). Omitted when the count is exact. A sorted markets search that fills the 10,000-candidate ceiling sets this flag.
400 · Invalid filter combination. Events reject expiry windows, and reject `search` combined with election-date `start` / `end`.
error?string
Stable, machine-readable code identifying the failure; branch on this rather than on message. One of bad_request, unauthorized, forbidden, not_found, conflict, service_unavailable, upstream_error, service_error, or internal_error.
message?string
Human-readable explanation, safe to show to a user. For client errors it names the specific problem; for server-side failures it is a generic notice and the underlying detail is deliberately withheld.
403 · The organization has no paid plan, so the realtime read scopes are refused. Distinct from a 429, which means a plan's budget ran out: nothing here resets on a timer, and the request succeeds only once the organization holds a plan.
error *string
Human-readable reason the request was refused.
status *integer
HTTP status code, repeated in the body.
upgrade_url?string (uri)
Page listing the plans and their request allowances, for buying access. Absent when no plan is available for purchase.
429 · The organization's minute or UTC-day request budget is exhausted, or the organization has reached its cap on requests running at the same time (`limit: "concurrency"`). Wait `Retry-After` seconds before retrying; for a concurrency 429, reduce parallelism.
error *"rate_limited"
Always rate_limited. Branch on this to detect a throttled request.
limit *"rpm" | "daily" | "concurrency"
Which limit was hit: rpm for the per-minute cap, daily for the daily one, or concurrency for the cap on requests running at the same time.
message *string
Human-readable explanation naming the limit that was exceeded.
upgrade_url?string (uri)
Page listing the plans and their request allowances, for buying a larger budget. Absent when no plan is available for purchase.
503 · The catalog is rebuilding. Retry in a few seconds.
error?string
Stable, machine-readable code identifying the failure; branch on this rather than on message. One of bad_request, unauthorized, forbidden, not_found, conflict, service_unavailable, upstream_error, service_error, or internal_error.
message?string
Human-readable explanation, safe to show to a user. For client errors it names the specific problem; for server-side failures it is a generic notice and the underlying detail is deliberately withheld.
Request example
curl -X GET "https://api.dev.adjacent.markets/api/v1/events" \
  -H "Authorization: Bearer <token>"
Response example
{
  "data": [
    {
      "event_id": "kalshi:CONTROLH-2028",
      "name": "2028 House winner",
      "category": "Elections",
      "region": "US",
      "election_date": "2028-11-07",
      "description": "In 2028",
      "created_at": "2026-06-02T16:28:27.350946Z",
      "updated_at": "2026-06-02T16:29:39.257577Z",
      "market_count": 2
    },
    {
      "event_id": "kalshi:CONTROLS-2028",
      "name": "2028 Senate winner",
      "category": "Elections",
      "region": "US",
      "election_date": "2028-11-07",
      "description": "In 2028",
      "created_at": "2026-06-02T16:28:24.146031Z",
      "updated_at": "2026-06-02T16:29:34.765363Z",
      "market_count": 2
    }
  ],
  "meta": {
    "total": 204963,
    "page": 1,
    "per_page": 20,
    "total_pages": 10249,
    "has_next": true,
    "has_prev": false
  }
}
Adjacent API
Powered byHolocron