Sports Data

Api sports

Learn how to use Api sports with Composio

Overview

SLUG: API_SPORTS

Description

API-Sports provides comprehensive sports data APIs covering over 2,000 competitions with more than 15 years of historical data, offering real-time updates and easy integration for developers.

Authentication Details

generic_api_key
stringRequired

Connecting to Api sports

Create an auth config

Use the dashboard to create an auth config for the Api sports toolkit. This allows you to connect multiple Api sports accounts to Composio for agents to use.

1

Select App

Navigate to the [Api sports toolkit page](https://app.composio.dev/apps/Api sports) and click “Setup Integration”.

2

Configure Auth Config Settings

Select among the supported auth schemes of and configure them here.

3

Create and Get auth config ID

Click “Create Integration”. After creation, copy the displayed ID starting with ac_. This is your auth config ID. This is not a sensitive ID — you can save it in environment variables or a database. This ID will be used to create connections to the toolkit for a given user.

Connect Your Account

Using API Key

1from composio import Composio
2from composio.types import auth_scheme
3
4# Replace these with your actual values
5api_sports_auth_config_id = "ac_YOUR_API_SPORTS_CONFIG_ID" # Auth config ID created above
6user_id = "0000-0000-0000"  # UUID from database/app
7
8composio = Composio()
9
10def authenticate_toolkit(user_id: str, auth_config_id: str):
11    # Replace this with a method to retrieve an API key from the user.
12    # Or supply your own.
13    user_api_key = input("[!] Enter API key")
14
15    connection_request = composio.connected_accounts.initiate(
16        user_id=user_id,
17        auth_config_id=auth_config_id,
18        config={"auth_scheme": "API_KEY", "val": user_api_key}
19    )
20
21    # API Key authentication is immediate - no redirect needed
22    print(f"Successfully connected Api sports for user {user_id}")
23    print(f"Connection status: {connection_request.status}")
24    
25    return connection_request.id
26
27
28connection_id = authenticate_toolkit(user_id, api_sports_auth_config_id)
29
30# You can verify the connection using:
31connected_account = composio.connected_accounts.get(connection_id)
32print(f"Connected account: {connected_account}")

Tools

Executing tools

Python
1from composio import Composio
2from openai import OpenAI
3import json
4
5openai = OpenAI()
6composio = Composio()
7
8# User ID must be a valid UUID format
9user_id = "0000-0000-0000"  # Replace with actual user UUID from your database
10
11tools = composio.tools.get(user_id=user_id, toolkits=["API_SPORTS"])
12
13print("[!] Tools:")
14print(json.dumps(tools))
15
16def invoke_llm(task = "What can you do?"):
17    completion = openai.chat.completions.create(
18        model="gpt-4o",
19        messages=[
20            {
21                "role": "user",
22                "content": task,  # Your task here!
23            },
24        ],
25        tools=tools,
26    )
27
28    # Handle Result from tool call
29    result = composio.provider.handle_tool_calls(user_id=user_id, response=completion)
30    print(f"[!] Completion: {completion}")
31    print(f"[!] Tool call result: {result}")
32
33invoke_llm()

Tool List

Tool Name: Get fixtures events

Description

Tool to get events (goals, cards, substitutions, var, etc.) from a fixture. use when you need detailed event data after confirming the fixture id.

Action Parameters

fixture
integerRequired
player
integer
team
integer
type
string

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Get Head-to-Head Fixtures

Description

Tool to get head-to-head fixtures between two teams. use after determining team ids to compare their direct match history.

Action Parameters

date
string
from
string
h2h
stringRequired
last
integer
league
integer
next
integer
season
integer
status
string
timezone
string
to
string

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Get Fixture Lineups

Description

Tool to retrieve starting xi and substitutes for a fixture. use after confirming fixture id; optionally filter by team, player, or section (startxi/substitutes). lineups appear ~20-40 minutes before kickoff for supported competitions.

Action Parameters

fixture
integerRequired
player
integer
team
integer
type
string

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Get fixture statistics

Description

Tool to get statistics for a fixture. use when you need detailed match stats (shots, fouls, possession, cards, passes, etc.), optionally filtered by team, statistic type, or including halftime data.

Action Parameters

fixture
integerRequired
half
boolean
team
integer
type
string

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Get Injuries

Description

Tool to get injured or suspended players. use when you need a list of sidelined players filtered by league, season, fixture, team, player, date, ids, or timezone.

Action Parameters

date
string
fixture
integer
ids
string
league
integer
player
integer
season
integer
team
integer
timezone
string

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Get Leagues

Description

Tool to retrieve leagues and cups. use when filtering competitions by id, name, country, code, season, team, type, current, search, or last.

Action Parameters

code
string
country
string
current
boolean
id
integer
last
integer
name
string
search
string
season
integer
team
integer
type
string

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Get League Seasons

Description

Tool to get the list of available seasons for all leagues. use when you need season filters for other league endpoints.

Action Parameters

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Get Odds

Description

Tool to fetch pre-match odds. use when you need odds filterable by fixture, league, season, date, timezone, bookmaker, bet, or to navigate pages.

Action Parameters

bet
integer
bookmaker
integer
date
string
fixture
integer
league
integer
page
integerDefaults to 1
season
integer
timezone
string

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Get In-Play Odds

Description

Tool to fetch in-play odds for fixtures in progress. use during live matches to get in-play odds.

Action Parameters

bet
integer
fixture
integer
league
integer

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Get Players

Description

Tool to get player statistics. use when fetching players by id, team, league, season, search, or pagination.

Action Parameters

id
integer
league
integer
page
integer
search
string
season
integer
team
integer

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Get Players Profiles

Description

Tool to get the list of all available players. use when you need player profiles optionally filtered by id, name search, or page.

Action Parameters

page
integerDefaults to 1
player
integer
search
string

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Get Players Seasons

Description

Tool to list all available seasons for player statistics. use when building a player statistics query, optionally filtering by a specific player id.

Action Parameters

player
integer

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Get Players Teams

Description

Tool to get the list of teams and seasons in which a player played during his career. use after confirming the player id to retrieve club history.

Action Parameters

player
integerRequired
season
integer

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Get Players Top Scorers

Description

Tool to get the 20 best players (top scorers) for a league or cup. use after confirming league and season.

Action Parameters

league
integerRequired
page
integer
season
integerRequired
team
integer

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Get Teams

Description

Tool to retrieve available teams. use when filtering teams by id, name, league, season, country, code, venue, or search before fetching detailed team data.

Action Parameters

code
string
country
string
id
integer
league
integer
name
string
search
string
season
integer
venue
integer

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Get team statistics

Description

Tool to get detailed statistics of a team for a given league and season. use after confirming league, season, and team id.

Action Parameters

date
string
from
string
league
integerRequired
season
integerRequired
team
integerRequired
to
string
venue
string

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Get Coaches

Description

Tool to fetch coaches and their career history. use when you need coach info by id, team filter, or name search.

Action Parameters

id
integer
search
string
team
integer

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Get Countries

Description

Tool to fetch available countries for league queries. use when filtering by name, code, or search string before retrieving leagues.

Action Parameters

code
string
name
string
search
string

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Get fixtures players

Description

Tool to get player statistics from a fixture. use when you need detailed per-player stats for a specific match. optionally filter by team.

Action Parameters

fixture
integerRequired
team
integer

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Get Fixtures Rounds

Description

Tool to get the rounds for a league or cup. use after confirming league and season to retrieve available round identifiers (optionally with dates) for filtering fixtures.

Action Parameters

current
boolean
dates
boolean
league
integerRequired
season
integerRequired
timezone
string

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Get Odds Bets

Description

Tool to get all available pre-match bet types. use when filtering by bet id or searching bet names before fetching odds.

Action Parameters

id
integer
search
string

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Get Odds Bookmakers

Description

Tool to list all available pre-match bookmakers. use when you need to discover or filter bookmakers before fetching odds.

Action Parameters

id
integer
search
string

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Get Live Odds Bets

Description

Tool to fetch all available bet types for in-play odds. use when you need to retrieve bet ids or names (optionally filtering by id or search) before fetching live odds.

Action Parameters

id
integer
search
string

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Get Players Top Assists

Description

Tool to get the 20 best players (top assists) for a league or cup. use after confirming league and season.

Action Parameters

league
integerRequired
page
integer
season
integerRequired
team
integer

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Get Players Top Yellow Cards

Description

Tool to get the 20 players with the most yellow cards for a league or cup. use after confirming league and season.

Action Parameters

league
integerRequired
page
integer
season
integerRequired
team
integer

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Get Predictions

Description

Tool to get predictions about a fixture. use when you need calculated predictions for a given fixture id.

Action Parameters

fixture
integerRequired

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Get Sidelined

Description

Tool to get sidelined information (injuries, suspensions, etc.). use when you need current sidelined records filtered by league, season, team, player, or type.

Action Parameters

league
integer
player
integer
season
integer
team
integer
type
string

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Get Timezone

Description

Tool to fetch the complete list of available timezones for fixture queries. use when you need valid timezone identifiers (e.g., 'europe/london') before calling fixtures endpoints.

Action Parameters

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Get Transfers

Description

Tool to get all available transfers for players and teams. use when you need transfer history filtered by player or team.

Action Parameters

player
integer
season
integer
team
integer

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Get Trophies

Description

Tool to get trophies for a player or coach. use when you need to list honors filtered by player(s) or coach(es).

Action Parameters

coach
integer
coachs
string
player
integer
players
string

Action Response

data
objectRequired
error
string
successful
booleanRequired