events

Get events (keyset)

Get active, non-archived events with keyset pagination.

get/events/keyset

Request

  • Base URL: https://gamma-api.polymarket.com (the document declares no server; this is the origin it was published from)
  • URL: https://gamma-api.polymarket.com/events/keyset
  • Auth: none declared

Query parameters

idinteger[] nullable

Event IDs to return

slugstring[] nullable

Event slugs to return

closedstring

Filter by closed flag (true/false)

livestring

Filter by live flag (true/false)

liquidity_minstring

Minimum liquidity

liquidity_maxstring

Maximum liquidity

volume_minstring

Minimum volume

volume_maxstring

Maximum volume

start_date_minstring

Minimum start date (RFC3339 or YYYY-MM-DD)

start_date_maxstring

Maximum start date (RFC3339 or YYYY-MM-DD)

end_date_minstring

Minimum end date (RFC3339 or YYYY-MM-DD)

end_date_maxstring

Maximum end date (RFC3339 or YYYY-MM-DD)

tag_idinteger[] nullable

Tag IDs to filter by

related_tagsstring

Include events from related tags (true/false)

tag_matchstring

Tag match mode

tag_slugstring

Filter by tag slug

featuredstring

Filter by featured flag (true/false)

cyomstring

Filter by CYOM flag (true/false)

series_idinteger[] nullable

Series IDs to filter by

series_slugstring[] nullable

Filter by series slug

game_idinteger[] nullable

Game IDs to filter by

us_idstring[] nullable

US event IDs to filter by

event_datestring

Filter by event date (RFC3339 or YYYY-MM-DD)

event_weekstring

Filter by event week

start_time_minstring

Minimum start time (RFC3339)

start_time_maxstring

Maximum start time (RFC3339)

exclude_tag_idinteger[] nullable

Tag IDs to exclude

featured_orderstring

Order by featured when true (true/false)

recurrence'daily' | 'weekly' | 'monthly' | 'annual' | 'hourly'

Recurrence filter

created_bystring[] nullable

Filter by creator

parent_event_idinteger[] nullable

Parent event IDs to filter by

include_childrenstring

Include the children of the matched parent_event_id or slug (true/false)

title_searchstring

Case-insensitive title search

include_best_linesstring

Include best lines (true/false)

include_marketsstring

Include each event's markets array (true/false, default true). false skips loading markets, so the response carries the event rows without a markets key

localestring

Locale code

partner_slugstring

Filter by external partner slug

event_metadata_keystring

Filter by event metadata key

event_metadata_valuestring

Filter by event metadata value

context_requires_regenstring

Return only events flagged for context regeneration when true; false has no effect

context_missingstring

Return only events with no generated context when true; false has no effect

combo_statusstring

Filter by combo status (pending/enabled/disabled). Returns events with at least one market in that status, counting markets owned by their child events, and narrows each event's markets array to that status.

versionstring[] nullable

Protocol versions to return (v1 or v2). Repeat the parameter for several. Omitted means the server default (v1 while polymarket-v2 is in its builder integration period)

limitinteger

Max results returned

offsetinteger

Number of results to skip

orderstring

Comma-separated field names to sort by

ascendingboolean

Sort ascending when true (default true)

after_cursorstring

Opaque keyset pagination cursor from a previous response

market_projection'full' | 'status' | 'card'

Market fields to load. full preserves the default response. status keeps every visible market in the same order, with only id, conditionId, marketMakerAddress, feeType, sportsMarketType, closed and gameStartTime; skips market enrichment and translation. Event fields, filters and ordering are unchanged. status allows up to 500 candidates and returns event_cursors for resuming after each row; full keeps its 100-row cap. card keeps all visible markets with card identity, quotes, lifecycle and selection fields, plus rewards and fee enrichment and market translations; its cap is 100 and it omits event_cursors. Requires include_markets=true (the default).

Response

The market_projection query parameter selects the response contract; no response header is needed. Omitted or full preserves the existing Market response and 100-event limit. With status, each market selects only id, conditionId, marketMakerAddress, feeType, sportsMarketType, closed and gameStartTime. The first four properties are required; feeType remains nullable. The other three properties are optional and omitted when unset. Every unselected Market property is optional in the schema. Consumers must tolerate additional optional properties. Status preserves visible markets and their order, skips market enrichment and translation, and accepts up to 500 events. Its event_cursors contains one signed continuation per event, in event order, and is omitted for an empty page. Each row cursor can resume a full, status or card read. Event fields, filters and ordering are unchanged. Card preserves all visible market rows and their order, loading only identity, quote, lifecycle and card-selection columns. It retains market translations, clobRewards and feeSchedule enrichment, keeps the 100-event cap and omits event_cursors. Card fields: id, conditionId, marketMakerAddress, feeType, feesEnabled, question, slug, image, icon, groupItemTitle, outcomes, outcomePrices, clobTokenIds, positionIds, comboStatus, sportsMarketType, line, gameStartTime, active, closed, archived, acceptingOrders, umaResolutionStatus, bestBid, bestAsk, spread, orderPriceMinTickSize, lastTradePrice, oneDayPriceChange, liquidity, volume, rewardsMinSize, rewardsMaxSpread, holdingRewardsEnabled, clobRewards and feeSchedule.

$schemastring uri

A URL to the JSON Schema for this object.

event_cursorsstring[] nullable

Status projection only: one signed continuation cursor per event, in event order. Clients can resume after a partially consumed batch.

next_cursorstring

Example response

{
  "$schema": "https://example.com/schemas/EventsKeysetListResponse.json",
  "events": [
    {
      "$schema": "https://example.com/schemas/Event.json",
      "eventCreators": [
        {
          "$schema": "https://example.com/schemas/EventCreator.json"
        }
      ],
      "externalPartners": [
        {
          "$schema": "https://example.com/schemas/EventExternalPartnerMapping.json",
          "partner": {
            "$schema": "https://example.com/schemas/Partner.json"
          }
        }
      ],
      "markets": [
        {
          "$schema": "https://example.com/schemas/Market.json",
          "cryptoMarketConfig": {
            "$schema": "https://example.com/schemas/CryptoMarketConfig.json"
          },
          "tags": [
            {
              "$schema": "https://example.com/schemas/Tag.json"
            }
          ]
        }
      ],
      "series": [
        {
          "$schema": "https://example.com/schemas/Series.json"
        }
      ],
      "sport": {
        "$schema": "https://example.com/schemas/SportsMetadata.json",
        "externalPartners": [
          {
            "$schema": "https://example.com/schemas/SportExternalPartnerMapping.json",
            "partner": {
              "$schema": "https://example.com/schemas/Partner.json"
            }
          }
        ]
      },
      "tags": [
        {
          "$schema": "https://example.com/schemas/Tag.json"
        }
      ],
      "teams": [
        {
          "$schema": "https://example.com/schemas/Team.json",
          "externalPartners": [
            {
              "$schema": "https://example.com/schemas/TeamExternalPartnerMapping.json",
              "partner": {
                "$schema": "https://example.com/schemas/Partner.json"
              }
            }
          ]
        }
      ]
    }
  ]
}

Changes

No recorded changes to this operation across all 1 revision of this API.