> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xquik.com/llms.txt
> Use this file to discover all available pages before exploring further.

# NFL & college football scores, X (Twitter) API docs

> Get 1 NFL or college football game's live scoreboard from X, with the score by quarter, clock, down & distance, venue & latest play. 1 credit per request.

> For the complete documentation index, see [llms.txt](https://docs.xquik.com/llms.txt).

`GET https://xquik.com/api/v1/x/sports/{league}/games/{id}`

**1 credit per request** · [All plans](https://xquik.com) from \$0.00012/credit

Direct [MPP](https://docs.xquik.com/mpp/machine-payments-protocol.md) at USD 0.00015 per call · Supports [guest paid reads](https://docs.xquik.com/guides/guest-wallets.md)

```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/bash.json","/languages/csharp.json","/languages/go.json","/languages/java.json","/languages/javascript.json","/languages/kotlin.json","/languages/php.json","/languages/python.json","/languages/ruby.json","/languages/typescript.json"]}}
curl "https://xquik.com/api/v1/x/sports/nfl/games/2055084502741811200" \
  -H "x-api-key: xq_your_api_key_here" | jq
```

```javascript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/bash.json","/languages/csharp.json","/languages/go.json","/languages/java.json","/languages/javascript.json","/languages/kotlin.json","/languages/php.json","/languages/python.json","/languages/ruby.json","/languages/typescript.json"]}}
const gameId = "2055084502741811200";
const response = await fetch(`https://xquik.com/api/v1/x/sports/nfl/games/${gameId}`, {
  headers: { "x-api-key": "xq_your_api_key_here" },
});
const game = await response.json();
if (!response.ok) throw new Error(JSON.stringify(game));

const home = game.teams[game.home.teamId]?.abbreviation;
const away = game.teams[game.away.teamId]?.abbreviation;
console.log(`${away} ${game.away.points} at ${home} ${game.home.points}, ${game.status}`);
```

```python Python theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/bash.json","/languages/csharp.json","/languages/go.json","/languages/java.json","/languages/javascript.json","/languages/kotlin.json","/languages/php.json","/languages/python.json","/languages/ruby.json","/languages/typescript.json"]}}
import requests

game_id = "2055084502741811200"
response = requests.get(
    f"https://xquik.com/api/v1/x/sports/nfl/games/{game_id}",
    headers={"x-api-key": "xq_your_api_key_here"},
)
game = response.json()
if not response.ok:
    raise RuntimeError(game)

home = game["teams"].get(game["home"]["teamId"], {}).get("abbreviation")
away = game["teams"].get(game["away"]["teamId"], {}).get("abbreviation")
print(away, game["away"]["points"], "at", home, game["home"]["points"], game["status"])
```

## Read a football game's live score

Use `GET /x/sports/{league}/games/{id}` for 1 game's score, clock & situation. Find the game ID with
[List football games](https://docs.xquik.com/api-reference/x/sports-games.md). Call it again to follow a live game.

* `home` & `away` hold each team's `teamId`, `points` & `timeoutsLeft`.
* `periods` lists the points of each period, in order.
* `situation` has the down, the yards to go & the team with the ball.
* `lastPlay` is the latest play, with the fields [Get football plays](https://docs.xquik.com/api-reference/x/sports-game-plays.md) returns.
* `teams` & `players` hold each team & player once, keyed by ID.

`situation` & `lastPlay` are null before kickoff. Fields such as `teamId` & `playerId` are keys of
`teams` & `players`.

## Path parameters

| Path parameter | Type | Required | Description |
| - | - | - | - |
| `league` | `string` | Yes | `nfl` for the NFL or `ncaafb` for college football, in any case. Another value gets a free `400 invalid_league`. |
| `id` | `string` | Yes | Game ID, a number up to 19 digits, such as `2055084502741811200`. [List football games](https://docs.xquik.com/api-reference/x/sports-games.md) returns it as `id`. Another value gets a free `400 invalid_game_id`. |

## Query parameters

| Query parameter | Type | Required | Description |
| - | - | - | - |
| `fields` | `string` | No | Fields to keep in each row, comma-separated, such as `id,text,author.username`. Use dots for nested fields. Case & underscores do not matter. A row that lacks a field leaves it out. Cursors, counts & diagnostics always stay. An unknown name returns `400 unknown_field` with the valid names, before any read. The price stays the same. |
| `omit` | `string` | No | Fields to drop from each row, comma-separated, such as `entities,media`. It takes the same names as `fields`. With `fields`, it drops from the kept fields. |

## Headers

| Header | Type | Required | Description |
| - | - | - | - |
| `x-api-key` | `string` | No | Full account key. Sessions and OAuth also work. |
| `Authorization` | `string` | No | `Bearer xq_your_guest_key_here` for `paid_reads`. |

## Response

### 200 OK

| Field | Type | Description |
| - | - | - |
| `id` | `string` | The game ID from your request. |
| `league` | `string` | The league from your request, `nfl` or `ncaafb`. |
| `seasonId` | `string` | X's ID for the season. NFL games have one. |
| `seasonType` | `string` | The part of the season, such as `RegularSeason`. X stopped sending it with a game on 2026-10-24, so it is null. |
| `week` | `number` | The week of the season. X stopped sending it with a game on 2026-10-24, so it is null. [List football games](https://docs.xquik.com/api-reference/x/sports-games.md) still has each game's week. |
| `startsAt` | `string` | The kickoff time in UTC. Null when X sends a time Xquik cannot read. |
| `venue` | `string` | The stadium. |
| `status` | `string` | X's game status, such as `Scheduled`, `InProgress` or `Closed`. |
| `clock` | `string` | The game clock, as X writes it. |
| `quarter` | `number` | The current or last quarter. |
| `situation` | `object` | Down & distance now, or null before kickoff. |
| `situation.down` | `number` | The down, from 1 to 4. |
| `situation.yardsToGo` | `number` | The yards needed for a first down. |
| `situation.yardline` | `number` | The yard line of the ball. |
| `situation.yardlineTeamId` | `string` | The team whose half the ball is in, a key of `teams`. |
| `situation.possessionTeamId` | `string` | The team with the ball, a key of `teams`. |
| `home` | `object` | The home team's `teamId`, a key of `teams`, its `points` & its `timeoutsLeft`. |
| `away` | `object` | The away team's `teamId`, a key of `teams`, its `points` & its `timeoutsLeft`. |
| `periods` | `object[]` | Points by period, in order. Each has `type`, such as `Quarter`, `number`, `sequence` from 1, `homePoints` & `awayPoints`. |
| `lastPlay` | `object` | The latest play, or null before kickoff. It has the play fields of [Get football plays](https://docs.xquik.com/api-reference/x/sports-game-plays.md). Each step names its players. A step's players stay empty until known. |
| `teams` | `object` | The teams this answer names, keyed by team ID. |
| `players` | `object` | The players this answer names, keyed by player ID. |

Each value in `teams` has these fields.

| Field | Type | Description |
| - | - | - |
| `id` | `string` | The team ID that games & players refer to. |
| `name` | `string` | The team's full name, such as `San Francisco 49ers`. |
| `shortName` | `string` | The team's short name. |
| `abbreviation` | `string` | The team's abbreviation, such as `SF`. |
| `alternateId` | `string` | Another ID X keeps for the team. College plays & drives name a side by it. |
| `location` | `string` | The school or place the team plays for. College schedules & a game's audience send it. |
| `colors` | `object[]` | The team's colors. Each has `r`, `g` & `b`, from 0 to 255. |
| `logos` | `object` | The team's logo links. `default` is the one X shows. `light` & `dark` suit light or dark backgrounds. |
| `xUserId` | `string` | The user ID of the team's X account. Pass it to [Get user](https://docs.xquik.com/api-reference/x/twitter-profile-lookup.md). |
| `record` | `object` | The team's `wins`, `losses` & `ties` this season. X sends it only in college football games. |
| `recentGames` | `object[]` | The team's recent games, newest first. Games without a kickoff time come last. Each has `id`, `startsAt`, `venue`, `status`, `clock`, `quarter`, `home` & `away`. `home` & `away` hold `teamId` & `points`. X sends them only with the teams of a college football game. The list is empty elsewhere. |

Each value in `players` has these fields.

| Field | Type | Description |
| - | - | - |
| `id` | `string` | The player ID that plays & stats refer to. |
| `teamId` | `string` | The player's team, a key of `teams`. |
| `name` | `string` | The player's full name. |
| `shortName` | `string` | The name play descriptions use, such as `B.Purdy`. |
| `jersey` | `string` | The jersey number, as text. |
| `position` | `string` | The position, such as `QB` or `DE`. |
| `college` | `string` | The college the player came from. |
| `birthPlace` | `string` | Where the player was born. X sends it only for NFL players. |
| `birthDate` | `string` | The birth date, as `YYYY-MM-DD`. |
| `headshots` | `object` | Photo links in `original`, `large`, `medium` & `small`. Any of them can be null. |
| `xUser` | `object` | The player's X account, with `id`, `username` & `blueVerified`. Null when the player has none. Rosters also fill `protected`, `superFollowEligible` & the highlighted `labelType`, such as `BusinessLabel`. Other answers send them as null. |

### 400 Invalid game ID

`{ "error": "invalid_game_id", "message": "Send a numeric game ID, such as 2055084502741811200." }`




The game ID is not a number. A league other than `nfl` or `ncaafb` gets `invalid_league`. Both
answers are free.

### 404 Game not found

`{ "error": "game_not_found", "message": "Game not found. Find game IDs with GET /x/sports/nfl/games." }`




X knows no game with this ID in the league. This answer is free.

### 401 Unauthenticated

Anonymous requests get `WWW-Authenticate: Bearer` and a guest wallet checkout action. This is not a Payment challenge.

### 402 Payment required

Account keys get account options. Guest keys get guest top-up only.
No checkout starts automatically. Confirm any payment action.

### 502 X API unavailable

The read service returned an error. Retry after a short delay.

> [!NOTE]
>
> **Related.** [List football games](https://docs.xquik.com/api-reference/x/sports-games.md) · [Get football plays](https://docs.xquik.com/api-reference/x/sports-game-plays.md) · [Get football box score](https://docs.xquik.com/api-reference/x/sports-game-box-score.md)

## Response examples

### 200 example

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/bash.json","/languages/csharp.json","/languages/go.json","/languages/java.json","/languages/javascript.json","/languages/kotlin.json","/languages/php.json","/languages/python.json","/languages/ruby.json","/languages/typescript.json"]}}
{
  "id": "2055084502741811200",
  "league": "nfl",
  "seasonId": "2039131233582546945",
  "seasonType": null,
  "week": null,
  "startsAt": "2026-10-20T00:15:00.000Z",
  "venue": "Levi's Stadium",
  "status": "Closed",
  "clock": "00:00:00",
  "quarter": 4
}
```

* **400** `{ "error": "invalid_input", "message": "Invalid input. Check the request body." }`
* **401** `{ "error": "unauthenticated", "message": "Authentication required. Provide a valid API key or bearer token." }`
* **402** `{ "error": "insufficient_credits", "message": "Insufficient credits. Top up or subscribe to continue." }`
* **403** `{ "error": "api_key_paused", "message": "This API key is paused. Resume it at dashboard.xquik.com/api-keys to use it again." }`
* **404** `{ "error": "not_found", "message": "Resource not found." }`
* **424** `{ "error": "x_api_unavailable", "message": "X data source temporarily unavailable. Try again later." }`
* **429** `{ "error": "rate_limit_exceeded", "message": "Too many requests. Try again later.", "retryAfter": 60 }`
* **502** `{ "error": "x_api_unavailable", "message": "X data source temporarily unavailable. Try again later." }`
* **503** `{ "error": "x_api_unavailable", "message": "Xquik is busy right now. Retry shortly." }`


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.