NCAAF API
Welcome to the BALLDONTLIE NCAAF API, the best College Football API on the planet. This API contains data from 2004 to now. An API key is required. You can obtain an API key by creating a free account on our website. Read the authentication section to learn how to use the API key.
Take a look at our other APIs:
Join us on discord.
MCP Server Integration
Connect to our sports data through any MCP-compatible client using our hosted MCP server. The MCP (Model Context Protocol) server allows AI assistants to interact with our API through natural language.
Quick Setup
Add this configuration to your MCP client (e.g., Claude Desktop, or any other MCP-compatible client):
{
"mcpServers": {
"balldontlie-api": {
"url": "https://mcp.balldontlie.io/mcp",
"transport": "http",
"headers": {
"Authorization": "YOUR_BALLDONTLIE_API_KEY"
}
}
}
}
Open Source Implementation
Check out our open-source MCP server implementation on GitHub: https://github.com/balldontlie-api/mcp
Usage Examples
Once configured, you can ask your AI assistant natural language questions like:
- "Show me the current AP Top 25 rankings"
- "Get Shedeur Sanders' season stats"
- "What are this week's NCAAF games?"
The MCP server provides access to all available API endpoints through conversational AI, making it easy to integrate sports data into any AI-powered application.
Account Tiers
There are three different account tiers which provide you access to different types of data. Visit our website to create an account for free.
Paid tiers do not apply across sports. The tier you purchase for NCAAF will not automatically be applied to other sports. You can purchase the ALL-ACCESS ($89.99/mo) tier to get access to every endpoint for every sport.
Read the table below to see the breakdown.
| Endpoint | Free | ALL-STAR | GOAT |
|---|---|---|---|
| Conferences | Yes | Yes | Yes |
| Teams | Yes | Yes | Yes |
| Players | Yes | Yes | Yes |
| Active Players | Yes | Yes | Yes |
| Standings | Yes | Yes | Yes |
| Games | No | Yes | Yes |
| Rankings | No | Yes | Yes |
| Play-by-Play | No | Yes | Yes |
| Player Stats | No | No | Yes |
| Team Stats | No | No | Yes |
| Player Season Stats | No | No | Yes |
| Team Season Stats | No | No | Yes |
The feature breakdown per tier is shown in the table below.
| Tier | Requests / Min | $USD / mo. |
|---|---|---|
| GOAT | 600 | 39.99 |
| ALL-STAR | 60 | 9.99 |
| Free | 5 | 0 |
Authentication
To authorize, use this code:
curl "api_endpoint_here" -H "Authorization: YOUR_API_KEY"
// Using fetch
const response = await fetch("https://api.balldontlie.io/ncaaf/v1/teams", {
headers: {
Authorization: "YOUR_API_KEY",
},
});
const data = await response.json();
# Using requests
import requests
response = requests.get(
'https://api.balldontlie.io/ncaaf/v1/teams',
headers={'Authorization': 'YOUR_API_KEY'}
)
data = response.json()
Make sure to replace
YOUR_API_KEYwith your API key.
BALLDONTLIE uses API keys to allow access to the API. You can obtain an API key by creating a free account at our website
We expect the API key to be included in all API requests to the server in a header that looks like the following:
Authorization: YOUR_API_KEY
Pagination
This API uses cursor based pagination rather than limit/offset. Endpoints that support pagination will send back responses with a meta key that looks like what is displayed on the right.
{
"meta": {
"next_cursor": 90,
"per_page": 25
}
}
You can use per_page to specify the maximum number of results. It defaults to 25 and doesn't allow values larger than 100.
You can use next_cursor to get the next page of results. Specify it in the request parameters like this: ?cursor=NEXT_CURSOR.
Errors
The API uses the following error codes:
| Error Code | Meaning |
|---|---|
| 401 | Unauthorized - You either need an API key or your account tier does not have access to the endpoint. |
| 400 | Bad Request -- The request is invalid. The request parameters are probably incorrect. |
| 404 | Not Found -- The specified resource could not be found. |
| 406 | Not Acceptable -- You requested a format that isn't json. |
| 429 | Too Many Requests -- You're rate limited. |
| 500 | Internal Server Error -- We had a problem with our server. Try again later. |
| 503 | Service Unavailable -- We're temporarily offline for maintenance. Please try again later. |
Conferences
Get All Conferences
curl "https://api.balldontlie.io/ncaaf/v1/conferences" \
-H "Authorization: YOUR_API_KEY"
const response = await fetch(
"https://api.balldontlie.io/ncaaf/v1/conferences",
{
headers: { Authorization: "YOUR_API_KEY" },
}
);
const data = await response.json();
import requests
response = requests.get(
'https://api.balldontlie.io/ncaaf/v1/conferences',
headers={'Authorization': 'YOUR_API_KEY'}
)
data = response.json()
The above command returns JSON structured like this:
{
"data": [
{
"id": 1,
"name": "ACC",
"abbreviation": "ACC"
},
{
"id": 2,
"name": "American",
"abbreviation": "American"
},
{
"id": 3,
"name": "Big 12",
"abbreviation": "Big 12"
},
{
"id": 12,
"name": "Big Sky",
"abbreviation": "Big Sky"
},
{
"id": 4,
"name": "Big Ten",
"abbreviation": "Big Ten"
},
{
"id": 13,
"name": "CAA",
"abbreviation": "CAA"
},
{
"id": 5,
"name": "CUSA",
"abbreviation": "CUSA"
},
{
"id": 6,
"name": "FBS Indep.",
"abbreviation": "FBS Indep."
},
{
"id": 14,
"name": "FCS Indep.",
"abbreviation": "FCS Indep."
},
{
"id": 15,
"name": "Ivy",
"abbreviation": "Ivy"
},
{
"id": 7,
"name": "MAC",
"abbreviation": "MAC"
},
{
"id": 16,
"name": "MEAC",
"abbreviation": "MEAC"
},
{
"id": 8,
"name": "Mountain West",
"abbreviation": "Mountain West"
},
{
"id": 17,
"name": "MVFC",
"abbreviation": "MVFC"
},
{
"id": 18,
"name": "NEC",
"abbreviation": "NEC"
},
{
"id": 19,
"name": "OVC-Big South",
"abbreviation": "OVC-Big South"
},
{
"id": 9,
"name": "Pac-12",
"abbreviation": "Pac-12"
},
{
"id": 20,
"name": "Patriot",
"abbreviation": "Patriot"
},
{
"id": 21,
"name": "Pioneer",
"abbreviation": "Pioneer"
},
{
"id": 10,
"name": "SEC",
"abbreviation": "SEC"
},
{
"id": 22,
"name": "Southern",
"abbreviation": "Southern"
},
{
"id": 23,
"name": "Southland",
"abbreviation": "Southland"
},
{
"id": 11,
"name": "Sun Belt",
"abbreviation": "Sun Belt"
},
{
"id": 24,
"name": "SWAC",
"abbreviation": "SWAC"
},
{
"id": 25,
"name": "UAC",
"abbreviation": "UAC"
}
]
}
This endpoint retrieves all NCAAF conferences.
HTTP Request
GET https://api.balldontlie.io/ncaaf/v1/conferences
Teams
Get All Teams
curl "https://api.balldontlie.io/ncaaf/v1/teams" \
-H "Authorization: YOUR_API_KEY"
const response = await fetch("https://api.balldontlie.io/ncaaf/v1/teams", {
headers: { Authorization: "YOUR_API_KEY" },
});
const data = await response.json();
import requests
response = requests.get(
'https://api.balldontlie.io/ncaaf/v1/teams',
headers={'Authorization': 'YOUR_API_KEY'}
)
data = response.json()
The above command returns JSON structured like this:
{
"data": [
{
"id": 1,
"conference": "1",
"city": "Boston College",
"name": "Eagles",
"full_name": "Boston College Eagles",
"abbreviation": "BC"
},
{
"id": 2,
"conference": "1",
"city": "California",
"name": "Golden Bears",
"full_name": "California Golden Bears",
"abbreviation": "CAL"
},
...
]
}
This endpoint retrieves all NCAAF teams.
HTTP Request
GET https://api.balldontlie.io/ncaaf/v1/teams
Query Parameters
| Parameter | Required | Description |
|---|---|---|
| conference_id | false | Returns teams that belong to this conference |
Players
Get All Players
curl "https://api.balldontlie.io/ncaaf/v1/players" \
-H "Authorization: YOUR_API_KEY"
const response = await fetch("https://api.balldontlie.io/ncaaf/v1/players", {
headers: { Authorization: "YOUR_API_KEY" },
});
const data = await response.json();
import requests
response = requests.get(
'https://api.balldontlie.io/ncaaf/v1/players',
headers={'Authorization': 'YOUR_API_KEY'}
)
data = response.json()
The above command returns JSON structured like this:
{
"data": [
{
"id": 1,
"first_name": "Jamien",
"last_name": "McCullum",
"position": "Wide Receiver",
"position_abbreviation": "WR",
"height": null,
"weight": null,
"jersey_number": null,
"team": {
"id": 13,
"conference": "1",
"city": "Stanford",
"name": "Cardinal",
"full_name": "Stanford Cardinal",
"abbreviation": "STAN"
}
},
...
],
"meta": {
"next_cursor": 25,
"per_page": 25
}
}
This endpoint retrieves all NCAAF players.
HTTP Request
GET https://api.balldontlie.io/ncaaf/v1/players
Query Parameters
| Parameter | Required | Description |
|---|---|---|
| cursor | false | The cursor, used for pagination |
| per_page | false | The number of results per page. Default to 25. Max is 100 |
| search | false | Returns players whose first or last name matches this value. For example, ?search=sanders will return players that have 'sanders' in their first or last name. |
| first_name | false | Returns players whose first name matches this value. For example, ?first_name=shedeur will return players that have 'shedeur' in their first name. |
| last_name | false | Returns players whose last name matches this value. For example, ?last_name=sanders will return players that have 'sanders' in their last name. |
| team_ids | false | Returns players that belong to these team ids. This should be an array: ?team_ids[]=1&team_ids[]=2 |
| player_ids | false | Returns players that match these ids. This should be an array: ?player_ids[]=1&player_ids[]=2 |
Get Active Players
curl "https://api.balldontlie.io/ncaaf/v1/players/active" \
-H "Authorization: YOUR_API_KEY"
const response = await fetch(
"https://api.balldontlie.io/ncaaf/v1/players/active",
{
headers: { Authorization: "YOUR_API_KEY" },
}
);
const data = await response.json();
import requests
response = requests.get(
'https://api.balldontlie.io/ncaaf/v1/players/active',
headers={'Authorization': 'YOUR_API_KEY'}
)
data = response.json()
The above command returns JSON structured like this:
{
"data": [
{
"id": 9935,
"first_name": "Calvin",
"last_name": "Moore",
"position": "Cornerback",
"position_abbreviation": "CB",
"height": "5' 10\"",
"weight": "180 lbs",
"jersey_number": "4",
"team": {
"id": 137,
"conference": "20",
"city": "Cal Poly",
"name": "Mustangs",
"full_name": "Cal Poly Mustangs",
"abbreviation": "CP"
}
},
...
],
"meta": {
"next_cursor": 25,
"per_page": 25
}
}
This endpoint retrieves all currently active NCAAF players.
HTTP Request
GET https://api.balldontlie.io/ncaaf/v1/players/active
Query Parameters
| Parameter | Required | Description |
|---|---|---|
| cursor | false | The cursor, used for pagination |
| per_page | false | The number of results per page. Default to 25. Max is 100 |
| search | false | Returns players whose first or last name matches this value. For example, ?search=sanders will return players that have 'sanders' in their first or last name. |
| first_name | false | Returns players whose first name matches this value. For example, ?first_name=shedeur will return players that have 'shedeur' in their first name. |
| last_name | false | Returns players whose last name matches this value. For example, ?last_name=sanders will return players that have 'sanders' in their last name. |
| team_ids | false | Returns players that belong to these team ids. This should be an array: ?team_ids[]=1&team_ids[]=2 |
| player_ids | false | Returns players that match these ids. This should be an array: ?player_ids[]=1&player_ids[]=2 |
Standings
Get Standings
curl "https://api.balldontlie.io/ncaaf/v1/standings?conference_id=1" \
-H "Authorization: YOUR_API_KEY"
const response = await fetch(
"https://api.balldontlie.io/ncaaf/v1/standings?conference_id=1",
{
headers: { Authorization: "YOUR_API_KEY" },
}
);
const data = await response.json();
import requests
response = requests.get(
'https://api.balldontlie.io/ncaaf/v1/standings',
params={'conference_id': 1},
headers={'Authorization': 'YOUR_API_KEY'}
)
data = response.json()
The above command returns JSON structured like this:
{
"data": [
{
"team": {
"id": 15,
"conference": "1",
"city": "Virginia",
"name": "Cavaliers",
"full_name": "Virginia Cavaliers",
"abbreviation": "UVA"
},
"conference": {
"id": 1,
"name": "ACC",
"abbreviation": "ACC"
},
"season": 2025,
"wins": 5,
"losses": 1,
"win_percentage": 1,
"games_behind": 0.5,
"home_record": "4-0",
"away_record": "1-1",
"conference_record": "3-0"
},
{
"team": {
"id": 4,
"conference": "1",
"city": "Duke",
"name": "Blue Devils",
"full_name": "Duke Blue Devils",
"abbreviation": "DUKE"
},
"conference": {
"id": 1,
"name": "ACC",
"abbreviation": "ACC"
},
"season": 2025,
"wins": 4,
"losses": 2,
"win_percentage": 1,
"games_behind": 1.5,
"home_record": "2-1",
"away_record": "2-1",
"conference_record": "3-0"
},
...
]
}
This endpoint retrieves NCAAF standings for a specific conference.
HTTP Request
GET https://api.balldontlie.io/ncaaf/v1/standings
Query Parameters
| Parameter | Required | Description |
|---|---|---|
| conference_id | true | The ID of the conference |
| season | true | Filter by season year |
Games
Get All Games
curl "https://api.balldontlie.io/ncaaf/v1/games" \
-H "Authorization: YOUR_API_KEY"
const response = await fetch("https://api.balldontlie.io/ncaaf/v1/games", {
headers: { Authorization: "YOUR_API_KEY" },
});
const data = await response.json();
import requests
response = requests.get(
'https://api.balldontlie.io/ncaaf/v1/games',
headers={'Authorization': 'YOUR_API_KEY'}
)
data = response.json()
The above command returns JSON structured like this:
{
"data": [
{
"id": 47671,
"date": "2025-10-11T16:00:00.000Z",
"season": 2025,
"week": 7,
"status": "in",
"period": 4,
"time": "1:23",
"home_team": {
"id": 18,
"conference": "151",
"city": "Army",
"name": "Black Knights",
"full_name": "Army Black Knights",
"abbreviation": "ARMY"
},
"visitor_team": {
"id": 19,
"conference": "151",
"city": "Charlotte",
"name": "49ers",
"full_name": "Charlotte 49ers",
"abbreviation": "CLT"
},
"home_score_q1": 7,
"home_score_q2": 10,
"home_score_q3": 7,
"home_score_q4": 0,
"home_score_ot": null,
"away_score_q1": 0,
"away_score_q2": 0,
"away_score_q3": 0,
"away_score_q4": 0,
"away_score_ot": null,
"home_score": 24,
"away_score": 0
},
{
"id": 47672,
"date": "2025-10-11T20:00:00.000Z",
"season": 2025,
"week": 7,
"status": "pre",
"period": 0,
"time": "0:00",
"home_team": {
"id": 27,
"conference": "151",
"city": "Temple",
"name": "Owls",
"full_name": "Temple Owls",
"abbreviation": "TEM"
},
"visitor_team": {
"id": 23,
"conference": "151",
"city": "Navy",
"name": "Midshipmen",
"full_name": "Navy Midshipmen",
"abbreviation": "NAVY"
},
"home_score_q1": null,
"home_score_q2": null,
"home_score_q3": null,
"home_score_q4": null,
"home_score_ot": null,
"away_score_q1": null,
"away_score_q2": null,
"away_score_q3": null,
"away_score_q4": null,
"away_score_ot": null,
"home_score": 0,
"away_score": 0
},
...
],
"meta": {
"next_cursor": 25,
"per_page": 25
}
}
This endpoint retrieves all NCAAF games.
HTTP Request
GET https://api.balldontlie.io/ncaaf/v1/games
Query Parameters
| Parameter | Required | Description |
|---|---|---|
| cursor | false | The cursor, used for pagination |
| per_page | false | The number of results per page. Default to 25. Max is 100 |
| dates | false | Returns games that match these dates. Dates should be formatted in YYYY-MM-DD. This should be an array: ?dates[]=2024-09-07&dates[]=2024-09-14 |
| seasons | false | Returns games that occurred in these seasons. This should be an array: ?seasons[]=2023&seasons[]=2024 |
| team_ids | false | Returns games for these team ids. This should be an array: ?team_ids[]=1&team_ids[]=2 |
| start_date | false | Returns games that occurred on or after this date. Date should be formatted in YYYY-MM-DD |
| end_date | false | Returns games that occurred on or before this date. Date should be formatted in YYYY-MM-DD |
| weeks | false | Returns games for these week numbers. This should be an array: ?weeks[]=1&weeks[]=2 |
Get a Specific Game
curl "https://api.balldontlie.io/ncaaf/v1/games/<ID>" \
-H "Authorization: YOUR_API_KEY"
const response = await fetch(
"https://api.balldontlie.io/ncaaf/v1/games/47671",
{
headers: { Authorization: "YOUR_API_KEY" },
}
);
const data = await response.json();
import requests
response = requests.get(
'https://api.balldontlie.io/ncaaf/v1/games/47671',
headers={'Authorization': 'YOUR_API_KEY'}
)
data = response.json()
The above command returns JSON structured like this:
{
"data": {
"id": 47671,
"date": "2025-10-11T16:00:00.000Z",
"season": 2025,
"week": 7,
"status": "in",
"period": 4,
"time": "1:16",
"home_team": {
"id": 18,
"conference": "151",
"city": "Army",
"name": "Black Knights",
"full_name": "Army Black Knights",
"abbreviation": "ARMY"
},
"visitor_team": {
"id": 19,
"conference": "151",
"city": "Charlotte",
"name": "49ers",
"full_name": "Charlotte 49ers",
"abbreviation": "CLT"
},
"home_score_q1": 7,
"home_score_q2": 10,
"home_score_q3": 7,
"home_score_q4": 0,
"home_score_ot": null,
"away_score_q1": 0,
"away_score_q2": 0,
"away_score_q3": 0,
"away_score_q4": 0,
"away_score_ot": null,
"home_score": 24,
"away_score": 0
}
}
This endpoint retrieves a specific NCAAF game.
HTTP Request
GET https://api.balldontlie.io/ncaaf/v1/games/<ID>
URL Parameters
| Parameter | Required | Description |
|---|---|---|
| ID | true | The ID of the game to retrieve |
Rankings
Get Rankings
curl "https://api.balldontlie.io/ncaaf/v1/rankings?season=2025" \
-H "Authorization: YOUR_API_KEY"
const response = await fetch(
"https://api.balldontlie.io/ncaaf/v1/rankings?season=2025",
{
headers: { Authorization: "YOUR_API_KEY" },
}
);
const data = await response.json();
import requests
response = requests.get(
'https://api.balldontlie.io/ncaaf/v1/rankings',
params={'season': 2025},
headers={'Authorization': 'YOUR_API_KEY'}
)
data = response.json()
The above command returns JSON structured like this:
{
"data": [
{
"team": {
"id": 57,
"conference": "5",
"city": "Ohio State",
"name": "Buckeyes",
"full_name": "Ohio State Buckeyes",
"abbreviation": "OSU"
},
"season": 2025,
"week": 7,
"rank": 1,
"first_place_votes": 40,
"points": 1620,
"trend": "-",
"record": "5-0"
},
{
"team": {
"id": 8,
"conference": "1",
"city": "Miami",
"name": "Hurricanes",
"full_name": "Miami Hurricanes",
"abbreviation": "MIA"
},
"season": 2025,
"week": 7,
"rank": 2,
"first_place_votes": 21,
"points": 1579,
"trend": "+1",
"record": "5-0"
},
{
"team": {
"id": 58,
"conference": "5",
"city": "Oregon",
"name": "Ducks",
"full_name": "Oregon Ducks",
"abbreviation": "ORE"
},
"season": 2025,
"week": 7,
"rank": 3,
"first_place_votes": 5,
"points": 1542,
"trend": "-1",
"record": "5-0"
},
...
]
}
This endpoint retrieves NCAAF AP Poll rankings.
HTTP Request
GET https://api.balldontlie.io/ncaaf/v1/rankings
Query Parameters
| Parameter | Required | Description |
|---|---|---|
| season | true | Season year |
| week | false | Filter by week number (defaults to current week) |
Play-by-Play
Get Play-by-Play Data
curl "https://api.balldontlie.io/ncaaf/v1/plays?game_id=47671" \
-H "Authorization: YOUR_API_KEY"
const response = await fetch(
"https://api.balldontlie.io/ncaaf/v1/plays?game_id=47671",
{
headers: { Authorization: "YOUR_API_KEY" },
}
);
const data = await response.json();
import requests
response = requests.get(
'https://api.balldontlie.io/ncaaf/v1/plays',
params={'game_id': 47671},
headers={'Authorization': 'YOUR_API_KEY'}
)
data = response.json()
The above command returns JSON structured like this:
{
"data": [
{
"game_id": 47671,
"order": 1,
"type": "Kickoff",
"text": "Anderson Britton kickoff for 62 yds , Derrick Eley return for 19 yds to the CLT 22",
"home_score": 0,
"away_score": 0,
"period": 1,
"clock": "14:55",
"scoring_play": false,
"score_value": null,
"team": {
"id": 19,
"conference": "151",
"city": "Charlotte",
"name": "49ers",
"full_name": "Charlotte 49ers",
"abbreviation": "CLT"
}
},
...
]
}
This endpoint retrieves play-by-play data for a specific game.
HTTP Request
GET https://api.balldontlie.io/ncaaf/v1/plays
Query Parameters
| Parameter | Required | Description |
|---|---|---|
| game_id | true | The game ID |
Player Stats
Get Player Statistics
curl "https://api.balldontlie.io/ncaaf/v1/player_stats" \
-H "Authorization: YOUR_API_KEY"
const response = await fetch(
"https://api.balldontlie.io/ncaaf/v1/player_stats",
{
headers: { Authorization: "YOUR_API_KEY" },
}
);
const data = await response.json();
import requests
response = requests.get(
'https://api.balldontlie.io/ncaaf/v1/player_stats',
headers={'Authorization': 'YOUR_API_KEY'}
)
data = response.json()
The above command returns JSON structured like this:
{
"data": [
{
"player": {
"id": 56105,
"first_name": "Rod",
"last_name": "Gainey Jr.",
"position": "Running Back",
"position_abbreviation": "RB",
"height": "6' 0\"",
"weight": "185 lbs",
"jersey_number": "6",
},
"team": {
"id": 19,
"conference": "151",
"city": "Charlotte",
"name": "49ers",
"full_name": "Charlotte 49ers",
"abbreviation": "CLT"
},
"game": {
"id": 47671,
"date": "2025-10-11T16:00:00.000Z",
"season": 2025,
"week": 7,
"status": "in",
"period": 4,
"time": "0:08",
"home_team": null,
"visitor_team": null,
"home_score_q1": 7,
"home_score_q2": 10,
"home_score_q3": 7,
"home_score_q4": 0,
"home_score_ot": null,
"away_score_q1": 0,
"away_score_q2": 0,
"away_score_q3": 0,
"away_score_q4": 7,
"away_score_ot": null,
"home_score": 24,
"away_score": 7
},
"passing_completions": null,
"passing_attempts": null,
"passing_yards": null,
"passing_touchdowns": null,
"passing_interceptions": null,
"passing_qbr": null,
"passing_rating": null,
"rushing_attempts": 19,
"rushing_yards": 51,
"rushing_touchdowns": 0,
"rushing_long": 10,
"receptions": 1,
"receiving_yards": 1,
"receiving_touchdowns": 0,
"receiving_targets": null,
"receiving_long": 1,
"total_tackles": null,
"solo_tackles": null,
"tackles_for_loss": null,
"sacks": null,
"interceptions": null,
"passes_defended": null
},
...
],
"meta": {
"next_cursor": 25,
"per_page": 25
}
}
This endpoint retrieves player game statistics.
HTTP Request
GET https://api.balldontlie.io/ncaaf/v1/player_stats
Query Parameters
| Parameter | Required | Description |
|---|---|---|
| cursor | false | The cursor, used for pagination |
| per_page | false | The number of results per page. Default to 25. Max is 100 |
| player_ids | false | Returns stats for these player ids. This should be an array: ?player_ids[]=1&player_ids[]=2 |
| team_ids | false | Returns stats for these team ids. This should be an array: ?team_ids[]=1&team_ids[]=2 |
| game_ids | false | Returns stats for these game ids. This should be an array: ?game_ids[]=1&game_ids[]=2 |
| dates | false | Returns stats that match these dates. Dates should be formatted in YYYY-MM-DD. This should be an array: ?dates[]=2024-09-07&dates[]=2024-09-14 |
| seasons | false | Returns stats that occurred in these seasons. This should be an array: ?seasons[]=2023&seasons[]=2024 |
| start_date | false | Returns stats that occurred on or after this date. Date should be formatted in YYYY-MM-DD |
| end_date | false | Returns stats that occurred on or before this date. Date should be formatted in YYYY-MM-DD |
| weeks | false | Returns stats for these week numbers. This should be an array: ?weeks[]=1&weeks[]=2 |
Team Stats
Get Team Statistics
curl "https://api.balldontlie.io/ncaaf/v1/team_stats" \
-H "Authorization: YOUR_API_KEY"
const response = await fetch("https://api.balldontlie.io/ncaaf/v1/team_stats", {
headers: { Authorization: "YOUR_API_KEY" },
});
const data = await response.json();
import requests
response = requests.get(
'https://api.balldontlie.io/ncaaf/v1/team_stats',
headers={'Authorization': 'YOUR_API_KEY'}
)
data = response.json()
The above command returns JSON structured like this:
{
"data": [
{
"team": {
"id": 19,
"conference": "151",
"city": "Charlotte",
"name": "49ers",
"full_name": "Charlotte 49ers",
"abbreviation": "CLT"
},
"game": {
"id": 47671,
"date": "2025-10-11T16:00:00.000Z",
"season": 2025,
"week": 7
},
"first_downs": 11,
"third_down_efficiency": "5-14",
"fourth_down_efficiency": "2-5",
"passing_yards": 110,
"rushing_yards": 68,
"total_yards": 178,
"turnovers": 1,
"penalties": 2,
"penalty_yards": 20,
"possession_time": "22:06"
},
{
"team": {
"id": 18,
"conference": "151",
"city": "Army",
"name": "Black Knights",
"full_name": "Army Black Knights",
"abbreviation": "ARMY"
},
"game": {
"id": 47671,
"date": "2025-10-11T16:00:00.000Z",
"season": 2025,
"week": 7
},
"first_downs": 20,
"third_down_efficiency": "8-14",
"fourth_down_efficiency": "2-3",
"passing_yards": 50,
"rushing_yards": 304,
"total_yards": 354,
"turnovers": 1,
"penalties": 1,
"penalty_yards": 15,
"possession_time": "37:54"
}
],
"meta": {
"per_page": 25
}
}
This endpoint retrieves team game statistics.
HTTP Request
GET https://api.balldontlie.io/ncaaf/v1/team_stats
Query Parameters
| Parameter | Required | Description |
|---|---|---|
| cursor | false | The cursor, used for pagination |
| per_page | false | The number of results per page. Default to 25. Max is 100 |
| team_ids | false | Returns stats for these team ids. This should be an array: ?team_ids[]=1&team_ids[]=2 |
| game_ids | false | Returns stats for these game ids. This should be an array: ?game_ids[]=1&game_ids[]=2 |
| dates | false | Returns stats that match these dates. Dates should be formatted in YYYY-MM-DD. This should be an array: ?dates[]=2024-09-07&dates[]=2024-09-14 |
| seasons | false | Returns stats that occurred in these seasons. This should be an array: ?seasons[]=2023&seasons[]=2024 |
| start_date | false | Returns stats that occurred on or after this date. Date should be formatted in YYYY-MM-DD |
| end_date | false | Returns stats that occurred on or before this date. Date should be formatted in YYYY-MM-DD |
| weeks | false | Returns stats for these week numbers. This should be an array: ?weeks[]=1&weeks[]=2 |
Player Season Stats
Get Player Season Statistics
curl "https://api.balldontlie.io/ncaaf/v1/player_season_stats" \
-H "Authorization: YOUR_API_KEY"
const response = await fetch(
"https://api.balldontlie.io/ncaaf/v1/player_season_stats",
{
headers: { Authorization: "YOUR_API_KEY" },
}
);
const data = await response.json();
import requests
response = requests.get(
'https://api.balldontlie.io/ncaaf/v1/player_season_stats',
headers={'Authorization': 'YOUR_API_KEY'}
)
data = response.json()
The above command returns JSON structured like this:
{
"data": [
{
"player": {
"id": 48749,
"first_name": "Carson",
"last_name": "Beck",
"position": "Quarterback",
"position_abbreviation": "QB",
"height": "6' 4\"",
"weight": "220 lbs",
"jersey_number": "11",
"team": {
"id": 8,
"conference": "1",
"city": "Miami",
"name": "Hurricanes",
"full_name": "Miami Hurricanes",
"abbreviation": "MIA"
}
},
"team": {
"id": 111,
"conference": "8",
"city": "Georgia",
"name": "Bulldogs",
"full_name": "Georgia Bulldogs",
"abbreviation": "UGA"
},
"season": 2021,
"passing_completions": 10,
"passing_attempts": 23,
"passing_yards": 176,
"passing_touchdowns": 2,
"passing_interceptions": 2,
"passing_yards_per_game": null,
"passing_rating": 119.06,
"rushing_attempts": 5,
"rushing_yards": 15,
"rushing_touchdowns": null,
"rushing_yards_per_game": null,
"rushing_avg": 3,
"receptions": null,
"receiving_yards": null,
"receiving_touchdowns": null,
"receiving_yards_per_game": null,
"receiving_avg": null,
"total_tackles": null,
"solo_tackles": null,
"tackles_for_loss": null,
"sacks": null,
"interceptions": null,
"passes_defended": null
},
{
"player": {
"id": 48749,
"first_name": "Carson",
"last_name": "Beck",
"position": "Quarterback",
"position_abbreviation": "QB",
"height": "6' 4\"",
"weight": "220 lbs",
"jersey_number": "11",
"team": {
"id": 8,
"conference": "1",
"city": "Miami",
"name": "Hurricanes",
"full_name": "Miami Hurricanes",
"abbreviation": "MIA"
}
},
"team": {
"id": 111,
"conference": "8",
"city": "Georgia",
"name": "Bulldogs",
"full_name": "Georgia Bulldogs",
"abbreviation": "UGA"
},
"season": 2022,
"passing_completions": 26,
"passing_attempts": 35,
"passing_yards": 310,
"passing_touchdowns": 4,
"passing_interceptions": null,
"passing_yards_per_game": null,
"passing_rating": 186.4,
"rushing_attempts": 7,
"rushing_yards": 43,
"rushing_touchdowns": null,
"rushing_yards_per_game": null,
"rushing_avg": 6.14,
"receptions": null,
"receiving_yards": null,
"receiving_touchdowns": null,
"receiving_yards_per_game": null,
"receiving_avg": null,
"total_tackles": null,
"solo_tackles": null,
"tackles_for_loss": null,
"sacks": null,
"interceptions": null,
"passes_defended": null
},
{
"player": {
"id": 48749,
"first_name": "Carson",
"last_name": "Beck",
"position": "Quarterback",
"position_abbreviation": "QB",
"height": "6' 4\"",
"weight": "220 lbs",
"jersey_number": "11",
"team": {
"id": 8,
"conference": "1",
"city": "Miami",
"name": "Hurricanes",
"full_name": "Miami Hurricanes",
"abbreviation": "MIA"
}
},
"team": {
"id": 111,
"conference": "8",
"city": "Georgia",
"name": "Bulldogs",
"full_name": "Georgia Bulldogs",
"abbreviation": "UGA"
},
"season": 2023,
"passing_completions": 302,
"passing_attempts": 417,
"passing_yards": 3941,
"passing_touchdowns": 24,
"passing_interceptions": 6,
"passing_yards_per_game": null,
"passing_rating": 167.93,
"rushing_attempts": 60,
"rushing_yards": 116,
"rushing_touchdowns": 4,
"rushing_yards_per_game": null,
"rushing_avg": 1.93,
"receptions": null,
"receiving_yards": null,
"receiving_touchdowns": null,
"receiving_yards_per_game": null,
"receiving_avg": null,
"total_tackles": 1,
"solo_tackles": 1,
"tackles_for_loss": null,
"sacks": null,
"interceptions": null,
"passes_defended": null
},
{
"player": {
"id": 48749,
"first_name": "Carson",
"last_name": "Beck",
"position": "Quarterback",
"position_abbreviation": "QB",
"height": "6' 4\"",
"weight": "220 lbs",
"jersey_number": "11",
"team": {
"id": 8,
"conference": "1",
"city": "Miami",
"name": "Hurricanes",
"full_name": "Miami Hurricanes",
"abbreviation": "MIA"
}
},
"team": {
"id": 111,
"conference": "8",
"city": "Georgia",
"name": "Bulldogs",
"full_name": "Georgia Bulldogs",
"abbreviation": "UGA"
},
"season": 2024,
"passing_completions": 290,
"passing_attempts": 448,
"passing_yards": 3485,
"passing_touchdowns": 28,
"passing_interceptions": 12,
"passing_yards_per_game": null,
"passing_rating": 145.34,
"rushing_attempts": 55,
"rushing_yards": 71,
"rushing_touchdowns": 1,
"rushing_yards_per_game": null,
"rushing_avg": 1.29,
"receptions": null,
"receiving_yards": null,
"receiving_touchdowns": null,
"receiving_yards_per_game": null,
"receiving_avg": null,
"total_tackles": 1,
"solo_tackles": 1,
"tackles_for_loss": null,
"sacks": null,
"interceptions": null,
"passes_defended": null
},
{
"player": {
"id": 48749,
"first_name": "Carson",
"last_name": "Beck",
"position": "Quarterback",
"position_abbreviation": "QB",
"height": "6' 4\"",
"weight": "220 lbs",
"jersey_number": "11",
"team": {
"id": 8,
"conference": "1",
"city": "Miami",
"name": "Hurricanes",
"full_name": "Miami Hurricanes",
"abbreviation": "MIA"
}
},
"team": {
"id": 8,
"conference": "1",
"city": "Miami",
"name": "Hurricanes",
"full_name": "Miami Hurricanes",
"abbreviation": "MIA"
},
"season": 2025,
"passing_completions": 102,
"passing_attempts": 139,
"passing_yards": 1213,
"passing_touchdowns": 11,
"passing_interceptions": 3,
"passing_yards_per_game": 242.6,
"passing_rating": 168.49,
"rushing_attempts": 13,
"rushing_yards": 18,
"rushing_touchdowns": 1,
"rushing_yards_per_game": 3.6,
"rushing_avg": 1.38,
"receptions": null,
"receiving_yards": null,
"receiving_touchdowns": null,
"receiving_yards_per_game": null,
"receiving_avg": null,
"total_tackles": null,
"solo_tackles": null,
"tackles_for_loss": null,
"sacks": null,
"interceptions": null,
"passes_defended": null
}
],
"meta": {
"per_page": 25
}
}
This endpoint retrieves player season statistics.
HTTP Request
GET https://api.balldontlie.io/ncaaf/v1/player_season_stats
Query Parameters
| Parameter | Required | Description |
|---|---|---|
| cursor | false | The cursor, used for pagination |
| per_page | false | The number of results per page. Default to 25. Max is 100 |
| player_ids | false | Returns stats for these player ids. This should be an array: ?player_ids[]=1&player_ids[]=2 |
| team_ids | false | Returns stats for these team ids. This should be an array: ?team_ids[]=1&team_ids[]=2 |
| season | false | Filter by season year |
Team Season Stats
Get Team Season Statistics
curl "https://api.balldontlie.io/ncaaf/v1/team_season_stats" \
-H "Authorization: YOUR_API_KEY"
const response = await fetch(
"https://api.balldontlie.io/ncaaf/v1/team_season_stats",
{
headers: { Authorization: "YOUR_API_KEY" },
}
);
const data = await response.json();
import requests
response = requests.get(
'https://api.balldontlie.io/ncaaf/v1/team_season_stats',
headers={'Authorization': 'YOUR_API_KEY'}
)
data = response.json()
The above command returns JSON structured like this:
{
"data": [
{
"team": {
"id": 8,
"conference": "1",
"city": "Miami",
"name": "Hurricanes",
"full_name": "Miami Hurricanes",
"abbreviation": "MIA"
},
"season": 2025,
"passing_yards": 1321,
"passing_yards_per_game": 264.2,
"passing_touchdowns": 11,
"passing_interceptions": 3,
"passing_qb_rating": 165.532,
"rushing_yards": 819,
"rushing_yards_per_game": 163.8,
"rushing_touchdowns": 12,
"receiving_yards": 1321,
"receiving_touchdowns": 11,
"opp_passing_yards": 945,
"opp_rushing_yards": 437
}
],
"meta": {
"per_page": 25
}
}
This endpoint retrieves team season statistics.
HTTP Request
GET https://api.balldontlie.io/ncaaf/v1/team_season_stats
Query Parameters
| Parameter | Required | Description |
|---|---|---|
| cursor | false | The cursor, used for pagination |
| per_page | false | The number of results per page. Default to 25. Max is 100 |
| team_ids | false | Returns stats for these team ids. This should be an array: ?team_ids[]=1&team_ids[]=2 |
| season | false | Filter by season year |