---
title: "List events"
method: GET
path: "/v2/events/"
tags: ["Market data"]
---

# List events

`GET /v2/events/`

## Request

- Base URL: `https://magicmarkets.com` (the document declares no server; this is the origin it was published from)
- URL: `https://magicmarkets.com/v2/events/`
- Auth: API key in header `X-Api-Key`

Lists the events that currently have prices. Each entry is the object the stream sends as `["event", {...}]`.

For price-sensitive work, use the streaming API: it pushes each change as it happens.

`ir_status` keeps the events in running (`in_running`) or not yet started (`pre_event`), the same values each event carries.

`event_type` gives the shape. A `normal` (match) event has `home` and `away`. A `multirunner` (outright) event has `teams` and `end_time`.

Page with `limit` and `after`: pass the previous page's last `"{sport},{event_id}"` as `after`. A page shorter than `limit` is the last one. The response has no total count.

`event_id` and `competition_id` filters need `sport`; a request without it gets a 400. Every entry has its `sport`, so a follow-up call can always supply it. Paging without filters needs no `sport`.

A filter that matches no event returns an empty `data`. This includes a sport, competition or event that has no prices at the moment. Each `event_id` must have the form an event carries, such as `2026-06-15,1001,2002`; any other form gets a 400.

## Query parameters

- `sport` string[]
- `competition_id` integer[]
- `event_id` string[]
- `lang` 'en' | 'zh-hans' | 'ko'
- `limit` integer
- `after` string
- `start_time_from` string, date-time
- `start_time_to` string, date-time
- `ir_status` 'pre_event' | 'in_running'

## Response `200`

Events with prices

- EventListEnvelope
  - `status` 'ok'
  - `data` Event[]: Events that currently have prices.
    - `event_type` 'normal' | 'multirunner'
    - `sport` string: Sport code
    - `event_id` string
    - `competition_id` integer
    - `competition_name` string
    - `competition_country` string: Country code of the competition, for example `US`, or `XE` for England.
    - `home` string, nullable: Normal events only
    - `away` string, nullable: Normal events only
    - `teams` object[], nullable: Runner list (multirunner events only)
      - `team_id` integer
      - `name` string
    - `end_time` string, date-time, nullable: Race end time (multirunner events only)
    - `event_name` string, nullable
    - `ir_status` 'pre_event' | 'in_running'
    - `start_time` string, date-time, nullable

## Other responses

- `400`: Invalid query parameter.
- `401`: Authentication failed - API key missing, malformed, or rejected.
- `403`: `invalid_customer`: the feed has no record of your account; contact support, because a retry gets the same answer. `forbidden`: the key is valid but cannot perform this action.
- `429`: Rate limit hit. Honour the `Retry-After` header.
- `500`: Unexpected internal error. Quote `data[1]` (the token) when contacting support.
- `503`: `warming`: the feed is loading its market data or customer records; retry with backoff. A body of `{ "detail": "Service unavailable" }` without the envelope means an upstream service could not be reached; retry with backoff.

---

[API](https://skmtc.dev/magicmarkets/apis/magicmarkets-api.md) · [All operations](https://skmtc.dev/magicmarkets/apis/magicmarkets-api/llms.txt) · [OpenAPI document](https://skmtc.dev/magicmarkets/apis/magicmarkets-api/revisions/00c2a7dcce2a?raw)