stackgate.ai
All integrations
API-Football

Football

Access football fixtures, live scores, leagues, standings, teams, players, lineups, match events, statistics, injuries, transfers and other football data.

Manual setup 23 tools

Example questions

Try asking your AI client

  • Show me the current Premier League standings.

  • When does Liverpool play next, and who is injured?

  • Did Brøndby ever get a result against Copenhagen this season?

  • Who are the top scorers in the Superliga right now?

  • Write a short match preview for Saturday - do not treat it as a bet.

Overview

Connect Football so AI clients can retrieve football competitions, teams, players, fixtures, live scores, standings, lineups, match events, statistics, injuries, transfers, venues, and coaches.

stackgate.ai stores your API-Sports (API-Football) API key encrypted and calls the provider on your behalf. Tool results are returned to your AI client for that request. Responses are cached briefly on the hub (by connection) to reduce duplicate upstream calls and protect your daily quota.

This integration is read-only. Public tool names and response shapes are provider-neutral; the initial upstream provider is API-Football by API-Sports.

Prerequisites

Getting credentials

  1. Sign in to stackgate.ai.
  2. Go to My Integrations and open Football.
  3. In a separate tab, open the API-Football dashboard.
  4. Go to Account → My Access and copy your API key.
  5. Paste the key into stackgate.ai and click Save.
  6. stackgate.ai runs a lightweight connection test (/status). On success you may see your plan name and daily request limit.
  7. Optionally use Edit tool access to limit which read tools the connection may use.

Use dashboard keys for https://v3.football.api-sports.io (header x-apisports-key). RapidAPI host/key pairs are not supported in this integration.

Treat the API key like a password. Regenerate it in the API-Sports dashboard if it is exposed.

Using with AI clients

  • Dedicated endpoint: POST /mcp/football with a Sanctum bearer token
  • Private gateway: one config for all integrations — use football__* namespaced tools

See Documentation for HTTP authentication and private gateway setup.

Example prompts

  • Show me the current Premier League standings.
  • Find Liverpool's next five matches.
  • Who are the top scorers in the current Bundesliga season?
  • Show the lineup and events from fixture 12345.
  • Find information about Christian Eriksen.
  • Compare the latest matches between Arsenal and Chelsea.
  • Which matches are currently live?
  • Show the players in FC Copenhagen's current squad.

Suggested workflow

  1. search_competitions - resolve competition_id (Premier League is often 39).
  2. get_standings / search_fixtures - many queries need season as YYYY (starting year).
  3. get_live_fixtures - in-play matches only.
  4. get_fixture - summary; use events/lineups/statistics tools for detail.
  5. search_teams / search_players - then get tools for profiles. Use letters, numbers, and spaces in name search.

Pagination

Where the provider paginates (for example players), pass page and optionally limit. Responses include pagination with page, total_pages, total_results, and has_more. The hub does not auto-fetch every page.

Caching and freshness

Approximate hub cache durations (per connection):

Data Cache
Competitions / seasons ~24 hours
Teams / venues / coaches ~12 hours
Players ~6 hours
Squads ~3 hours
Standings / upcoming fixtures ~10 minutes
Completed fixtures ~24 hours
Live fixtures / events ~20 seconds
Lineups ~2 minutes
Injuries ~30 minutes
Transfers ~3 hours

Authentication failures are never cached. Live scores can lag a short cache window.

Rate limits

API-Football plans have a daily request quota and a per-minute cap. Free plans are often around 100 requests/day. Prefer cached tools, specific IDs, and small date windows. A 429 or provider “request limit” error means wait or upgrade your API-Sports plan.

Data licensing notice

stackgate.ai provides access to data returned by the connected provider. Availability and permitted use depend on the provider’s terms and your subscription. A free API plan does not grant unrestricted redistribution rights. Club logos, player photos, venue images, and competition branding may have separate rights restrictions. You are responsible for ensuring usage complies with the provider’s terms and applicable rights. Do not treat this data as open-source or freely redistributable.

Troubleshooting

  • 422 integration not configured — add your API-Sports API key in My Integrations.
  • Connection test failed / invalid key — confirm the key from Account → My Access on the API-Football dashboard (not a RapidAPI key).
  • 401 / authentication failed — regenerate the key and update My Integrations.
  • 429 / request limit — you hit the provider quota; wait, reduce tool calls, or upgrade your plan.
  • Empty items — no matching data for those filters/season, or your plan does not cover that competition/season.
  • season required - many player/team/standings queries need a season year (YYYY, starting year). Free API-Sports plans typically allow 2022-2024.
  • Name search punctuation - query may only use letters, numbers, and spaces (Manchester United, not Man-Utd or F.C. Barcelona). Hyphens and dots are stripped automatically.
  • query + country - do not combine a name search with a country filter.
  • search_players - a name search needs team_id or competition_id plus season. Prefer get_team_squad to list a club.
  • last fixtures - the last parameter is often paid-only; use date or team_id plus season instead.
  • Images - logo/photo URLs are third-party media links; they may require attribution or usage limits under provider terms.

Available tools

  • search_competitions

    Find a competition_id for a league or cup. Use before standings, fixtures, or top scorers. Do not use for teams, players, or live scores. Returns current_season and season_years; call get_competition_seasons for full season coverage.

  • get_competition_seasons

    List every available season year, date range, and coverage flag for one competition. Use after search_competitions when you need a valid season YYYY.

  • search_teams

    Find a team_id by club name, ID, league+season, country, or venue. Requires at least one filter. Do not use for squads (get_team_squad) or fixtures. Name search cannot be combined with country or venue_id.

  • get_team

    Get one club profile (name, country, founded, venue). Requires team_id from search_teams.

  • get_team_squad

    List the current squad (player_id, number, position) for a club. Prefer this over search_players when you need everyone at a team.

  • search_players

    Find a player_id. Name search requires query plus team_id or competition_id plus season. For a known ID use player_id. Prefer get_team_squad to list a club.

  • get_player

    Get one player profile (name, nationality, position, club). Requires player_id and season. Club is chosen from the season row with the most club minutes, not the first international competition.

  • get_player_statistics

    Season stats for one player (goals, assists, minutes, cards) split by competition. Requires player_id and season. Optionally filter to one club or league.

  • search_fixtures

    Search matches by date, team, competition+season, status, or fixture_id. For in-play games use get_live_fixtures. For two clubs use get_head_to_head. Prefer date or team_id+season; last is often unavailable on free plans.

  • get_live_fixtures

    Currently in-play matches only (first half, half-time, second half, extra time). Empty items[] means nothing is live. Cached about 20 seconds. Do not use for today's full schedule (search_fixtures with date).

  • get_fixture

    One match summary: teams, score, status, venue, referee. Does not include events, lineups, or statistics - use the dedicated get_fixture_* tools.

  • get_fixture_events

    Goals, cards, substitutions, and VAR for one match, sorted by minute. Requires fixture_id. Optional filters narrow the list.

  • get_fixture_lineups

    Starting elevens, substitutes, formation, and coach for one match. Requires fixture_id. Usually available close to kickoff.

  • get_fixture_statistics

    Team-level match stats (possession, shots, passes, cards, xG when available). Requires fixture_id. Best after the match has started or finished.

  • get_fixture_player_statistics

    Per-player match stats (minutes, rating, shots, passes). Requires fixture_id. Large payload; pass team_id or player_id when you only need one side or one player.

  • get_standings

    League table for one competition and season (position, points, form). Requires competition_id and season. Supports grouped competitions (World Cup).

  • get_top_scorers

    Top goalscorers for a competition season, including goals, assists, appearances, and minutes. Requires competition_id and season.

  • get_top_assists

    Top assist providers for a competition season, including assists, goals, appearances, and minutes. Requires competition_id and season.

  • get_injuries

    Injured or sidelined players. Prefer date=today (YYYY-MM-DD) for current status. team_id/player_id/competition_id without date require season and can return a large season history (capped by limit, default 25).

  • get_transfers

    Transfer history, newest first. Pass exactly one of player_id or team_id. Club histories are large; default limit is 20. Prefer player_id for a single career.

  • get_head_to_head

    Historical matches between two clubs. Requires both team IDs. Prefer season over last (last is often paid-only). Do not use search_fixtures for two-team history.

  • search_venues

    Find a stadium/venue_id by name, ID, city, or country. Name search allows letters, numbers, and spaces only (Wembley Stadium).

  • search_coaches

    Find a coach by last name, coach_id, or current team_id. Prefer last name only (Guardiola, not Pep Guardiola). Full names fall back to the last word if needed.

MCP endpoint: https://stackgate.ai/mcp/football (HTTP) or via the private gateway.

Create account Documentation