--- title: "Retrieve the current states for events by id." method: GET path: "/v3/events/{event_ids}/states/" tags: ["events"] --- # Retrieve the current states for events by id. `GET /v3/events/{event_ids}/states/` ## Request - Base URL: `https://api.smarkets.com` - URL: `https://api.smarkets.com/v3/events/{event_ids}/states/` - Auth: none declared - TypeScript: (a function with typed inputs; its response is checked against the schema) ## Rate limits Maximum 600 requests per 60 seconds
## Path parameters - `event_ids` integer[], required ## Response `200` Events States success response - object: Events States success response - `event_states` object[], required - `actual_end_datetime` string, date-time, nullable: When the event actually ended - `actual_start_datetime` string, date-time, nullable: When the event actually went live - `aggregate` integer[], nullable: The score of the first leg in an aggregate.
The first value corresponds to the score of the team playing
as the home team in the first leg and second value to the away team. - `clock` object, nullable: Clock information for the event - `match_time` string: The current match time - `remaining_time` string: Remaining time - `remaining_time_in_period` string: Remaining time in the current period - `stoppage_time` string: Stoppage time of the current period - `stoppage_time_announced` string - `stopped` boolean: Indicates whether the clock is stopped - `has_league_table` boolean: Shows whether there is league table information linked to this event - `hidden` boolean, nullable, required: True if the event is hidden from the Smarkets website - `id` string, required: This ID uniquely identifies an event - `info` object, nullable: Additional information about the state of this event - `instant_match` boolean, required: Will instant match be enabled for this event.
For more information about this feature read this help article - `match_period` 'unknown' | 'first_half' | 'second_half' | 'extra_time_first_half' | 'extra_time_second_half' | 'penalty_shootout' | 'half_time' | 'end_of_second_half' | 'extra_time_half_time' | 'end_of_extra_time' | 'full_time' | 'pre_match' | 'awaiting_sudden_death' | 'sudden_death' | 'end_of_sudden_death' | 'awaiting_extra_time' | 'awaiting_penalties' | 'end_of_penalty_shootout' | 'first_pause' | 'third_pause' | 'overtime' | 'extra_innings' | 'pre_toss' | 'post_toss' | 'suspended' | 'in_progress' | 'break' | 'first_break' | 'second_break' | 'super_over_1' | 'super_over_2' | 'awaiting_super_over' | 'awaiting_overtime' | 'awaiting_golden_set' | 'golden_set' | 'after_golden_set' | 'delayed' | 'abandoned' | 'finished' | 'at_the_post' | 'going_down' | 'off' | 'dormant' | 'photograph' | 'result' | 'weighed_in' | 'amended_result' | 'race_void' | 'going_behind' | 'false_start' | 'parading' | 'rerun' | 'app_traps' | 'start_delay' | 'going_in_traps' | 'hare_running' | 'hare_stopped' | 'stopped_for_safety' | 'traps_failed' | 'no_race' | 'frame_1' | 'frame_2' | 'frame_3' | 'frame_4' | 'frame_5' | 'frame_6' | 'frame_7' | 'frame_8' | 'frame_9' | 'frame_10' | 'frame_11' | 'frame_12' | 'frame_13' | 'frame_14' | 'frame_15' | 'frame_16' | 'frame_17' | 'frame_18' | 'frame_19' | 'frame_20' | 'frame_21' | 'frame_22' | 'frame_23' | 'frame_24' | 'frame_25' | 'frame_26' | 'frame_27' | 'frame_28' | 'frame_29' | 'frame_30' | 'frame_31' | 'frame_32' | 'frame_33' | 'frame_34' | 'frame_35' | 'innings_1' | 'innings_2' | 'innings_3' | 'innings_4' | 'inning_1' | 'inning_2' | 'inning_3' | 'inning_4' | 'inning_5' | 'inning_6' | 'inning_7' | 'inning_8' | 'inning_9' | 'quarter_1' | 'quarter_2' | 'quarter_3' | 'quarter_4' | 'set_1' | 'set_2' | 'set_3' | 'set_4' | 'set_5' | 'set_6' | 'set_7' | 'set_8' | 'set_9' | 'set_10' | 'set_11' | 'set_12' | 'set_13' | 'map_1' | 'map_2' | 'map_3' | 'map_4' | 'map_5' | 'map_6' | 'map_7' | 'break_1' | 'break_2' | 'break_3' | 'break_4' | 'break_5' | 'break_6' | 'period_1' | 'period_2' | 'period_3': The current period of the match - `probable_pitcher` object, nullable: Probable pitcher information for Baseball games.
This field will be null for other sports, and can be empty for some Baseball games if we don't have this information available. - `away` object: Pitcher specific information for a team - `id` string, required: Pitcher ID - `name` string, required: Pitcher name - `team` string, required: Team ID - `home` object: Pitcher specific information for a team - `id` string, required: Pitcher ID - `name` string, required: Pitcher name - `team` string, required: Team ID - `provider_metadata` object, nullable, required: Additional metadata from our events provider - `reversed` boolean, nullable: True if the event name is written in the form at - `scores` union, required: football, point based, set based, cricket, part based, golf, rugby - object - `current` integer[] - `full` integer[] - `half` integer[] - object - `current` integer[] - `full` integer[] - `game` integer[] - `golden_set` integer[] - `leg` integer[] - `set_1` integer[] - `set_10` integer[] - `set_11` integer[] - `set_12` integer[] - `set_13` integer[] - `set_2` integer[] - `set_3` integer[] - `set_4` integer[] - `set_5` integer[] - `set_6` integer[] - `set_7` integer[] - `set_8` integer[] - `set_9` integer[] - `sets` object[] - `score_a` integer, required: Score for `a` competitor - `score_b` integer, required: Score for `b` competitor - `tiebreak` integer[] - `tiebreak_1` integer[] - `tiebreak_2` integer[] - `tiebreak_3` integer[] - `tiebreak_4` integer[] - `tiebreak_5` integer[] - object - `a_innings` string[] - `b_innings` string[] - `current` integer[] - `full` integer[] - `scorecard` object - `commentary` string, nullable - `innings_1` object, nullable - `batsmen` object[], nullable - … - `bowlers` object[], nullable - … - `competitor_id` string, nullable - `competitor_name` string, nullable - `conclusion` string, nullable - `extras_summary` object, nullable - `has_target` boolean, nullable - `innings_number` integer - `is_final_innings` boolean, nullable - `is_follow_on` boolean, nullable - `overs` string - `overs_available` integer - `runs` integer - `target` integer, nullable - `wickets` integer - `innings_2` object, nullable - `batsmen` object[], nullable - … - `bowlers` object[], nullable - … - `competitor_id` string, nullable - `competitor_name` string, nullable - `conclusion` string, nullable - `extras_summary` object, nullable - `has_target` boolean, nullable - `innings_number` integer - `is_final_innings` boolean, nullable - `is_follow_on` boolean, nullable - `overs` string - `overs_available` integer - `runs` integer - `target` integer, nullable - `wickets` integer - `innings_3` object, nullable - `batsmen` object[], nullable - … - `bowlers` object[], nullable - … - `competitor_id` string, nullable - `competitor_name` string, nullable - `conclusion` string, nullable - `extras_summary` object, nullable - `has_target` boolean, nullable - `innings_number` integer - `is_final_innings` boolean, nullable - `is_follow_on` boolean, nullable - `overs` string - `overs_available` integer - `runs` integer - `target` integer, nullable - `wickets` integer - `innings_4` object, nullable - `batsmen` object[], nullable - … - `bowlers` object[], nullable - … - `competitor_id` string, nullable - `competitor_name` string, nullable - `conclusion` string, nullable - `extras_summary` object, nullable - `has_target` boolean, nullable - `innings_number` integer - `is_final_innings` boolean, nullable - `is_follow_on` boolean, nullable - `overs` string - `overs_available` integer - `runs` integer - `target` integer, nullable - `wickets` integer - `recent_overs` object[] - `winner` string, nullable: Winner of the event - object - `current` integer[] - `extra` integer[] - `extra_innings` integer[] - `full` integer[] - `half` integer[] - `inning_1` integer[] - `inning_2` integer[] - `inning_3` integer[] - `inning_4` integer[] - `inning_5` integer[] - `inning_6` integer[] - `inning_7` integer[] - `inning_8` integer[] - `inning_9` integer[] - `map_1` integer[] - `map_2` integer[] - `map_3` integer[] - `map_4` integer[] - `map_5` integer[] - `map_6` integer[] - `map_7` integer[] - `map_8` integer[] - `map_9` integer[] - `overtime` integer[] - `part_1` integer[] - `part_2` integer[] - `part_3` integer[] - `part_4` integer[] - `part_5` integer[] - `part_6` integer[] - `part_7` integer[] - `part_8` integer[] - `part_9` integer[] - `penalty` integer[] - `period_1` integer[] - `period_2` integer[] - `period_3` integer[] - `shootout` integer[] - `total_score` integer: Total score for this event - `winner` 'home' | 'away': Winner of the event - object - `positions` object - object - `current` integer[] - `first_half` integer[] - `full` integer[] - `overtime` integer[] - `second_half` integer[] - object - `current` integer[] - `first_half` integer[] - `full` integer[] - `over_time` integer[] - `quarter_1` integer[] - `quarter_2` integer[] - `quarter_3` integer[] - `quarter_4` integer[] - `second_half` integer[] - object - `current` integer[] - `extra_time` integer[] - `extra_time_first_half` integer[] - `extra_time_second_half` integer[] - `first_half` integer[] - `full` integer[] - `normal_time` integer[] - `penalties` integer[] - `second_half` integer[] - object - `horse_results` object, required: result of each horse - `beaten_distance` string - `close_up` string - `horse_id` string - `name` string - `position` string - object - `greyhound_results` object, required: result of each greyhound - `beaten_distance` string - `greyhound_id` string - `name` string - `position` string - object - `current` integer[] - `frame_1` integer[] - `frame_10` integer[] - `frame_11` integer[] - `frame_12` integer[] - `frame_13` integer[] - `frame_14` integer[] - `frame_15` integer[] - `frame_16` integer[] - `frame_17` integer[] - `frame_18` integer[] - `frame_19` integer[] - `frame_2` integer[] - `frame_20` integer[] - `frame_21` integer[] - `frame_22` integer[] - `frame_23` integer[] - `frame_24` integer[] - `frame_25` integer[] - `frame_26` integer[] - `frame_27` integer[] - `frame_28` integer[] - `frame_29` integer[] - `frame_3` integer[] - `frame_30` integer[] - `frame_31` integer[] - `frame_32` integer[] - `frame_33` integer[] - `frame_34` integer[] - `frame_35` integer[] - `frame_4` integer[] - `frame_5` integer[] - `frame_6` integer[] - `frame_7` integer[] - `frame_8` integer[] - `frame_9` integer[] - `full` integer[] - `game` integer[] - `sets` integer[] - `show_flags` boolean, nullable: display the country flag for the both competitors using the country code - `state` 'new' | 'upcoming' | 'live' | 'ended' | 'settled' | 'cancelled' | 'suspended', required: Event state can have the following values:
  • upcoming: the event is now open for betting
  • live: the event is now live in-play
  • ended: the event has ended and its markets should be settled
  • settled: the event has ended and its markets should be settled
  • cancelled: the event was cancelled and didn't take place
  • suspended: the event was suspended and during play time
- `tennis_server` 'a' | 'b', nullable, required: In case of a tennis match, this indicates who is serving, otherwise it's null - `visualization` boolean, nullable, required: Is visualization enabled for this event ## Other responses - `400`: REQUEST_VALIDATION_ERROR - `401`: EVENTS_AUTH_BREAKER - `404`: NO_RESULTS_FOUND - `414`: REQUEST_TOO_LARGE - `429`: RATE_LIMIT_EXCEEDED - `500`: Internal server error - `503`: EVENTS_INTERNAL_ERROR, EVENTS_API_RATE_LIMIT, EVENTS_UNAVAILABLE ## Changes > 21 revisions in range; 1 not diffed. - **2026-10-22** `d942ef7e7158`: 1 info - added the non-success response with the status `401` - **2026-10-09** `a87a2496f57e`: 5 breaking - the response's body type changed from `object` to no type for status `429` - the `data` response's property type changed from `object` to `string, object` for status `429` - removed the required property `data/count` from the response with the `429` status - removed the required property `data/expiry` from the response with the `429` status - …1 more - **2024-08-26** `e605dcddbcbe`: 2 info - added the optional property `event_states/items/scores/anyOf[subschema #4: parts_based_score]/map_8` to the response with the `200` status - added the optional property `event_states/items/scores/anyOf[subschema #4: parts_based_score]/map_9` to the response with the `200` status - **2022-10-22** `a17ca5bb986a`: 41 warning, 8 info - added the new `frame_1` enum value to the `event_states/items/match_period` response property for the response status `200` - added the new `frame_10` enum value to the `event_states/items/match_period` response property for the response status `200` - added the new `frame_11` enum value to the `event_states/items/match_period` response property for the response status `200` - added the new `frame_12` enum value to the `event_states/items/match_period` response property for the response status `200` - …45 more - …earlier changes not shown [Operation history](https://skmtc.dev/smarkets/apis/smarkets-http-api/changes/v3/events/:event_ids/states/get.md) --- [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.dev/smarkets/apis/smarkets-http-api/revisions/32c5f1f4369e?raw)