> ## Documentation Index > Fetch the complete documentation index at: https://docs.rook.pm/llms.txt > Use this file to discover all available pages before exploring further. # List events > Find the venue events that contain markets you want to inspect. Browse by keyword, venue, category or family; for an exact native lookup, supply venue and venue_event_id. For example, venue=polymarket&venue_event_id=900001 looks up a numeric Polymarket event ID. Use event_id instead when you already have its Rook ID. Each item returns the Rook event_id, venue, original venue_event_id, source title, market_ids and family_ids. Events preserve the venue's grouping: Rook never merges related venue events or creates an event from analytically related markets. A family can connect several events without changing them. The response always uses items; an exact lookup returns zero or one event. Follow market_ids to /markets, or family_ids to /families to discover the broader group across events. Other filters narrow results, and pagination preserves the search snapshot. See the [integration guide](/guides/market-identity) for the workflow and interpretation of this response. ## Examples ```http Browse events theme={null} GET /v1/events ``` ```http Get one event theme={null} GET /v1/events?event_id=evt_pm_900001 ``` ```http Search by words theme={null} GET /v1/events?q=Fed%20rate%20cut&page_size=5 ``` ```http Filter results theme={null} GET /v1/events?category=rates&page_size=20 ``` The response always contains `items`, `next_page_token`, `snapshot_id` and `as_of`. An ID lookup returns zero or one item with its full details. No match returns an empty `items` array. Use `q` to search titles, descriptions and tags by words. Results are ordered by relevance. `page_size` sets the maximum results per page; use `next_page_token` to continue. Other filters, such as `category` or `venue`, narrow the search. ```http Look up a Polymarket event theme={null} GET /v1/events?venue=polymarket&venue_event_id=900001 ``` Supply the venue together with its original numeric ID. The result returns the Rook ID and `family_ids`. Native IDs use exact decimal text in JSON. Do not combine native and Rook ID selectors. ## OpenAPI ````yaml GET /events openapi: 3.1.0 info: title: Rook API version: 0.1.0-design description: Markets, settlement relationships, scenarios, payouts and market data. servers: - url: https://api.rook.pm/v1 description: Proposed API origin; not an assertion these operations are callable. security: - ApiKeyBearer: [] tags: - name: Reference data description: Events, unified markets and native-ID resolution. - name: Families and scenarios description: Family scope and versioned scenario columns. - name: Relationships and Combos description: Related-market discovery, selected-set inference and Combo interpretation. - name: Payouts and exposure description: Scoped per-unit payouts and stateless portfolio/candidate calculations. - name: Market data description: Current prices, history, L2 books, prints, statistics and published fees. - name: Fair values description: Future private customer estimates; not Rook forecasts. - name: Coverage and updates description: Supported capabilities and incremental semantic changes. paths: /events: get: tags: - Reference data summary: List events description: >- Find the venue events that contain markets you want to inspect. Browse by keyword, venue, category or family; for an exact native lookup, supply venue and venue_event_id. For example, venue=polymarket&venue_event_id=900001 looks up a numeric Polymarket event ID. Use event_id instead when you already have its Rook ID. Each item returns the Rook event_id, venue, original venue_event_id, source title, market_ids and family_ids. Events preserve the venue's grouping: Rook never merges related venue events or creates an event from analytically related markets. A family can connect several events without changing them. The response always uses items; an exact lookup returns zero or one event. Follow market_ids to /markets, or family_ids to /families to discover the broader group across events. Other filters narrow results, and pagination preserves the search snapshot. operationId: listEvents parameters: - name: event_id in: query required: false description: >- Rook ID for one original venue event. Its identity is scoped to venue and venue_event_id; related events remain separate. Omit to browse. Exact lookup retains the items envelope. schema: type: string minLength: 1 example: evt_pm_900001 - name: venue_event_id in: query required: false description: >- Original venue event ID. For Polymarket this is its numeric Gamma event ID, encoded as decimal text. It is not a market ID. schema: type: string minLength: 1 example: '900001' - name: family_id in: query required: false description: >- Rook family ID connecting related markets across original venue events. Omit to browse. Exact lookup retains the items envelope. schema: type: string minLength: 1 example: fam_fed_dec_2026 - name: q in: query required: false description: >- Search titles, descriptions and tags by words, ignoring letter case. Results are ordered by relevance with stable ID tie-breaking. Other filters narrow the matches. schema: type: string minLength: 1 example: Fed rate cut - name: category in: query required: false description: >- Exact category label used by the catalog, for example rates. Narrows search results. schema: type: string - name: venue in: query required: false description: >- Venue identifier, such as polymarket or kalshi. Required when looking up a venue-native ID; never inferred from the ID. schema: type: string example: polymarket - name: status in: query required: false description: >- Filter by the resource lifecycle status. This does not indicate analytical coverage or feed freshness. schema: type: string enum: - OPEN - CLOSED - RESOLVED - UNKNOWN - name: page_size in: query required: false description: >- Requested maximum items; service caps disclosed by coverage. Oversize requests fail explicitly. schema: type: integer minimum: 1 default: 50 - name: page_token in: query required: false description: >- Opaque continuation; reuse the same filters/order. Cursor pins the original snapshot. schema: type: string - name: X-Client-Request-Id in: header required: false schema: type: string description: Caller correlation reference; not an idempotency guarantee. responses: '200': description: Success. content: application/json: schema: $ref: '#/components/schemas/ListEventsResponse' example: items: - event_id: evt_pm_900001 title: Fed rate cut — December 2026 description: >- Illustrative source event containing the cut market. The related hold market belongs to another original venue event. category: rates status: OPEN market_ids: - mkt_fed_dec_2026_cut family_ids: - fam_fed_dec_2026 observed_at: '2026-10-19T12:00:00Z' venue: polymarket venue_event_id: '900001' next_page_token: null snapshot_id: snap_rates_20261019_120000 as_of: '2026-10-19T12:00:00Z' headers: X-Request-Id: description: Server request trace ID. schema: type: string description: Opaque text identifier. Preserve its exact value. minLength: 1 components: schemas: ListEventsResponse: type: object properties: items: type: array items: $ref: '#/components/schemas/Event' next_page_token: anyOf: - type: string - type: 'null' snapshot_id: type: string description: Opaque text identifier. Preserve its exact value. minLength: 1 as_of: type: string format: date-time required: - items - next_page_token - snapshot_id - as_of additionalProperties: true Event: type: object properties: event_id: type: string description: >- Rook ID for one original venue event. Its identity is scoped to venue and venue_event_id; related events remain separate. minLength: 1 title: type: string description: type: string category: anyOf: - type: string - type: 'null' description: >- Exact category label used by the catalog, for example rates. Narrows search results. status: type: string enum: - OPEN - CLOSED - RESOLVED - UNKNOWN description: >- Filter by the resource lifecycle status. This does not indicate analytical coverage or feed freshness. market_ids: type: array items: type: string description: Opaque text identifier. Preserve its exact value. minLength: 1 description: >- Rook market IDs in this resource. On an event these reflect its source venue membership; on a family they identify the related market members. family_ids: type: array items: type: string description: Opaque text identifier. Preserve its exact value. minLength: 1 description: >- Rook family memberships for this resource, or family IDs to scope a change feed. Preserve all returned memberships. starts_at: anyOf: - type: string format: date-time - type: 'null' expected_settlement_at: anyOf: - type: string format: date-time - type: 'null' observed_at: type: string format: date-time venue: type: string minLength: 1 description: >- Venue identifier, such as polymarket or kalshi. Required when looking up a venue-native ID; never inferred from the ID. example: polymarket venue_event_id: type: string minLength: 1 description: >- Original venue event ID. For Polymarket this is its numeric Gamma event ID, encoded as decimal text. It is not a market ID. example: '900001' required: - event_id - title - status - market_ids - family_ids - observed_at - venue - venue_event_id additionalProperties: true description: >- One original venue event, wrapped with a Rook ID and family references. The pair (venue, venue_event_id) defines source identity. Rook preserves the source title and market grouping; it never synthesizes or merges events to represent related markets. allOf: - if: properties: venue: const: polymarket required: - venue then: properties: venue_event_id: pattern: ^[0-9]+$ securitySchemes: ApiKeyBearer: type: http scheme: bearer description: >- Proposed server-to-server API key. No client request HMAC signing scheme is specified. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.