Live Events

Requires Authentication: This endpoint requires an API key and costs 2 credits per request.

Returns all currently live sporting events with real-time statistics and odds. This endpoint is optimized for speed, providing sub-second response times even under heavy load. Why use this endpoint instead of /v2/matches?status=live?

10-100x faster - Optimized for real-time performance
Real-time data included - Live scores, odds, phase, elapsed time
Always fresh - Updated every 30 seconds as events progress
Worth the cost - 2 credits for real-time data vs 1 credit for static list
Live-only - No mixed results, guaranteed live events

Key Difference: /v2/matches?status=live returns a static list without stats/odds. This endpoint returns real-time live data with scores and odds updated every 30 seconds.

Freshness Guarantee: Events are updated in real-time as matches progress. Maximum staleness is 30 seconds.

Migration from /v2/matches?status=live:If you’re currently using /v2/matches?status=live, you’re only getting a static list of event IDs and names without real-time data. That endpoint:

Does NOT include live scores, odds, or statistics
Static data (not updated in real-time)
Costs only 1 credit
Good for “Live Now” badges or event lists

This endpoint (/v2/matches/live):

Includes live scores, odds movements, and real-time stats
Updated every 30 seconds (fresh data)
10-100x faster response times
Costs 2 credits (worth it for real-time data)
Built for live dashboards and real-time applications

Authorization

string

default:"Bearer "

required

Your API key for authentication

Query Parameters

sport

string

Filter by sport nameOptions: soccer, basketball, tennis, baseball, volleyball, american-football, ice-hockey, handballExample: soccer

When filtering by sport, the endpoint is optimized for even faster response times.

locale

string

default:"en"

Language for team, competition, and region names. Supported: en, es, pt

Response

data

array

Array of live event objects

count

integer

Total number of live events returned

Event Object

The response format is identical to the /v2/matches endpoint, with the following fields:

string

Unique event IDExample: 43357554

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-14T20:00:00.000Z

status

string

Always live for this endpoint

stats

object

Always present for live events. Contains real-time match statistics including scores, elapsed time, and sport-specific data. All properties are flattened directly on the stats object for optimal performance.

Show Stats Object Structure

stats.homeGoals

integer

Home team score/goals (updated in real-time)

stats.awayGoals

integer

Away team score/goals (updated in real-time)

stats.homeCorners

integer

Home team corners (soccer only)

stats.awayCorners

integer

Away team corners (soccer only)

stats.homeYellowCards

integer

Home team yellow cards (soccer only)

stats.awayYellowCards

integer

Away team yellow cards (soccer only)

stats.homeRedCards

integer

Home team red cards (soccer only)

stats.awayRedCards

integer

Away team red cards (soccer only)

stats.elapsedSeconds

integer

Time elapsed in seconds since match start

stats.phase

string

Current match phaseSoccer: 1ST_HALF, HALF_TIME, 2ND_HALF, EXTRA_TIME, etc.

stats.phaseCaption

string

Human-readable time displayExample: 45:00, 67:32

stats.isLive

boolean

Whether the event is currently in play

stats.isInPlay

boolean

Whether betting is available (false during stoppages)

liveBetItems

array

Live betting odds for this event with price tracking

Show Live Bet Item Structure

betItemId

string

Unique bet item identifier

marketSysname

string

Market type (e.g., SOCCER_MATCH_RESULT, SOCCER_UNDER_OVER)

marketCaption

string

Human-readable market name

code

string

Bet code (1, X, 2, O, U, etc.)

caption

string

Bet description

price

number

Current odds

priceChange

number

Change from previous update (null if first update)

isAvailable

boolean

Whether betting is currently available

timestamp

string

When this price was captured

homeTeam

object

Home team details (localized)

awayTeam

object

Away team details (localized)

competition

object

Competition details (localized)

region

object

Region details (localized)

markets

array

Available betting markets with odds

Example Request

curl -H "Authorization: Bearer sk_live_..." \
  "https://api.mrdoge.co/v2/matches/live?locale=en"

Response

{
  "data": [
    {
      "id": "43357554",
      "startDateTime": "2025-11-14T20:00:00.000Z",
      "status": "live",
      "competitionId": 847,
      "sportId": 1,
      "regionId": 6,
      "views": 234,
      "sport": {
        "id": 1,
        "name": "soccer"
      },
      "homeTeam": {
        "id": 95450,
        "name": "Arsenal"
      },
      "awayTeam": {
        "id": 11045,
        "name": "Liverpool"
      },
      "competition": {
        "id": 847,
        "caption": "Premier League"
      },
      "region": {
        "id": 6,
        "caption": "England"
      },
      "stats": {
        "id": "stats_123",
        "homeGoals": 2,
        "awayGoals": 1,
        "homeCorners": 5,
        "awayCorners": 3,
        "homeYellowCards": 2,
        "awayYellowCards": 1,
        "homeRedCards": 0,
        "awayRedCards": 0,
        "elapsedSeconds": 2820,
        "phaseCaptionLong": "2T",
        "phaseCaption": "47:00",
        "referenceTime": "2025-11-14T20:47:00.000Z",
        "isLive": true,
        "isInPlay": true,
        "liveBetItems": [
            {
              "betItemId": "6234567890",
              "marketSysname": "SOCCER_MATCH_RESULT",
              "marketCaption": "Match Result",
              "code": "1",
              "caption": "Arsenal",
              "price": 1.45,
              "priceChange": -0.05,
              "isAvailable": true,
              "timestamp": "1731612847000"
            },
            {
              "betItemId": "6234567891",
              "marketSysname": "SOCCER_MATCH_RESULT",
              "marketCaption": "Match Result",
              "code": "X",
              "caption": "Draw",
              "price": 4.2,
              "priceChange": 0.1,
              "isAvailable": true,
              "timestamp": "1731612847000"
            },
            {
              "betItemId": "6234567892",
              "marketSysname": "SOCCER_MATCH_RESULT",
              "marketCaption": "Match Result",
              "code": "2",
              "caption": "Liverpool",
              "price": 6.5,
              "priceChange": 0.3,
              "isAvailable": true,
              "timestamp": "1731612847000"
            }
          ]
      },
      "markets": [
        {
          "id": "1488408114",
          "eventId": "43357554",
          "betTypeSysname": "SOCCER_MATCH_RESULT",
          "betItems": [
            {
              "id": "6234567890",
              "code": "1",
              "caption": "Arsenal",
              "price": 1.45,
              "oddsText": "1.45",
              "isAvailable": true
            }
          ]
        }
      ]
    }
  ],
  "count": 1
}

Performance Characteristics

This endpoint is optimized for high-frequency polling and real-time applications:

Response Time

Sub-secondFast response times even with dozens of live events

Update Frequency

Every 30 secondsLive data refreshed continuously as matches progress

Reliability

Highly availableHandles halftime breaks, delays, and interruptions gracefully

Scalability

High throughputSupports unlimited concurrent requests

Use Cases

Live Scores Widget

Display real-time scores and stats on your site

Live Betting Interface

Show live odds with price movement tracking

Event Monitoring

Track multiple live events simultaneously

Push Notifications

Trigger alerts on score changes or odds movements

Migration Guide

If you’re currently using /v2/matches?status=live, here’s how to migrate:

Before (General Events Endpoint)

// Static list, no live data
const response = await fetch(
  'https://api.mrdoge.co/v2/matches?status=live&locale=en',
  { headers: { 'Authorization': 'Bearer sk_live_...' } }
);
// Cost: 1 credit
// Returns: Event IDs and names only (no stats/odds)
// Use case: "Live Now" badge, event list

After (Dedicated Live Events Endpoint)

// Real-time data with scores and odds
const response = await fetch(
  'https://api.mrdoge.co/v2/matches/live?locale=en',
  { headers: { 'Authorization': 'Bearer sk_live_...' } }
);
// Cost: 2 credits
// Returns: Live scores, odds, stats, phase, elapsed time (updated every 30s)
// Use case: Live dashboard, real-time scores

When to Use Each Endpoint

Scenario	Use `/v2/matches/live`	Use `/v2/matches?status=live`
Real-time live scores dashboard	Yes	No
Live odds and price tracking	Yes	No
Polling every 30-60 seconds	Yes	No
Static “Live Now” list (no scores)	No	Yes
Mixed upcoming + live + completed	No	Yes
Budget-conscious single fetch	No	Yes
High-frequency updates	Yes	No
Need final scores for completed events	No	Yes (use `status=completed`)

Error Responses

error

object

Error details if request fails

Show Common Errors

401 Unauthorized

{
  "statusCode": 401,
  "message": "Invalid API key"
}

403 Forbidden

{
  "statusCode": 403,
  "message": "Insufficient permissions. Requires: read:live-events"
}

429 Too Many Requests

{
  "statusCode": 429,
  "message": "Rate limit exceeded. PRO tier allows 1000 requests/minute."
}

Authorizations

Authorization

string

header

required

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

Query Parameters

limit

string

Maximum number of live events to return

Example:

"20"

prioritize

enum<string>

Smart sorting (popular leagues first)

Available options:

true,

false

Response

List of live 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"

data.liveEventData

object[]

Show child attributes

data.liveEventData.eventId

string

data.liveEventData.phaseSysname

string

Example:

"SOCCER_MATCH_SECOND_HALF"

data.liveEventData.isLive

boolean

Example:

true

data.liveEventData.liveDataJson

object

Sport-specific live data (scores, statistics, etc.)

Sports Endpoints

AI Endpoints

Core Utilities

Authorization

Query Parameters

Response

Event Object

Example Request

Response

Performance Characteristics

Response Time

Update Frequency

Reliability

Scalability

Use Cases

Live Scores Widget

Live Betting Interface

Event Monitoring

Push Notifications

Migration Guide

Before (General Events Endpoint)

After (Dedicated Live Events Endpoint)

When to Use Each Endpoint

Error Responses

Authorizations

Query Parameters

Response

Sports Endpoints

AI Endpoints

Core Utilities

​Authorization

​Query Parameters

​Response

​Event Object

​Example Request

​Response

​Performance Characteristics

Response Time

Update Frequency

Reliability

Scalability

​Use Cases

Live Scores Widget

Live Betting Interface

Event Monitoring

Push Notifications

​Migration Guide

​Before (General Events Endpoint)

​After (Dedicated Live Events Endpoint)

​When to Use Each Endpoint

​Error Responses

Authorizations

Query Parameters

Response

Authorization

Query Parameters

Response

Event Object

Example Request

Response

Performance Characteristics

Use Cases

Migration Guide

Before (General Events Endpoint)

After (Dedicated Live Events Endpoint)

When to Use Each Endpoint

Error Responses