> For the complete documentation index, see [llms.txt](https://docs.sportmonks.com/v3/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.sportmonks.com/v3/sportmonks-ai-docs/mcp-server-beta/tools/fixtures.md).

# Fixtures

Get upcoming, live, or historic matches for a team or league, preview an upcoming fixture with head-to-head history, or fetch full match details including lineups, events, and statistics.

### Tools

| Tool                  | Description                                                       |
| --------------------- | ----------------------------------------------------------------- |
| `get_matches`         | Upcoming, live, or historic fixtures for a team or league         |
| `get_match_preview`   | Fixture info plus the last 5 head-to-head results                 |
| `get_fixture_details` | Detailed match data with optional lineups, events, and statistics |

### get\_matches

**Parameters**

| Parameter   | Type    | Required | Description                                 |
| ----------- | ------- | -------- | ------------------------------------------- |
| `id`        | integer | Yes      | Sportmonks team ID or league ID             |
| `type`      | string  | Yes      | `team` or `league`                          |
| `timeframe` | string  | No       | `upcoming` (default), `live`, or `historic` |

**Limits:**

* `upcoming` - next 14 days, max 20 fixtures
* `historic` - last 30 days, max 20 fixtures
* `live` - max 20 fixtures

### get\_match\_preview

Returns a fixture summary plus the last 5 head-to-head matches between the two teams.

> Only works for fixtures that have **not yet started**. Use `get_matches` with `timeframe: upcoming` to find a valid fixture ID.

**Parameters**

| Parameter | Type    | Required | Description           |
| --------- | ------- | -------- | --------------------- |
| `id`      | integer | Yes      | Sportmonks fixture ID |

### get\_fixture\_details

Returns base fixture data plus any optional expansions you request.

**Parameters**

| Parameter    | Type    | Required | Description                               |
| ------------ | ------- | -------- | ----------------------------------------- |
| `fixture_id` | integer | Yes      | Sportmonks fixture ID                     |
| `includes`   | array   | No       | Any of: `lineups`, `events`, `statistics` |

**Base response** includes both teams, scoreline, state, and league.

**Optional expansions:**

* `lineups` - starting XI and substitutes. Each player includes name, position (resolved label), detailed position, jersey number, and lineup type (starter/substitute)
* `events` - goals, cards, and substitutions in chronological order
* `statistics` - team stats (shots, possession, corners, etc.) keyed by type name

### Example prompts

* *Show me Arsenal's upcoming fixtures for the next two weeks*
* *What were Liverpool's results over the last 30 days?*
* *Are there any live matches right now?*
* *Give me a preview for fixture 19135697 - include the H2H record*
* *Get the full details for fixture 19135697 including lineups and statistics*


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.sportmonks.com/v3/sportmonks-ai-docs/mcp-server-beta/tools/fixtures.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.