Skip to main content
GET
/
v2
/
matches
List Events
curl --request GET \
  --url https://api.mrdoge.co/v2/matches \
  --header 'Authorization: Bearer <token>'
{
  "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
}

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.

Requires Authentication: This endpoint requires an API key and costs 1 credit per request.
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)
For real-time live data: Use the Get 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.
For full event details including markets and odds, use the Get Event Details endpoint.
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.

​
Authorization

​
Authorization
string
default:"Bearer "
required
Your API key for authentication

​
Query Parameters

​
locale
string
default:"en"
Language for team, competition, and region names. Supported: en, es, pt
​
competitionId
string
Filter by competition IDExample: 847 for Premier League
​
regionId
string
Filter by region IDExample: 6 for England
​
sportName
string
Filter by sport nameOptions: soccer, basketball, tennis, baseball, volleyball, american-football, ice-hockey, handballExample: soccer
​
status
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
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 endpoint instead (/v2/matches/live).
​
date
string
Filter events on specific date (YYYY-MM-DD)Example: 2025-11-08
When no date parameters are provided, the API returns events based on the default status filter (upcoming and live events).
Cannot be used together with startDate or endDate. Choose either date for single-day filtering or startDate/endDate for range filtering.
​
startDate
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.
Cannot be used together with date parameter.
​
endDate
string
Filter events ending on or before this date (YYYY-MM-DD). Used with startDate for range-based queries.
Cannot be used together with date parameter.
​
limit
string
default:"100"
Maximum number of events to return per pageDefault: 100, Maximum: 100
​
page
string
default:"1"
Page number for paginationExample: page=1, page=2, page=3Default: 1 (first page)
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.
​
timezone
string
Timezone for date filtering. Uses IANA timezone identifiers.Example: America/New_York, Europe/London, America/Sao_Paulo
Recommended to always include timezone for accurate date filtering based on user location.
Always include the locale parameter (en, es, or pt) to control translations. Requests without it default to English.
Getting Live Events with Real-Time Data: Use the dedicated /v2/matches/live endpoint for real-time scores, odds, and statistics:
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.

​
Response

​
data
array
Array of event objects
​
count
integer
Total number of events matching the filters

​
Event Object

​
id
string
Unique event IDExample: 123456
​
competitionId
integer
Parent competition ID
​
regionId
integer
Parent region ID
​
sportId
integer
Sport ID (1=Soccer, 2=Basketball, etc.)
​
startDateTime
string
Event start time in ISO 8601 formatExample: 2025-11-08T15:00:00Z
​
status
string
Event status: upcoming, live, or completed
​
views
integer
Number of times this event has been viewed
​
stats
array
Conditional field - Only present for completed events. Contains final match statistics including scores and sport-specific data.
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)
​
metadata
object
Sport-specific event data including team names, markets, and odds

​
Example Request

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"

​
Response

{
  "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
}

​
Pagination Strategy

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

​
Page-Based Pagination

# 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

# 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

# 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"
Performance: Each page is cached separately in Redis. When event data changes, all cached pages are invalidated automatically to ensure data consistency.

​
Common Filters

Get all events happening today in a specific timezone:
?date=2025-11-08&timezone=America/New_York&locale=en
Perfect for building daily event schedules or “today’s matches” widgets.
Get a static list of currently live events:
?status=live&locale=en
Important: This returns a static list only without real-time data. For live scores, odds, and statistics, use the /live-events endpoint instead (/v2/matches/live).
Get finished events with final scores and statistics:
?status=completed&date=2025-11-08&locale=en
Includes the stats field with complete match data, timeline, and final scores.
Get all events for a specific competition:
?competitionId=847&locale=en
Use this pattern for any league/tournament - just change the competitionId.

Authorizations

​
Authorization
string
header
required

Use your API key from the Mr. Doge dashboard. Format: Bearer sk_live_... or Bearer sk_test_...

Query Parameters

​
competitionId
string

Filter by competition ID

Example:

"1"

​
regionId
string

Filter by region ID

Example:

"1"

​
status
enum<string>[]

Filter by one or more event statuses. Repeat the parameter or send a comma-separated value (e.g., status=upcoming&status=completed).

Available options:
upcoming,
live,
completed
​
date
string<date>

Filter events on specific date (YYYY-MM-DD)

Example:

"2025-11-08"

​
startDate
string<date>

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).

​
endDate
string<date>

Filter events ending on or before this date (YYYY-MM-DD). Use with startDate for range-based pagination.

​
limit
string

Maximum number of events to return

Example:

"50"

​
timezone
string

Timezone for date filtering

Example:

"America/New_York"

Response

List of events

​
data
object[]
​
count
integer
Example:

45