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

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

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).
  • Images — logo/photo URLs are third-party media links; they may require attribution or usage limits under provider terms.

Available tools

  • search_competitions

    Search football leagues, cups, and competitions. Use when you need a competition_id, available seasons, or coverage info. Do not use for fixtures or standings.

  • get_competition_seasons

    List available seasons for a competition, including date ranges and coverage. Use after search_competitions when you need season years.

  • search_teams

    Search football teams by name, ID, competition+season, country, or venue. Requires at least one filter. Do not use for squads or fixtures.

  • get_team

    Get a normalized team profile including venue details when available.

  • get_team_squad

    List the current squad for a team (players, numbers, positions). Prefer this over searching every player individually.

  • search_players

    Search players by name, ID, team, or competition. Season is required for most searches. Use get_player for a single profile.

  • get_player

    Get a normalized player profile. Pass season when you need season-specific team/position context.

  • get_player_statistics

    Season statistics for a player (goals, assists, minutes, cards, etc.). Requires player_id and season.

  • search_fixtures

    Search fixtures by date, competition, team, status, last/next N, or fixture_id. For live matches use get_live_fixtures. For two-team history use get_head_to_head.

  • get_live_fixtures

    Return currently live matches. Optionally filter by competition IDs. Cached briefly (~20s).

  • get_fixture

    Get a single fixture summary (teams, score, status, venue). Does not include events, lineups, or detailed statistics — use dedicated tools for those.

  • get_fixture_events

    Match events (goals, cards, substitutions, VAR) sorted chronologically.

  • get_fixture_lineups

    Starting elevens, substitutes, formations, and coaches for a fixture.

  • get_fixture_statistics

    Team-level match statistics (possession, shots, passes, cards, etc.). Values keep original units/labels.

  • get_fixture_player_statistics

    Per-player performance statistics for a fixture.

  • get_standings

    League table / standings for a competition and season. Supports multi-group competitions.

  • get_top_scorers

    Top scorers for a competition season.

  • get_top_assists

    Top assists for a competition season.

  • get_injuries

    Player injuries/sidelined status. Requires at least one filter (team, player, competition+season, fixture, or date).

  • get_transfers

    Transfer history for exactly one player_id or team_id. Newest first.

  • get_head_to_head

    Historical fixtures between two teams. Prefer this over search-fixtures when comparing two clubs.

  • search_venues

    Search stadiums/venues by name, ID, city, or country.

  • search_coaches

    Search coaches by name, ID, or current team. Includes career history when available.

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

Create account Documentation