Events

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

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:

First request: GET /events?date=2025-11-15&page=1&limit=100 → Returns first 100 events
Next request: GET /events?date=2025-11-15&page=2&limit=100 → Returns next 100 events (101-200)
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

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)

Show Stats Object Structure (Completed Events Only)

stats.homeGoals

integer

Final home team score/goals

stats.awayGoals

integer

Final away team score/goals

stats.homeCorners

integer

Final home team corners (soccer)

stats.awayCorners

integer

Final away team corners (soccer)

stats.homeYellowCards

integer

Final home team yellow cards (soccer)

stats.awayYellowCards

integer

Final away team yellow cards (soccer)

stats.phase

string

Final match phase (e.g., “FULL_TIME”, “AFTER_EXTRA_TIME”)

metadata

object

Sport-specific event data including team names, markets, and odds

Show Metadata Structure

sportName

string

Sport name (soccer, basketball, tennis, etc.)

homeTeamName

string

Home team name (localized via locale)

awayTeamName

string

Away team name (localized via locale)

markets

array

Available betting markets with 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

Today's Events

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.

Live Event List

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

Completed Events

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.

Premier League Events

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[]

Show child attributes

data.id

string

Example:

"123456"

data.competitionId

integer

Example:

1

data.homeTeamId

integer

deprecated

Example:

100

data.awayTeamId

integer

deprecated

Example:

101

data.regionId

integer

Example:

1

data.sportId

integer

Example:

1

data.startDateTime

string<date-time>

Example:

"2025-11-08T15:00:00Z"

data.status

enum<string>

Available options:

upcoming,

live,

completed

Example:

"upcoming"

data.views

integer

Example:

1250

data.metadata

object

Sport-specific event metadata including teams, markets, and odds

Show child attributes

data.metadata.sportName

string

Example:

"soccer"

data.metadata.homeTeamName

string

Example:

"Arsenal"

data.metadata.awayTeamName

string

Example:

"Chelsea"

count

integer

Example:

45

Sports Endpoints

AI Endpoints

Core Utilities

Authorization

Query Parameters

Response

Event Object

Example Request

Response

Common Filters

Authorizations

Query Parameters

Response

Sports Endpoints

AI Endpoints

Core Utilities

​Authorization

​Query Parameters

​Response

​Event Object

​Example Request

​Response

​Pagination Strategy

​Page-Based Pagination

​Pagination with Date Ranges

​Pagination with Filters

​Common Filters

Authorizations

Query Parameters

Response

Authorization

Query Parameters

Response

Event Object

Example Request

Response

Pagination Strategy

Page-Based Pagination

Pagination with Date Ranges

Pagination with Filters

Common Filters