States

What does the include do?

The state include allows you to retrieve comprehensive information about the current state of a fixture. The state indicates the exact phase of the match - whether it's scheduled, live, finished, postponed, cancelled, or in any other specific state. This is essential for properly displaying match status and handling different scenarios in your application.

Why use states?

The state include is crucial for:

• Match status display: Show accurate status (Live, Finished, Postponed, etc.)

• Real-time filtering: Filter fixtures by state (e.g., show only live matches)

• Notification systems: Trigger alerts when matches change state

• Data synchronisation: Know when to refresh match data

• Error handling: Handle postponed, cancelled, or interrupted matches

• User experience: Provide contextual information based on match state

Requesting states

To retrieve state information for a fixture, use the following include:

https://api.sportmonks.com/v3/football/fixtures
?api_token=YOUR_TOKEN&include=state

Or for a specific fixture:

https://api.sportmonks.com/v3/football/fixtures/{fixture_id}
?api_token=YOUR_TOKEN&include=state

Response structure

When you include state in your request, you'll receive a state object:

{
   "data": {
    "id": 19568462,
    "sport_id": 1,
    "league_id": 2,
    "season_id": 25580,
    "stage_id": 77478049,
    "group_id": null,
    "aggregate_id": null,
    "round_id": 388953,
    "state_id": 5,
    "venue_id": 204,
    "name": "Arsenal vs FC Bayern M\u00fcnchen",
    "starting_at": "2025-11-26 20:00:00",
    "result_info": "Arsenal won after full-time.",
    "leg": "1\/1",
    "details": null,
    "length": 90,
    "placeholder": false,
    "has_odds": true,
    "has_premium_odds": true,
    "starting_at_timestamp": 1764187200,
    "state": {
      "id": 5,
      "state": "FT",
      "name": "Full Time",
      "short_name": "FT",
      "developer_name": "FT"
    }
  }
}

Field descriptions

Field	Type	Description
id	integer	Unique identifier for this state
state	string	Short code for the state (e.g., "FT", "LIVE", "NS")
name	string	Full descriptive name of the state
short_name	string	Short display name for the state
developer_name	string	Programming-friendly name (uppercase, underscores)

Complete list of fixture states

ID	State Code	Name	Description
1	NS	Not Started	Fixture is scheduled but hasn't begun
2	LIVE	Live	Match is currently in progress (1st half)
3	HT	Half Time	Match is at half time break
4	FT	Full Time	Match has finished (90 minutes completed)
5	FT	Full Time	Match finished after regular time
6	AET	After Extra Time	Match finished after extra time
7	PEN_LIVE	Penalty Shootout Live	Penalty shootout in progress
8	FT_PEN	Full Time (Penalties)	Match decided by penalties
9	BREAK	Break Time	Extra time break
10	ET	Extra Time	Extra time in progress
11	AWARDED	Awarded	Winner decided externally (walkover)
12	CANCL	Cancelled	Match cancelled before starting
13	POSTP	Postponed	Match postponed to another date
14	INT	Interrupted	Match interrupted (weather, crowd issues)
15	ABAN	Abandoned	Match abandoned after starting
16	SUSP	Suspended	Match suspended temporarily
17	DELAYED	Delayed	Match start delayed
18	TBA	To Be Announced	Schedule not confirmed
19	AU	Awaiting Updates	Waiting for data updates
21	Deleted	Deleted	Fixture removed from API

State transitions and flow

Understanding how states transition is crucial for building robust applications:

Normal match flow

NS (Not Started)
  ↓ Match starts
LIVE (1st Half)
  ↓ Half-time whistle
HT (Half Time)
  ↓ 2nd half starts
LIVE (2nd Half)
  ↓ Full-time whistle
FT (Full Time)

Match with extra time

FT (After 90 minutes)
  ↓ Extra time starts
ET (Extra Time 1st Half)
  ↓ Break
BREAK (Extra Time Half Time)
  ↓ Extra time 2nd half
ET (Extra Time 2nd Half)
  ↓ Finished
AET (After Extra Time)

Match with penalties

AET (After Extra Time)
  ↓ Penalties start
PEN_LIVE (Penalty Shootout)
  ↓ Shootout complete
FT_PEN (Finished on Penalties)

Problem states

NS (Not Started)
  ↓ Issues arise
DELAYED → (eventually) → LIVE or POSTP
POSTP → (rescheduled) → NS
CANCL → (no transition, final state)

LIVE (During match)
  ↓ Issues arise
INT (Interrupted) → (may resume) → LIVE
SUSP (Suspended) → (may resume) → LIVE
ABAN (Abandoned) → (no transition, final state)

Filtering by state

To filter fixtures based on specific states, use the filters parameter:

https://api.sportmonks.com/v3/football/fixtures
?api_token=YOUR_TOKEN&include=state&filters=fixtureStates:2

Filter for multiple states:

https://api.sportmonks.com/v3/football/fixtures
?api_token=YOUR_TOKEN&include=state&filters=fixtureStates:2,3,10

Common Filter Scenarios

Get only live matches:

&filters=fixtureStates:2,10,7

States: LIVE (2), ET (10), PEN_LIVE (7)

Get finished matches:

&filters=fixtureStates:5,6,8

States: FT (5), AET (6), FT_PEN (8)

Get problem matches:

&filters=fixtureStates:11,12,15,16,18

States: SUSP (11), CANCELLED (12), ABANDONED (15), DELAYED (16), INTERRUPTED (18).

Nested includes

state.type

Get detailed type information for the state:

https://api.sportmonks.com/v3/football/fixtures/{fixture_id}
?api_token=YOUR_TOKEN&include=state.type

This returns additional type metadata (though state itself is typically sufficient).

Code examples

Python example

import requests

# API configuration
API_TOKEN = "YOUR_TOKEN"

# Get all live fixtures
def get_live_fixtures():
    """Get all currently live matches"""
    url = "https://api.sportmonks.com/v3/football/fixtures"
    params = {
        "api_token": API_TOKEN,
        "include": "state,participants",
        "filters": "fixtureStates:2,10,7"  # LIVE, ET, PEN_LIVE
    }
    
    response = requests.get(url, params=params)
    data = response.json()
    
    fixtures = data.get('data', [])
    
    print(f"🔴 {len(fixtures)} live matches found:\n")
    
    for fixture in fixtures:
        state = fixture.get('state', {})
        print(f"{fixture['name']}")
        print(f"  Status: {state['name']} ({state['state']})")
        print()
    
    return fixtures

# Check specific fixture state
def check_fixture_state(fixture_id):
    """Check the state of a specific fixture"""
    url = f"https://api.sportmonks.com/v3/football/fixtures/{fixture_id}"
    params = {
        "api_token": API_TOKEN,
        "include": "state"
    }
    
    response = requests.get(url, params=params)
    data = response.json()
    
    fixture = data['data']
    state = fixture.get('state', {})
    
    return {
        'fixture_id': fixture_id,
        'fixture_name': fixture['name'],
        'state_id': state['id'],
        'state_code': state['state'],
        'state_name': state['name'],
        'is_live': state['id'] in [2, 10, 7],
        'is_finished': state['id'] in [5, 6, 8],
        'has_problem': state['id'] in [12, 13, 14, 15, 16, 17]
    }

# Monitor state changes
def monitor_fixtures(fixture_ids, callback):
    """Monitor fixtures for state changes"""
    previous_states = {}
    
    url = "https://api.sportmonks.com/v3/football/fixtures/multi/" + ",".join(map(str, fixture_ids))
    params = {
        "api_token": API_TOKEN,
        "include": "state"
    }
    
    response = requests.get(url, params=params)
    data = response.json()
    
    for fixture in data.get('data', []):
        fixture_id = fixture['id']
        current_state = fixture['state']['id']
        
        if fixture_id in previous_states:
            if previous_states[fixture_id] != current_state:
                # State changed!
                callback(fixture, previous_states[fixture_id], current_state)
        
        previous_states[fixture_id] = current_state

# Get fixtures with problems
def get_problem_fixtures():
    """Get all postponed, cancelled, or problematic fixtures"""
    url = "https://api.sportmonks.com/v3/football/fixtures"
    params = {
        "api_token": API_TOKEN,
        "include": "state,participants",
        "filters": "fixtureStates:12;13;14;15;16;17"  # Problem states
    }
    
    response = requests.get(url, params=params)
    data = response.json()
    
    fixtures = data.get('data', [])
    
    # Group by state type
    by_state = {}
    for fixture in fixtures:
        state_name = fixture['state']['name']
        if state_name not in by_state:
            by_state[state_name] = []
        by_state[state_name].append(fixture)
    
    print("⚠️  Problem Fixtures:\n")
    for state_name, matches in by_state.items():
        print(f"{state_name}: {len(matches)} matches")
        for match in matches:
            print(f"  - {match['name']}")
        print()
    
    return by_state

# Categorise fixtures by state
def categorise_fixtures_by_state(fixtures):
    """Categorise fixtures into groups based on state"""
    categories = {
        'upcoming': [],
        'live': [],
        'finished': [],
        'postponed': [],
        'cancelled': [],
        'other': []
    }
    
    for fixture in fixtures:
        state_id = fixture['state']['id']
        
        if state_id == 1:  # Not Started
            categories['upcoming'].append(fixture)
        elif state_id in [2, 10, 7]:  # LIVE, ET, PEN_LIVE
            categories['live'].append(fixture)
        elif state_id in [5, 6, 8]:  # FT, AET, FT_PEN
            categories['finished'].append(fixture)
        elif state_id == 13:  # Postponed
            categories['postponed'].append(fixture)
        elif state_id == 12:  # Cancelled
            categories['cancelled'].append(fixture)
        else:
            categories['other'].append(fixture)
    
    return categories

# Example usage
live_matches = get_live_fixtures()
fixture_state = check_fixture_state(18535517)
print(f"Fixture state: {fixture_state}")
problem_fixtures = get_problem_fixtures()

JavaScript Example

// API configuration
const API_TOKEN = "YOUR_TOKEN";

// Get all live fixtures
async function getLiveFixtures() {
    const url = "https://api.sportmonks.com/v3/football/fixtures";
    const params = new URLSearchParams({
        api_token: API_TOKEN,
        include: "state,participants",
        filters: "fixtureStates:2,10,7" // LIVE, ET, PEN_LIVE
    });

    try {
        const response = await fetch(`${url}?${params}`);
        const data = await response.json();
        const fixtures = data.data || [];
        
        console.log(`🔴 ${fixtures.length} live matches found:\n`);
        
        fixtures.forEach(fixture => {
            const state = fixture.state || {};
            console.log(`${fixture.name}`);
            console.log(`  Status: ${state.name} (${state.state})`);
            console.log();
        });
        
        return fixtures;
    } catch (error) {
        console.error("Error fetching live fixtures:", error);
        return [];
    }
}

// Check specific fixture state
async function checkFixtureState(fixtureId) {
    const url = `https://api.sportmonks.com/v3/football/fixtures/${fixtureId}`;
    const params = new URLSearchParams({
        api_token: API_TOKEN,
        include: "state"
    });

    try {
        const response = await fetch(`${url}?${params}`);
        const data = await response.json();
        const fixture = data.data;
        const state = fixture.state || {};
        
        return {
            fixture_id: fixtureId,
            fixture_name: fixture.name,
            state_id: state.id,
            state_code: state.state,
            state_name: state.name,
            is_live: [2, 10, 7].includes(state.id),
            is_finished: [5, 6, 8].includes(state.id),
            has_problem: [12, 13, 14, 15, 16, 17].includes(state.id)
        };
    } catch (error) {
        console.error("Error checking fixture state:", error);
        return null;
    }
}

// Display state badge
function createStateBadge(state) {
    const badge = document.createElement('span');
    badge.className = `state-badge state-${state.state.toLowerCase()}`;
    
    // Color coding
    const colors = {
        'LIVE': '#ff0000',
        'FT': '#28a745',
        'HT': '#ffc107',
        'POSTP': '#6c757d',
        'CANCL': '#dc3545'
    };
    
    badge.style.backgroundColor = colors[state.state] || '#6c757d';
    badge.style.color = 'white';
    badge.style.padding = '4px 8px';
    badge.style.borderRadius = '4px';
    badge.style.fontWeight = 'bold';
    badge.textContent = state.short_name;
    
    return badge;
}

// Get fixtures with problems
async function getProblemFixtures() {
    const url = "https://api.sportmonks.com/v3/football/fixtures";
    const params = new URLSearchParams({
        api_token: API_TOKEN,
        include: "state,participants",
        filters: "fixtureStates:12;13;14;15;16;17" // Problem states
    });

    try {
        const response = await fetch(`${url}?${params}`);
        const data = await response.json();
        const fixtures = data.data || [];
        
        // Group by state
        const byState = {};
        fixtures.forEach(fixture => {
            const stateName = fixture.state.name;
            if (!byState[stateName]) {
                byState[stateName] = [];
            }
            byState[stateName].push(fixture);
        });
        
        console.log("⚠️  Problem Fixtures:\n");
        Object.entries(byState).forEach(([stateName, matches]) => {
            console.log(`${stateName}: ${matches.length} matches`);
            matches.forEach(match => {
                console.log(`  - ${match.name}`);
            });
            console.log();
        });
        
        return byState;
    } catch (error) {
        console.error("Error fetching problem fixtures:", error);
        return {};
    }
}

// Categorise fixtures
function categoriseFixturesByState(fixtures) {
    const categories = {
        upcoming: [],
        live: [],
        finished: [],
        postponed: [],
        cancelled: [],
        other: []
    };
    
    fixtures.forEach(fixture => {
        const stateId = fixture.state.id;
        
        if (stateId === 1) {
            categories.upcoming.push(fixture);
        } else if ([2, 10, 7].includes(stateId)) {
            categories.live.push(fixture);
        } else if ([5, 6, 8].includes(stateId)) {
            categories.finished.push(fixture);
        } else if (stateId === 13) {
            categories.postponed.push(fixture);
        } else if (stateId === 12) {
            categories.cancelled.push(fixture);
        } else {
            categories.other.push(fixture);
        }
    });
    
    return categories;
}

// Build fixtures list with state indicators
function buildFixturesList(fixtures) {
    const container = document.createElement('div');
    container.className = 'fixtures-list';
    
    const categories = categoriseFixturesByState(fixtures);
    
    // Display by category
    Object.entries(categories).forEach(([category, matches]) => {
        if (matches.length > 0) {
            const section = document.createElement('div');
            section.className = 'fixture-category';
            section.innerHTML = `<h3>${category.toUpperCase()} (${matches.length})</h3>`;
            
            matches.forEach(fixture => {
                const item = document.createElement('div');
                item.className = 'fixture-item';
                item.appendChild(createStateBadge(fixture.state));
                item.innerHTML += ` ${fixture.name}`;
                section.appendChild(item);
            });
            
            container.appendChild(section);
        }
    });
    
    document.body.appendChild(container);
}

// Run examples
getLiveFixtures();
checkFixtureState(18535517).then(state => console.log("Fixture state:", state));
getProblemFixtures();

Common use cases

1. Live match filtering

Show only matches that are currently live:

def is_match_live(state_id):
    return state_id in [2, 10, 7]  # LIVE, ET, PEN_LIVE

2. State-based notifications

Send notifications when states change:

def should_notify(old_state, new_state):
    notifications = {
        (1, 2): "Match started!",
        (2, 3): "Half time",
        (3, 2): "Second half started",
        (2, 5): "Full time",
        (1, 13): "Match postponed",
        (1, 12): "Match cancelled"
    }
    return notifications.get((old_state, new_state))

3. Data refresh strategy

Determine when to refresh data based on state:

def get_refresh_interval(state_id):
    """Get appropriate refresh interval in seconds"""
    if state_id in [2, 10, 7]:  # Live states
        return 30  # Refresh every 30 seconds
    elif state_id in [1]:  # Not started
        return 300  # Refresh every 5 minutes
    elif state_id in [5, 6, 8]:  # Finished
        return None  # No need to refresh
    else:
        return 600  # Check every 10 minutes

Best practices

1. Always include state for fixtures: State is essential for proper match display and handling.

2. Use state IDs, not names: State IDs are more reliable than text names which may change.

3. Handle problem states gracefully: Show appropriate messages for postponed, cancelled, or interrupted matches.

4. Filter efficiently: Use state filters in API requests rather than filtering after fetching.

5. Monitor state transitions: For live applications, track when states change to trigger updates.

6. Cache finished matches: Once a match reaches FT/AET/FT_PEN, its state won't change.

7. Consider ALL live states: Don't just check for state ID 2 (LIVE). Include extra time (10) and penalties (7).

Related includes

• Periods - Period information complements state data

• Events - Event data should be interpreted with state context

• Scores - Scores are most meaningful with state information

Summary

The state include provides essential match status information with 21 different states covering all possible fixture scenarios from scheduled to finished, including problem states like postponed and cancelled. Understanding state transitions and using state-based filtering enables robust match tracking, proper data refresh strategies, and excellent user experiences. Always check state before displaying match data or determining refresh intervals.