Sports

College football data

Learn how to use College football data with Composio

Overview

SLUG: COLLEGE_FOOTBALL_DATA

Description

CollegeFootballData.com provides comprehensive college football data, including game scores, statistics, and recruiting information, accessible via a RESTful API.

Authentication Details

generic_api_key
stringRequired

Connecting to College football data

Create an auth config

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

1

Select App

Navigate to [College football data](https://platform.composio.dev?next_page=/marketplace/College football data).

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

Tools

Executing tools

To prototype you can execute some tools to see the responses and working on the [College football data toolkit’s playground](https://app.composio.dev/app/College football data)

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=["COLLEGE_FOOTBALL_DATA"])
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: Advanced Box Score

Description

Tool to retrieve advanced box score metrics for a single college football game. Use after selecting a specific game to access team- and player-level advanced analytics.

Action Parameters

gameId
integerRequired

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Advanced Game Stats

Description

Tool to retrieve advanced team metrics at the game level. Use when detailed offensive and defensive metrics (success rates, explosiveness, havoc) are needed.

Action Parameters

excludeGarbageTime
boolean
opponent
string
seasonType
string
team
string
week
integer
year
integer

Action Response

data
arrayRequired
error
string
successful
booleanRequired

Tool Name: Advanced Season Stats by Team

Description

Tool to retrieve advanced season metrics aggregated by team and season. Use after selecting season and team filters.

Action Parameters

endWeek
integer
excludeGarbageTime
boolean
startWeek
integer
team
string
year
integer

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Betting Lines

Description

Tool to fetch betting lines and totals by game and provider. Use when you need current or historical betting line data filtered by specific criteria.

Action Parameters

away
string
conference
string
gameId
integer
home
string
seasonType
string
team
string
week
integer
year
integer

Action Response

data
arrayRequired
error
string
successful
booleanRequired

Tool Name: Composite Team Talent

Description

Tool to fetch composite team talent rankings by season. Use when you need 247Sports team talent composites for specified seasons.

Action Parameters

year
integer

Action Response

data
arrayRequired
error
string
successful
booleanRequired

Tool Name: Conference Memberships History

Description

Tool to retrieve historical conference memberships for teams, including years active and division. Use when you need to trace a team's conference history over time.

Action Parameters

conference
string
endYear
integer
startYear
integer
team
string

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Divisions by Conference

Description

Tool to list FBS/FCS conference divisions with active years and metadata. Use after specifying an optional season year to filter active divisions.

Action Parameters

year
integer

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Get Drive Data

Description

Tool to retrieve drive-level data and results. Use when analyzing detailed drives for specified games after filtering by season, team, or week.

Action Parameters

conference
string
defense
string
defenseConference
string
offense
string
offenseConference
string
seasonType
string
team
string
week
integer
year
integerRequired

Action Response

data
arrayRequired
error
string
successful
booleanRequired

Tool Name: Get Game Media

Description

Tool to retrieve game media information and broadcast schedules (TV, radio, web, etc.). Use after selecting season year and optional filters (week, team, conference). Example: "Get week 3 TV and radio outlets for 2025 SEC games."

Action Parameters

conference
string
mediaType
string
seasonType
string
team
string
week
integer
year
integerRequired

Action Response

data
arrayRequired
error
string
successful
booleanRequired

Tool Name: Get Games and Results

Description

Tool to retrieve games and results for a given season/week/team. Use when you need game schedules or outcomes filtered by specific criteria.

Action Parameters

away
string
conference
string
home
string
id
integer
seasonType
string
team
string
week
integer
year
integerRequired

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Get Player Game Stats

Description

Tool to fetch player statistics at the game level. Use when you need detailed stats for players in games after filtering parameters.

Action Parameters

category
string
conference
string
gameId
integer
seasonType
string
team
string
week
integer
year
integerRequired

Action Response

data
arrayRequired
error
string
successful
booleanRequired

Tool Name: Get Team Game Stats

Description

Tool to fetch team statistics at the game level. Use when you need detailed box score stats for games after filtering parameters.

Action Parameters

conference
string
gameId
integer
seasonType
string
team
string
week
integer
year
integerRequired

Action Response

data
arrayRequired
error
string
successful
booleanRequired

Tool Name: List Coaches and History

Description

Tool to get coaching records and history. Use when you need coaches’ season-by-season data with optional filters.

Action Parameters

firstName
string
lastName
string
maxYear
integer
minYear
integer
team
string
year
integer

Action Response

data
arrayRequired
error
string
successful
booleanRequired

Tool Name: List Conferences

Description

Tool to list all college football conferences. Use after authenticating to retrieve the up-to-date list of conferences.

Action Parameters

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: List FBS Teams

Description

Tool to list FBS teams for a given season. Use after selecting the season year to retrieve all FBS teams.

Action Parameters

year
integer

Action Response

data
arrayRequired
error
string
successful
booleanRequired

Tool Name: List FCS Teams

Description

Tool to list FCS teams for a given season and conference. Use when you need a list of FCS programs filtered by season year and conference.

Action Parameters

conference
string
year
integer

Action Response

data
arrayRequired
error
string
successful
booleanRequired

Tool Name: List Teams

Description

Tool to list college football teams. Use when you need a list of teams filtered by season year and/or conference.

Action Parameters

conference
string
year
integer

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: List Venues and Stadiums

Description

Tool to list college football venues with metadata (name, capacity, location, etc.). Use when you need detailed venue information for a specific season.

Action Parameters

year
integer

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: NFL Draft Picks

Description

Tool to list NFL Draft picks. Use when you need draft pick data by year, round, team, player, etc.

Action Parameters

conference
string
limit
integer
offset
integer
overall
integer
pick
integer
position
string
round
integer
school
string
team
string
year
integerRequired

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: NFL Draft Positions

Description

Tool to list NFL draft positions. Use when you need a standardized set of NFL positions for draft analysis.

Action Parameters

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: NFL Draft Teams

Description

Tool to list NFL teams used in draft endpoints. Use when preparing to retrieve NFL draft data by team.

Action Parameters

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Play-by-Play Data

Description

Tool to fetch play-by-play data for college football games. Use when you need detailed play logs filtered by season, week, team, or game.

Action Parameters

conference
string
defense
string
defenseConference
string
gameId
integer
offense
string
offenseConference
string
playType
string
seasonType
string
team
string
week
integerRequired
year
integerRequired

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Play Stats Player

Description

Tool to fetch player-level stats tied to individual plays. Use when you need detailed play-by-play player statistics filtered by season, week, game, or athlete.

Action Parameters

athleteId
integer
gameId
integer
seasonType
string
statTypeId
integer
team
string
week
integer
year
integer

Action Response

data
arrayRequired
error
string
successful
booleanRequired

Tool Name: Play Stat Types

Description

Tool to fetch all play-level stat type definitions. Use when you need a catalog of available play stat types for filtering or referencing.

Action Parameters

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Player PPA by Game

Description

Tool to retrieve player-level PPA/EPA broken down by game. Use when you need per-game PPA/EPA metrics for players filtered by season, week, or team.

Action Parameters

excludeGarbageTime
boolean
playerId
integer
position
string
team
string
threshold
string
week
integer
year
integer

Action Response

data
arrayRequired
error
string
successful
booleanRequired

Tool Name: PPA Player By Season

Description

Tool to fetch player-level PPA/EPA aggregated by season. Use when you need seasonal PPA metrics for specific players or groups after applying filters.

Action Parameters

conference
string
excludeGarbageTime
boolean
playerId
integer
position
string
team
string
threshold
string
year
integer

Action Response

data
arrayRequired
error
string
successful
booleanRequired

Tool Name: Predict Expected Points (EP)

Description

Tool to get expected points by down, distance, and field position. Use after selecting down (1–4) and distance to explore expected outcomes across the field.

Action Parameters

distance
integerRequired
down
integerRequired

Action Response

data
arrayRequired
error
string
successful
booleanRequired

Tool Name: PPA Team By Game

Description

Tool to retrieve team Predicted Points Added (PPA) by game. Use when you need team-level PPA metrics for games after filtering by season, week, team, or date.

Action Parameters

conference
string
endDate
string
seasonType
string
startDate
string
team
string
week
integer
year
integerRequired

Action Response

data
arrayRequired
error
string
successful
booleanRequired

Tool Name: Rankings Polls

Description

Tool to retrieve weekly human/computer poll rankings. Use after specifying season year and optional week.

Action Parameters

season_type
string
week
integer
year
integerRequired

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Elo Ratings

Description

Tool to retrieve Elo ratings for college football teams. Use when you need historical Elo ratings by season or for a specific team.

Action Parameters

team
string
year
integer

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: SP+ Ratings

Description

Tool to retrieve SP+ team ratings. Use when you need historical SP+ ratings for a specific season after confirming the season year.

Action Parameters

team
string
year
integer

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: SRS Ratings

Description

Tool to retrieve Simple Rating System (SRS) team ratings. Use when you need historical SRS values for a season, optionally filtering by team or conference.

Action Parameters

conference
string
team
string
year
integer

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Recruiting Group Dictionary

Description

Tool to list recruiting position group aggregations. Use when you need aggregated team recruiting ratings by position group (e.g., QB, RB, WR).

Action Parameters

conference
string
endYear
integer
startYear
integer
team
string

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Recruiting Transfer Portal

Description

Tool to retrieve transfer portal entries for a given season. Use when you need details of players entering the transfer portal, including from/to teams, position, and recruiting ratings.

Action Parameters

year
integerRequired

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Returning Production by Team

Description

Tool to fetch Bill Connelly–style returning production splits by team and season. Use when evaluating returning offense, defense, and overall production for teams in a given season.

Action Parameters

conference
string
team
string
year
integer

Action Response

data
arrayRequired
error
string
successful
booleanRequired

Tool Name: Season Stats Player

Description

Tool to fetch basic season stats aggregated by player and season. Use when you need overall player performance summaries for a given season.

Action Parameters

category
string
conference
string
endWeek
integer
seasonType
string
startWeek
integer
team
string
year
integer

Action Response

data
arrayRequired
error
string
successful
booleanRequired

Tool Name: Season Team Stats

Description

Tool to get basic season stats aggregated by team and season. Use when you need a summary of team-level statistics for a particular season.

Action Parameters

conference
string
endWeek
integer
seasonType
stringDefaults to both
startWeek
integer
team
string
year
integerRequired

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Season Types Dictionary

Description

Tool to list season types. Uses the season calendar endpoint to extract valid seasonType values.

Action Parameters

year
integer

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Team Matchup History

Description

Tool to retrieve head-to-head team matchup records over a date range. Use after selecting two FBS teams to compare their matchup history.

Action Parameters

maxYear
integer
minYear
integer
team1
stringRequired
team2
stringRequired

Action Response

data
arrayRequired
error
string
successful
booleanRequired

Tool Name: Team season records

Description

Tool to fetch team season records by year with optional filters. Use after specifying the year and any optional filters (conference, team, division, seasonType, limit, offset) to retrieve records.

Action Parameters

conference
string
division
string
limit
integer
offset
integer
seasonType
stringDefaults to regular
team
string
year
integerRequired

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Get Team Roster

Description

Tool to fetch roster for a given team and season. Use when you need a team's roster for a specific year.

Action Parameters

team
stringRequired
year
integerRequired

Action Response

data
arrayRequired
error
string
successful
booleanRequired