---
title: "List Events"
method: POST
path: "/v1/mcp/list_events"
tags: ["mcp"]
---

# List Events

`POST /v1/mcp/list_events`

## Request

- Base URL: `https://api.infersports.dev` (the document declares no server; this is the origin it was published from)
- URL: `https://api.infersports.dev/v1/mcp/list_events`
- Auth: none declared

## Request body

- ListEventsRequest
  - `date` string, required: Calendar day to list, 'YYYY-MM-DD'. REQUIRED — this tool always returns a bounded window (use list_today_matches for 'today + still-live').
  - `date_to` string, nullable: Optional inclusive end day 'YYYY-MM-DD' — one call covers the whole [date, date_to] window (max 31 days), e.g. a tournament's group stage. Omit for a single day.
  - `timezone` string, nullable: Optional IANA timezone (e.g. 'Asia/Shanghai', 'America/New_York'). The day boundary is computed in this zone; default is the UTC day. The response keeps UTC `scheduled_at` as canonical and adds `scheduled_at_local` per fixture.
  - `sport` string, nullable: Filter: football | basketball.
  - `status` string, nullable: Filter: scheduled | live | finished.
  - `league` string, nullable: Filter by external league id (lg_…).
  - `limit` integer: Max fixtures to return (kickoff order).

## Response `200`

Successful Response

- ListEventsResult: A specific calendar day's fixtures (kickoff order), bounded by `limit`. UTC-canonical: `date` echoes the requested day, `timezone` the zone its boundary was computed in (null = UTC). Each fixture's `scheduled_at` stays UTC; `scheduled_at_local` is populated when a timezone was given. `truncated` is true when more fixtures fell on the day than were returned — narrow with sport/status/league rather than paging.
  - `date` string, required: The calendar day listed (YYYY-MM-DD), in `timezone` if given else UTC.
  - `date_to` string, nullable: Inclusive end day when a range was requested (null = single day).
  - `timezone` string, nullable: Echo of the requested timezone (null = UTC day).
  - `count` integer, required: Fixtures returned (after the limit cap).
  - `truncated` boolean: True when more fixtures matched the day than were returned.
  - `matches` MatchSummary[], required
    - `event_id` string, required: Canonical event id (evt_…); pass to get_match_odds / compare_lines.
    - `sport` string, required: football | basketball
    - `league` string, required: League name, e.g. 'English Premier League'.
    - `home_team` string, required
    - `away_team` string, required
    - `scheduled_at` string, nullable: Kickoff, ISO-8601 UTC.
    - `scheduled_at_local` string, nullable: Kickoff in the requested timezone (ISO-8601); null when no timezone was given.
    - `status` string, required: scheduled | live | finished
    - `score` Score
      - `home` integer, required
      - `away` integer, required
    - `red_cards` Score
      - `home` integer, required
      - `away` integer, required
    - `clock` string, nullable: Match clock when live, humanized for display: e.g. '1st half 25'', '2nd half 47'' (the real minute, not estimated) or 'half-time'; null pre-match or when the feed omits it. Basketball clocks (e.g. 'Q2 4:12') pass through as-is.
    - `confidence` number, nullable: Fuzzy-match confidence 0–1 (find_match only; null elsewhere).
    - `summary` string, nullable: One-line human-readable status, e.g. "Man City vs Arsenal — LIVE 1h 23 2-1." or "… — Kicks off 18:00 UTC on Jun 01." — ready to read to a user.

## Other responses

- `422`: Validation Error

---

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