--- title: "Retrieve events that are available on Smarkets to bet on." method: GET path: "/v3/events/" tags: ["events"] --- # Retrieve events that are available on Smarkets to bet on. `GET /v3/events/` ## Description Events in Smarkets follow a tree structure per sport, where events can have several child events, but only one parent event.
As an example for football, we have:

In the case of most sports, we have 3 levels in the tree. However, there are cases where we can have a different number.

To identify whether an event is a leaf node in this tree, one can look at the bettable flag.

Only leaf events can have markets, which in turn will have contracts.

## Query parameters - `id` string[] — Event IDs to filter by - `inplay_enabled` boolean — True if trading will be open when the markets go live in-play - `state` string[] — Event states to filter by - `type` string[] — Event types to filter by - `type_domain` string[] — Allows filtering by 'domains' - a feature of the new, improved typing system for events.
The domain of an event denotes the category of events this event belongs to. In most cases this will be the sport (football, tennis, golf, etc) but for non-sports the domain could be politics, tv_and_entertainment, to mention some examples. If you want to use this, you might also want to opt into the new typing system (see `with_new_type`). - `type_scope` string[] — Allows filtering by 'scopes' - a feature of the new, improved typing system for events.
The scope of an event denotes the kind of event you want, potential values include single_event (your typical football match, horse race, political event), outright (an event who's outcome spans multiple events), acca (an accumulator), etc.
If you want to use this, you might also want to opt into the new typing system (see `with_new_type`). - `with_new_type` boolean — Enables a new, improved typing system for events.
If this flag is set to true, the format of the type field in the event response will change.
Users of the API are urged to make use of the new typing system, as the old typing system will be deprecated in the next version of the API. - `parent_id` string[] — Filter by events with these parent IDs - `start_datetime_min` string, date-time — When the event is scheduled to go live - `start_datetime_max` string, date-time — When the event is scheduled to go live - `last_modified_min` string, date-time — The timestamp when any of the properties of the event was last modified - `last_modified_max` string, date-time — The timestamp when any of the properties of the event was last modified - `pagination_last_display_order` integer — Display order for the last event of the previous page.
This parameter should be used in conjunction with sorting by display_order,... - `pagination_last_start_datetime` string, date-time — Start datetime for the last event of the previous page.
This parameter should be used in conjunction with sorting by start_datetime - `pagination_last_id` string — The last event id from the previous page, so we can retrieve the subsequent events.
This should be used in conjunction with sorting by id - `pagination_last_name` string — The name of the last event from the previous page, so we can retrieve the subsequent events.
This should be used in conjunction with sorting by name - `sort` 'display_order,start_datetime,name' | 'display_order,start_datetime,id' | 'start_datetime,name' | 'start_datetime,id' | 'id' — The sorting order for the resulting events.
It should be used in conjunction with pagination parameters.
The default and recommended sorting order and pagination is by event id.
The links to the next page returned on every request help clients navigate through all the relevant events - `limit` integer — The number of events to retrieve in the API call - `include_hidden` boolean — Choose to include in the response events that are not visible on the website. Hidden events may not be displayed for a varied number of reasons (for example the start date is too far away). Betting is not available for hidden events. - `jurisdiction` 'CDG' | 'CFTC' | 'DGA' | 'IGC' | 'IRGC' | 'MGA' | 'SGA' | 'UKGC' — Jurisdiction of user - `platform` 'exchange' | 'sbk' — Platform used by user ## Response `200` Events success response - object — Events success response - `events` object[], required - `bet_allowed` boolean — Determines whether bets are allowed in the given jurisdiction - `bettable` boolean — This needs to be True for events to be open for trading - `cftc` object — CFTC-specific enrichment data - `chart_time_period` string, nullable — A string to be used by frontend to show/default selectable chart time periods - `created` string, date-time, required — When was the event created in the Smarkets exchange - `description` string, nullable, required — Additional description for this event - `display_order` integer, nullable — On Smarkets listings pages, events will be sorted according to these numbers, in descending order - `end_date` string, date, nullable, required — When the event is scheduled to end - `full_slug` string, required — The URL slug for the event page - `hidden` boolean, required — True if the event is hidden from the Smarkets website - `id` string, required — This ID uniquely identifies an event - `inplay_enabled` boolean — True if trading will be open when the markets go live in-play - `modified` string, date-time, required — The datetime of the last modification made by Smarkets to the event properties - `name` string, required — The name of the event - `parent_id` string, nullable, required — This ID uniquely identifies the parent of the event - `seo_description` string, nullable — Additional description for this event used for SEO - `short_name` string, nullable, required — A shorter version of the name of the event - `slug` string, required — An easier way to identify the event - `special_rules` string, nullable — Special rules to be defined for this market - `start_date` string, date, nullable, required — In what day the event will go live, This can be useful for events that still have an unknown start_datetime - `start_datetime` string, date-time, nullable, required — When the event is scheduled to go live - `state` 'new' | 'upcoming' | 'live' | 'ended' | 'settled' | 'cancelled' | 'suspended', required — Event state can have the following values: - `super_sub_enabled` boolean — True for events that are in super-sub leagues - `type` union, required — The type of the event, for instance, the name of the sport
- 'american_football_match' | 'american_football_outright' | 'baseball_match' | 'baseball_outright' | 'basketball_esports_match' | 'basketball_match' | 'boxing_match' | 'call_of_duty_match' | 'cricket_match' | 'cricket_outright' | 'csgo_match' | 'current_affairs' | 'cycling' | 'darts_match' | 'darts_outright' | 'dota_2_match' | 'football_esports_match' | 'football_match' | 'football_outright' | 'golf_match' | 'golf_outright' | 'greyhound_racing_race' | 'handball_match' | 'horse_racing_race' | 'ice_hockey_match' | 'league_of_legends_match' | 'mma_match' | 'motorsports_race' | 'motorsports_outright' | 'politics' | 'politics_outright' | 'rowing' | 'rugby_league_match' | 'rugby_league_outright' | 'rugby_union_match' | 'rugby_union_outright' | 'sailing_race' | 'sailing_outright' | 'snooker_match' | 'snooker_outright' | 'table_tennis_match' | 'table_tennis_outright' | 'tennis_match' | 'tennis_outright' | 'volleyball_match' | 'generic' | 'top_level_event' | 'tv_entertainment' - object - `domain` 'accumulator' | 'american_football' | 'australian_rules' | 'baseball' | 'basketball' | 'basketball_esports' | 'boxing' | 'call_of_duty' | 'chess' | 'cricket' | 'csgo' | 'current_affairs' | 'cycling' | 'darts' | 'dota_2' | 'esports' | 'football' | 'football_esports' | 'golf' | 'greyhound_racing' | 'handball' | 'horse_racing' | 'ice_hockey' | 'king_of_glory' | 'league_of_legends' | 'lol_wild_rift' | 'mma' | 'motorsports' | 'olympics' | 'overwatch' | 'poker' | 'politics' | 'pubg' | 'rainbow_six_siege' | 'rocket_league' | 'rowing' | 'rugby_league' | 'rugby_union' | 'sailing' | 'snooker' | 'starcraft' | 'starcraft_2' | 'tv_and_entertainment' | 'table_tennis' | 'tennis' | 'valorant' | 'volleyball' | 'winter_sports' | 'gaelic_football' | 'gaelic_hurling', required — The domain part of the type (football, politics, horse_racing, etc) - `scope` 'root' | 'round' | 'category_root' | 'category' | 'single_event' | 'acca_root' | 'acca_category' | 'acca' | 'outright_root' | 'outright_category' | 'outright' | 'tour' | 'antepost_root' | 'antepost_category' | 'antepost', required — The scope part of the event type (single_event, outright, acca, etc) - `venue` object, nullable — Additional information about the state of this event - `pagination` object - `next_page` string, nullable, required — The url query string for clients to fetch the next page of results ## Other responses - `400` — REQUEST_VALIDATION_ERROR - `414` — REQUEST_TOO_LARGE - `429` — Rate limit exceeded - `500` — Internal server error - `503` — EVENTS_API_RATE_LIMIT, EVENTS_INTERNAL_ERROR, EVENTS_UNAVAILABLE --- [API](https://skmtc.dev/smarkets/apis/smarkets-http-api.md) · [All operations](https://skmtc.dev/smarkets/apis/smarkets-http-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/smarkets/smarkets-http-api/revisions/75f7e3050340/schema)