Livescores

Included in all plans

Livescore data is available on all base plans (Starter, Growth, Pro, Enterprise) at no additional cost. Plans differ in the number of accessible leagues and hourly API call limits.

Compare plans →

Quick summary: This tutorial covers the three livescore endpoints, when to use each one, how to enrich real-time responses, and how to filter by specific leagues or fixtures. It also explains when fixtures are the better choice.

What you'll learn:

• The difference between the three livescore endpoints and when to use each

• How to enrich livescore responses with scores, events, and team data

• How to filter livescores by league or fixture ID

• When to switch from livescores to fixtures

Time to complete: 15 minutes Skill level: Beginner Prerequisites: Authentication, Includes, Filter and Select Fields

1. When to use this feature

Livescores are optimised for tracking active matches in real time. They return the same data structure as fixtures, but only cover matches within a 15-minute window around kickoff, from 15 minutes before the match starts to 15 minutes after it ends.

Livescores vs fixtures: when to use what

Use case	Use	Why
Live match tracker or scoreboard	Livescores	Lightweight payload, updated frequently, only active matches
Match detail page	Fixtures	Complete information: venue, officials, detailed metadata
Pre-match information	Fixtures	Livescores only populate 15 minutes before kickoff
Post-match analysis	Fixtures	Full statistics and detailed data
Historical matches	Fixtures	Livescores are not available outside the match window

Recommended workflow: Use livescores for real-time updates in your live tracker. Switch to the full fixture endpoint when a user clicks for match details or when the match ends.

Real-world use cases

Use case 1: Live scoreboard widget You're building a widget that shows all currently active matches with live scores, match minutes, and events. The GET All Inplay Livescores endpoint gives you exactly this, only matches that are live right now (or about to kick off within 15 minutes).

Use case 2: Today's match schedule You want to show all matches happening today, including those that haven't started yet. GET All Livescores (without the /inplay suffix) returns all fixtures for the current day.

Use case 3: Incremental live updates You're polling frequently and want to minimise payload size. GET Latest Updated Livescores returns only the matches that received a data update within the last 10 seconds, goals, cards, substitutions, and score changes.

When NOT to use this feature

• Past or future matches : Livescores are not available outside the 15-minute match window. Use Fixtures instead.

• Complete match metadata : Livescores return a lean response. For venue, officials, and detailed match data, fetch the full fixture by ID using the same id field in the response.

2. How to retrieve data

Understanding the endpoints

Base URL:

https://api.sportmonks.com/v3/football/livescores

Available endpoints:

Endpoint	Path suffix	Description
GET All Inplay Livescores	/inplay	Only matches currently in play (±15 min window before and after the match)
GET All Livescores	(base URL)	All fixtures for the current day
GET Latest Updated Livescores	/latest	Fixtures updated in the last 10 seconds

Available parameters:

Parameter	Type	Required	Description	Example
api_token	string	Yes	Your API authentication token	YOUR_API_TOKEN
include	string	No	Related data to attach to the response	scores;participants;events
select	string	No	Specific fields to return	name,starting_at
filters	string	No	Filter results by league or fixture ID	fixtureLeagues:172

Step-by-step implementation

Step 1: GET All Inplay Livescores

Returns all fixtures currently in the livescore window (15 minutes before kickoff) through 15 minutes after the final whistle.

JavaScript:

Javascript

const apiToken = 'YOUR_API_TOKEN';

async function getInplayLivescores() {
  const response = await fetch(
    `https://api.sportmonks.com/v3/football/livescores/inplay?api_token=${apiToken}`
  );
  return response.json();
}

Python

PHP

Free plan note: If you're on the free plan, the inplay response will contain matches from the Danish Superliga and Scottish Premiership only.

Step 2: GET All Livescores

Returns all fixtures for the current day, including matches that have not yet kicked off. This is the right endpoint for a full today's matches view.

https://api.sportmonks.com/v3/football/livescores
?api_token=YOUR_API_TOKEN

The response uses the same data structure as fixtures. The number of results will be higher than the inplay endpoint.

Step 3: GET Latest Updated Livescores

Returns only the livescores that received a data update within the last 10 seconds. This is the most efficient endpoint for high-frequency polling, you only process what changed.

https://api.sportmonks.com/v3/football/livescores/latest
?api_token=YOUR_API_TOKEN

JavaScript:

async function pollLatestLivescores(intervalMs = 10000) {
  const poll = async () => {
    const response = await fetch(
      `https://api.sportmonks.com/v3/football/livescores/latest?api_token=${apiToken}`
    );
    const data = await response.json();
    processUpdates(data.data);
  };

  setInterval(poll, intervalMs);
}

Do not poll faster than 10 seconds. The endpoint updates on a 10-second cycle, and more frequent requests will produce duplicate data while consuming your rate limit.

Step 4: Adding includes

Livescore responses return only IDs and basic match data by default. Use include to attach scores, teams, events, and other related data.

https://api.sportmonks.com/v3/football/livescores/inplay
?api_token=YOUR_API_TOKEN&include=scores;participants;statistics.type;events;lineups

The most commonly used includes for livescores are:

• scores : Current and half-time scores

• participants : Home and away team names and logos

• events : Goals, cards, and substitutions as they happen

• statistics.type : Live match stats

• lineups : Starting XI (available once confirmed)

Step 5: Filtering by league

If you only want livescores for a specific league, use the filters parameter with the fixtureLeagues filter. This is especially useful if your plan covers hundreds of leagues but your product focuses on one.

https://api.sportmonks.com/v3/football/livescores/inplay
?api_token=YOUR_API_TOKEN&filters=fixtureLeagues:172&include=participants;scores

Example league IDs: Danish Superliga = 172, Scottish Premiership = 501, English Premier League = 8.

Step 6: Complete example — live tracker

Javascript

class LivescoreTracker {
  constructor(apiToken) {
    this.token = apiToken;
    this.baseURL = 'https://api.sportmonks.com/v3/football/livescores';
  }

  async getInplay(params = {}) {
    const query = new URLSearchParams({ api_token: this.token, ...params });
    const r = await fetch(`${this.baseURL}/inplay?${query}`);
    if (!r.ok) throw new Error(`HTTP ${r.status}`);
    return r.json();
  }

  async getLatest(params = {}) {
    const query = new URLSearchParams({ api_token: this.token, ...params });
    const r = await fetch(`${this.baseURL}/latest?${query}`);
    if (!r.ok) throw new Error(`HTTP ${r.status}`);
    return r.json();
  }

  startPolling(leagueId = null, intervalMs = 10000) {
    const filters = leagueId ? { filters: `fixtureLeagues:${leagueId}` } : {};
    const includes = { include: 'scores;participants;events' };

    const poll = async () => {
      try {
        const data = await this.getLatest({ ...filters, ...includes });
        this.onUpdate(data.data);
      } catch (err) {
        console.error('Livescore poll error:', err.message);
      }
    };

    poll();
    return setInterval(poll, intervalMs);
  }

  onUpdate(fixtures) {
    console.log('Updated fixtures:', fixtures.length);
  }
}

// Usage
const tracker = new LivescoreTracker('YOUR_API_TOKEN');
tracker.startPolling(501);

Python

PHP

3. Working with the data

Understanding the response structure

The livescore response uses the same structure as fixtures. The key fields to monitor during a live match are:

{
  "data": {
    "id": 18535517,
    "sport_id": 1,
    "league_id": 501,
    "season_id": 19735,
    "state_id": 5,
    "name": "Celtic vs Rangers",
    "starting_at": "2022-09-03 11:30:00",
    "result_info": "Celtic won after full-time.",
    "has_odds": true,
    "last_processed_at": "2023-03-02 17:47:38",
    "starting_at_timestamp": 1662204600
  }
}

Fields most relevant to live tracking:

Field	Type	Description
id	integer	Unique fixture ID — use this to fetch full details from the fixtures endpoint
state_id	integer	Current match state (see States reference)
last_processed_at	string	Last time this fixture was updated
result_info	string	Plain-text result summary (null during live matches)

Processing the data

Display a live scoreboard:

const data = await tracker.getInplay({ include: 'scores;participants' });

const scoreboard = data.data.map(fixture => {
  const home = fixture.participants?.find(p => p.meta?.location === 'home');
  const away = fixture.participants?.find(p => p.meta?.location === 'away');
  const score = fixture.scores?.find(s => s.description === 'CURRENT');

  return {
    home: home?.name || 'Home',
    away: away?.name || 'Away',
    score: score ? `${score.score.goals} - ${score.score.participant}` : '0 - 0'
  };
});

Detect goals from events:

const data = await tracker.getLatest({ include: 'events;participants' });

for (const fixture of data.data) {
  const goals = (fixture.events || []).filter(e => e.type_id === 14);
  if (goals.length) {
    console.log(`Goal in ${fixture.name}:`, goals.map(g => g.player_name));
  }
}

4. Common pitfalls

Pitfall 1: Expecting livescores outside the match window

Livescores are unavailable before the 15-minute pre-match window and disappear 15 minutes after the final whistle.

// ❌ Returns nothing for a match starting in 2 hours
const data = await getLivescores();

// ✅ For future matches, use the fixtures endpoint
const upcoming = await fetch('/v3/football/fixtures/date/2026-06-14?api_token=...');

Pitfall 2: Polling the inplay endpoint too frequently

The inplay endpoint is not a WebSocket — it does not push updates. Polling faster than every 10 seconds gives you duplicate data and burns through your rate limit.

// ❌ Too frequent — data does not change this fast
setInterval(fetchInplay, 1000);

// ✅ Use /latest at 10-second intervals instead
setInterval(fetchLatest, 10000);

Pitfall 3: Not accounting for an empty response

Outside of active match windows (e.g. early morning), the inplay endpoint may return an empty data array. Always check before iterating.

// ❌ Will throw if data is empty
const firstName = data.data[0].name;

// ✅ Safe access
if (data.data && data.data.length > 0) {
  console.log('Matches in progress:', data.data.length);
} else {
  console.log('No matches currently live.');
}

---

Pitfall 4: Fetching full fixture data for every livescore update

If you're polling every 10 seconds and making an additional fixture request for each match in the response, you'll exhaust your rate limit quickly.

// ❌ Wrong — N fixture requests per poll cycle
const live = await getLivescores({ include: '' });
for (const match of live.data) {
  const full = await getFixture(match.id, { include: 'scores;events;lineups' });
}

// ✅ Correct — use includes on the livescore request itself
const live = await getLivescores({
  include: 'scores;events;lineups;participants'
})

5. Advanced usage

Advanced technique 1: Hybrid live + detail pattern

Use the livescore /latest endpoint for frequent polling, then fetch the full fixture on demand when a user opens a match detail view.

const poller = setInterval(async () => {
  const updates = await tracker.getLatest({ include: 'scores;events' });
  updateScoreboard(updates.data);
}, 10000);

async function openMatchDetail(fixtureId) {
  clearInterval(poller);
  const detail = await api.getFixture(fixtureId, {
    include: 'scores;participants;events;lineups;statistics.type'
  });
  renderMatchDetail(detail.data);
}

Advanced technique 2: Multi-league filtering with parallel requests

If your product shows multiple leagues with different priorities, fetch them in parallel and merge results.

async function getMultiLeagueLivescores(leagueIds) {
  const requests = leagueIds.map(id =>
    fetch(
      `https://api.sportmonks.com/v3/football/livescores/inplay?api_token=${token}&filters=fixtureLeagues:${id}&include=scores;participants`
    ).then(r => r.json())
  );

  const results = await Promise.all(requests);
  return results.flatMap(r => r.data || []);
}

const fixtures = await getMultiLeagueLivescores([8, 501, 172]);

6. Common errors

401 Unauthorised

Cause: Missing or invalid api_token. Fix: Confirm the token is appended to every request. Find it at MySportmonks.

429 Too Many Requests

Cause: Polling too frequently or making too many enriched requests in parallel. Fix: Switch to the /latest endpoint, reduce polling frequency, and implement exponential backoff. See the Rate Limiting guide.

Empty response (no error, but data: [])

Cause: No matches are currently within the livescore window. This is expected outside of typical match hours. Fix: Handle empty arrays gracefully and show an appropriate message to users.

CORS error (browser only)

Cause: Calling the API directly from the browser exposes your token. Fix: Route all API calls through a backend proxy.

// ✅ Backend proxy (Node.js/Express)
app.get('/api/livescores', async (req, res) => {
  const r = await fetch(
    `https://api.sportmonks.com/v3/football/livescores/inplay?api_token=${process.env.SPORTMONKS_TOKEN}&include=scores;participants`
  );
  res.json(await r.json());
});

See also

Prerequisites

• Authentication : Setting up API access

• Includes : Enriching your responses

• Filter and Select Fields : Filtering by league or fixture

Understanding the full picture

• Fixtures : Complete match data at any time; use for match detail views

• States : Understanding match states (NS, LIVE, HT, FT, etc.)

Building real-time apps

• Rate Limiting : Optimise polling frequency for livescores

• Best Practices : Build efficient livescore applications

• Lineups and Formations : Attach confirmed lineups to your live view

Related endpoints

• Livescores Endpoints : API endpoint reference

• Fixtures Endpoints : Access complete fixture data

8. FAQ

Q: What does the 15-minute window mean exactly?

A match appears in the livescore endpoints from 15 minutes before its scheduled kickoff time and remains there until 15 minutes after the final whistle. Outside this window, use the fixtures endpoint with the match ID to access the data.

Q: Why is my livescore response empty even though there are matches today?

Either no matches in your subscription are currently within the 15-minute window, or you're using the /inplay endpoint (which only shows active matches) rather than the base livescores endpoint (which shows all of today's fixtures).

Q: The livescore response looks the same as a fixture. What's the difference?

The data structure is identical. Livescores are a filtered, real-time view of the fixtures data, optimised for polling during active matches. Any livescore record can be fetched at any time via the fixtures endpoint using the same id.

Q: How do I show the current score?

Include scores in your request and look for the entry with description: "CURRENT" in the scores array.

Q: Is livescore data available on all plans?

Yes. All plans include livescore access. The difference is which leagues are available based on your plan. Check your subscription via MySportmonks.

Best practices summary

✅ DO:

• Use /latest for high-frequency polling, it returns only what changed

• Use filters=fixtureLeagues:{id} to narrow results to leagues you care about

• Include scores;participants;events in your live requests to avoid follow-up calls

• Handle empty responses gracefully

• Switch to the fixtures endpoint for match details

❌ DON'T:

• Poll more frequently than every 10 seconds

• Use livescores for past or future match data

• Make additional fixture requests per match inside your polling loop

• Expose your API token in frontend JavaScript

• Assume the response will always contain data