> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mrdoge.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Events

> Get sporting events with filtering by competition, region, date, and status

<Warning>
  **Requires Authentication**: This endpoint requires an API key and costs **1 credit** per request.
</Warning>

Returns a list of sporting events with basic information. Use filters to find specific events by competition, region, date, or status.

This is the main endpoint for **browsing event lists and schedules**. It supports **all event statuses** including:

* `upcoming` - Events that haven't started yet (no stats)
* `live` - Currently ongoing events (**list only, no real-time data**)
* `completed` - Finished events (includes final scores and stats)

<Warning>
  **For real-time live data**: Use the [Get Live Events](/api-reference/sports/live-events) endpoint (2 credits) instead of `status=live` on this endpoint. The `/v2/matches/live` endpoint provides real-time scores, odds, and statistics with sub-second response times.

  This endpoint (`/v2/matches`) is designed for **static event lists and schedules**. Live events returned here will NOT include real-time stats or odds.
</Warning>

For full event details including markets and odds, use the [Get Event Details](/api-reference/sports/event-details) endpoint.

<Note>
  **Pagination**: This endpoint returns a maximum of 100 events per request. To retrieve more events, use date ranges (`startDate`/`endDate`) or filter by specific competitions/regions and make multiple requests.
</Note>

## Authorization

<ParamField header="Authorization" type="string" required default="Bearer " placeholder="Bearer sk_live_...">
  Your API key for authentication
</ParamField>

## Query Parameters

<ParamField query="locale" type="string" default="en">
  Language for team, competition, and region names. Supported: `en`, `es`, `pt`
</ParamField>

<ParamField query="competitionId" type="string">
  Filter by competition ID

  Example: `847` for Premier League
</ParamField>

<ParamField query="regionId" type="string">
  Filter by region ID

  Example: `6` for England
</ParamField>

<ParamField query="sportName" type="string">
  Filter by sport name

  Options: `soccer`, `basketball`, `tennis`, `baseball`, `volleyball`, `american-football`, `ice-hockey`, `handball`

  Example: `soccer`
</ParamField>

<ParamField query="status" type="string" default="upcoming,live">
  Filter by one or more event statuses.

  Options:

  * `upcoming` - Events that haven't started (no stats field)
  * `live` - Currently ongoing events (**no stats/odds** - use `/v2/matches/live` for real-time data)
  * `completed` - Finished events (includes `stats` field with final scores)

  Pass multiple statuses with a comma (`status=upcoming,completed`) or by repeating the parameter (`status=upcoming&status=completed`).

  Default: Returns both `upcoming` and `live` events

  <Warning>
    **Using `status=live`?** This returns a static list of live events without real-time data. For live scores, odds, and statistics, use the dedicated [/live-events](/api-reference/sports/live-events) endpoint instead (`/v2/matches/live`).
  </Warning>
</ParamField>

<ParamField query="date" type="string">
  Filter events on specific date (YYYY-MM-DD)

  Example: `2025-11-08`

  <Note>
    When no date parameters are provided, the API returns events based on the default `status` filter (upcoming and live events).
  </Note>

  <Warning>
    Cannot be used together with `startDate` or `endDate`. Choose either `date` for single-day filtering or `startDate`/`endDate` for range filtering.
  </Warning>
</ParamField>

<ParamField query="startDate" type="string">
  Filter events starting on or after this date (YYYY-MM-DD). Pair with `endDate` to fetch a multi-day window (e.g., a full week) in one request and paginate through the calendar efficiently.

  <Warning>
    Cannot be used together with `date` parameter.
  </Warning>
</ParamField>

<ParamField query="endDate" type="string">
  Filter events ending on or before this date (YYYY-MM-DD). Used with `startDate` for range-based queries.

  <Warning>
    Cannot be used together with `date` parameter.
  </Warning>
</ParamField>

<ParamField query="limit" type="string" default="100">
  Maximum number of events to return per page

  Default: `100`, Maximum: `100`
</ParamField>

<ParamField query="page" type="string" default="1">
  Page number for pagination

  Example: `page=1`, `page=2`, `page=3`

  Default: `1` (first page)

  <Note>
    **How pagination works**:

    1. First request: `GET /events?date=2025-11-15&page=1&limit=100` → Returns first 100 events
    2. Next request: `GET /events?date=2025-11-15&page=2&limit=100` → Returns next 100 events (101-200)
    3. Continue incrementing `page` until no more results

    Each page is cached separately for optimal performance.
  </Note>
</ParamField>

<ParamField query="timezone" type="string">
  Timezone for date filtering. Uses IANA timezone identifiers.

  Example: `America/New_York`, `Europe/London`, `America/Sao_Paulo`

  <Note>
    Recommended to always include timezone for accurate date filtering based on user location.
  </Note>
</ParamField>

<Info>
  Always include the `locale` parameter (`en`, `es`, or `pt`) to control translations. Requests without it default to English.
</Info>

<Tip>
  **Getting Live Events with Real-Time Data**: Use the dedicated `/v2/matches/live` endpoint for real-time scores, odds, and statistics:

  ```bash theme={null}
  GET /v2/matches/live?sport=soccer&locale=en
  ```

  This provides sub-second response times and includes live stats, odds movements, and real-time scores.

  **Don't use** `/v2/matches?status=live` for real-time data - it only returns a static list without stats.
</Tip>

## Response

<ResponseField name="data" type="array">
  Array of event objects
</ResponseField>

<ResponseField name="count" type="integer">
  Total number of events matching the filters
</ResponseField>

### Event Object

<ResponseField name="id" type="string">
  Unique event ID

  Example: `123456`
</ResponseField>

<ResponseField name="competitionId" type="integer">
  Parent competition ID
</ResponseField>

<ResponseField name="regionId" type="integer">
  Parent region ID
</ResponseField>

<ResponseField name="sportId" type="integer">
  Sport ID (1=Soccer, 2=Basketball, etc.)
</ResponseField>

<ResponseField name="startDateTime" type="string">
  Event start time in ISO 8601 format

  Example: `2025-11-08T15:00:00Z`
</ResponseField>

<ResponseField name="status" type="string">
  Event status: `upcoming`, `live`, or `completed`
</ResponseField>

<ResponseField name="views" type="integer">
  Number of times this event has been viewed
</ResponseField>

<ResponseField name="stats" type="array">
  **Conditional field** - Only present for `completed` events. Contains final match statistics including scores and sport-specific data.

  <Note>
    **Important**: This endpoint does NOT return `stats` for `upcoming` or `live` events:

    * `upcoming` events: No stats (event hasn't started)
    * `live` events: No stats (**use `/v2/matches/live` for real-time data**)
    * `completed` events: Includes final stats (static data)
  </Note>

  <Expandable title="Stats Object Structure (Completed Events Only)">
    <ResponseField name="stats.homeGoals" type="integer">
      Final home team score/goals
    </ResponseField>

    <ResponseField name="stats.awayGoals" type="integer">
      Final away team score/goals
    </ResponseField>

    <ResponseField name="stats.homeCorners" type="integer">
      Final home team corners (soccer)
    </ResponseField>

    <ResponseField name="stats.awayCorners" type="integer">
      Final away team corners (soccer)
    </ResponseField>

    <ResponseField name="stats.homeYellowCards" type="integer">
      Final home team yellow cards (soccer)
    </ResponseField>

    <ResponseField name="stats.awayYellowCards" type="integer">
      Final away team yellow cards (soccer)
    </ResponseField>

    <ResponseField name="stats.phase" type="string">
      Final match phase (e.g., "FULL\_TIME", "AFTER\_EXTRA\_TIME")
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="metadata" type="object">
  Sport-specific event data including team names, markets, and odds

  <Expandable title="Metadata Structure">
    <ResponseField name="sportName" type="string">
      Sport name (soccer, basketball, tennis, etc.)
    </ResponseField>

    <ResponseField name="homeTeamName" type="string">
      Home team name (localized via `locale`)
    </ResponseField>

    <ResponseField name="awayTeamName" type="string">
      Away team name (localized via `locale`)
    </ResponseField>

    <ResponseField name="markets" type="array">
      Available betting markets with odds
    </ResponseField>
  </Expandable>
</ResponseField>

## Example Request

<CodeGroup>
  ```bash cURL theme={null}
  curl -H "Authorization: Bearer sk_live_..." \
    "https://api.mrdoge.co/v2/matches?competitionId=1&date=2025-11-08&limit=10&status=upcoming&status=live&status=completed&locale=en"
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://api.mrdoge.co/v2/matches?competitionId=1&date=2025-11-08&limit=10&status=upcoming&status=live&status=completed&locale=en', {
    headers: {
      'Authorization': 'Bearer sk_live_...'
    }
  });

  const data = await response.json();
  console.log(data);
  ```

  ```python Python theme={null}
  import requests

  headers = {
      'Authorization': 'Bearer sk_live_...'
  }

  response = requests.get(
      'https://api.mrdoge.co/v2/matches',
      headers=headers,
      params={
          'competitionId': '1',
          'date': '2025-11-08',
          'status': ['upcoming', 'live', 'completed'],
          'limit': '10',
          'locale': 'en'
      }
  )

  data = response.json()
  print(data)
  ```
</CodeGroup>

## Response

<ResponseExample>
  ```json Response theme={null}
  {
    "data": [
      {
        "id": "42099047",
        "startDateTime": "2025-09-13T11:30:00.000Z",
        "status": "upcoming",
        "homeTeamId": 95450,
        "homeTeam": {
          "id": 95450,
          "name": "Arsenal"
        },
        "awayTeamId": 11045,
        "awayTeam": {
          "id": 11045,
          "name": "Nottingham Forest"
        },
        "sportId": 1,
        "sport": {
          "id": 1,
          "name": "soccer"
        },
        "competitionId": 847,
        "competition": {
          "id": 847,
          "caption": "Premier League"
        },
        "regionId": 6,
        "region": {
          "id": 6,
          "caption": "England"
        },
        "markets": [
          {
            "id": "1432181681",
            "betTypeSysname": "SOCCER_MATCH_RESULT",
            "betItems": [
              {
                "id": "<string>",
                "code": "1",
                "caption": "1",
                "price": 1.4,
                "isAvailable": true
              },
              {
                "id": "<string>",
                "code": "X",
                "caption": "X",
                "price": 4.7,
                "isAvailable": true
              },
              {
                "id": "<string>",
                "code": "2",
                "caption": "2",
                "price": 8.1,
                "isAvailable": true
              }
            ]
          },
          {
            "id": "<string>",
            "betTypeSysname": "SOCCER_UNDER_OVER",
            "betItems": [
              {
                "id": "<string>",
                "code": "O",
                "caption": "Over 2.5",
                "price": 1.72,
                "isAvailable": true
              },
              {
                "id": "<string>",
                "code": "U",
                "caption": "Under 2.5",
                "price": 2.1,
                "isAvailable": true
              }
            ]
          }
        ]
      }
    ],
    "count": 1
  }
  ```
</ResponseExample>

## Pagination Strategy

The endpoint returns a maximum of 100 events per request. Use the `page` parameter to paginate through results:

### Page-Based Pagination

```bash theme={null}
# Page 1: First 100 events for a specific date
curl -H "Authorization: Bearer sk_live_..." \
  "https://api.mrdoge.co/v2/matches?date=2025-11-15&page=1&limit=100&locale=en"

# Page 2: Next 100 events (events 101-200)
curl -H "Authorization: Bearer sk_live_..." \
  "https://api.mrdoge.co/v2/matches?date=2025-11-15&page=2&limit=100&locale=en"

# Page 3: Next 100 events (events 201-300)
curl -H "Authorization: Bearer sk_live_..." \
  "https://api.mrdoge.co/v2/matches?date=2025-11-15&page=3&limit=100&locale=en"
```

### Pagination with Date Ranges

```bash theme={null}
# Week's events - Page 1
curl -H "Authorization: Bearer sk_live_..." \
  "https://api.mrdoge.co/v2/matches?startDate=2025-11-15&endDate=2025-11-22&page=1&locale=en"

# Week's events - Page 2
curl -H "Authorization: Bearer sk_live_..." \
  "https://api.mrdoge.co/v2/matches?startDate=2025-11-15&endDate=2025-11-22&page=2&locale=en"
```

### Pagination with Filters

```bash theme={null}
# Premier League events - Page 1
curl -H "Authorization: Bearer sk_live_..." \
  "https://api.mrdoge.co/v2/matches?competitionId=847&page=1&locale=en"

# Premier League events - Page 2
curl -H "Authorization: Bearer sk_live_..." \
  "https://api.mrdoge.co/v2/matches?competitionId=847&page=2&locale=en"
```

<Note>
  **Performance**: Each page is cached separately in Redis. When event data changes, all cached pages are invalidated automatically to ensure data consistency.
</Note>

## Common Filters

<AccordionGroup>
  <Accordion title="Today's Events" icon="calendar-day">
    Get all events happening today in a specific timezone:

    ```bash theme={null}
    ?date=2025-11-08&timezone=America/New_York&locale=en
    ```

    Perfect for building daily event schedules or "today's matches" widgets.
  </Accordion>

  <Accordion title="Live Event List" icon="list">
    Get a static list of currently live events:

    ```bash theme={null}
    ?status=live&locale=en
    ```

    <Warning>
      **Important**: This returns a **static list only** without real-time data. For live scores, odds, and statistics, use the [/live-events](/api-reference/sports/live-events) endpoint instead (`/v2/matches/live`).
    </Warning>
  </Accordion>

  <Accordion title="Completed Events" icon="check-circle">
    Get finished events with final scores and statistics:

    ```bash theme={null}
    ?status=completed&date=2025-11-08&locale=en
    ```

    Includes the `stats` field with complete match data, timeline, and final scores.
  </Accordion>

  <Accordion title="Premier League Events" icon="futbol">
    Get all events for a specific competition:

    ```bash theme={null}
    ?competitionId=847&locale=en
    ```

    Use this pattern for any league/tournament - just change the `competitionId`.
  </Accordion>
</AccordionGroup>


## OpenAPI

````yaml /api-reference/openapi.json GET /v2/matches
openapi: 3.1.0
info:
  title: Mr. Doge API
  description: >-
    Comprehensive sports betting odds, AI predictions, and live data API
    covering 8 major sports with real-time updates and value betting
    recommendations.
  version: 1.0.0
  contact:
    name: Mr. Doge Support
    email: support@mrdoge.co
    url: https://mrdoge.co
servers:
  - url: https://api.mrdoge.co
    description: Production server
security:
  - bearerAuth: []
tags:
  - name: Odds
    description: Endpoints for accessing sports events, odds, and betting markets
  - name: AI
    description: AI-powered betting recommendations and value opportunities
paths:
  /v2/matches:
    get:
      tags:
        - Odds
      summary: List Events
      description: >-
        Get sporting events with filtering by competition, region, date, and
        status. Returns events with basic information.
      parameters:
        - name: competitionId
          in: query
          description: Filter by competition ID
          schema:
            type: string
            example: '1'
        - name: regionId
          in: query
          description: Filter by region ID
          schema:
            type: string
            example: '1'
        - name: status
          in: query
          description: >-
            Filter by one or more event statuses. Repeat the parameter or send a
            comma-separated value (e.g., status=upcoming&status=completed).
          style: form
          explode: true
          schema:
            type: array
            items:
              type: string
              enum:
                - upcoming
                - live
                - completed
        - name: date
          in: query
          description: Filter events on specific date (YYYY-MM-DD)
          schema:
            type: string
            format: date
            example: '2025-11-08'
        - name: startDate
          in: query
          description: >-
            Filter events starting on or after this date (YYYY-MM-DD). Combine
            with endDate to request a multi-day window (e.g., a full week).
          schema:
            type: string
            format: date
        - name: endDate
          in: query
          description: >-
            Filter events ending on or before this date (YYYY-MM-DD). Use with
            startDate for range-based pagination.
          schema:
            type: string
            format: date
        - name: status
          in: query
          description: >-
            Filter by one or more event statuses. Repeat the parameter or send a
            comma-separated value (e.g., status=upcoming&status=completed).
          style: form
          explode: true
          schema:
            type: array
            items:
              type: string
              enum:
                - upcoming
                - live
                - completed
        - name: limit
          in: query
          description: Maximum number of events to return
          schema:
            type: string
            example: '50'
        - name: timezone
          in: query
          description: Timezone for date filtering
          schema:
            type: string
            example: America/New_York
      responses:
        '200':
          description: List of events
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Event'
                  count:
                    type: integer
                    example: 45
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/InsufficientCredits'
components:
  schemas:
    Event:
      type: object
      properties:
        id:
          type: string
          example: '123456'
        competitionId:
          type: integer
          example: 1
        homeTeamId:
          type: integer
          example: 100
          deprecated: true
        awayTeamId:
          type: integer
          example: 101
          deprecated: true
        regionId:
          type: integer
          example: 1
        sportId:
          type: integer
          example: 1
        startDateTime:
          type: string
          format: date-time
          example: '2025-11-08T15:00:00Z'
        status:
          type: string
          enum:
            - upcoming
            - live
            - completed
          example: upcoming
        views:
          type: integer
          example: 1250
        metadata:
          type: object
          description: Sport-specific event metadata including teams, markets, and odds
          properties:
            sportName:
              type: string
              example: soccer
            homeTeamName:
              type: string
              example: Arsenal
            awayTeamName:
              type: string
              example: Chelsea
    Error:
      type: object
      properties:
        statusCode:
          type: integer
          example: 400
        message:
          type: string
          example: Invalid request parameters
        error:
          type: string
          example: Bad Request
  responses:
    Unauthorized:
      description: Missing or invalid API key
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            statusCode: 401
            message: Invalid API key
            error: Unauthorized
    InsufficientCredits:
      description: Not enough credits to complete request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            statusCode: 403
            message: Insufficient credits. This endpoint costs 2 credits.
            error: Forbidden
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key
      description: >-
        Use your API key from the Mr. Doge dashboard. Format: `Bearer
        sk_live_...` or `Bearer sk_test_...`

````