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

# Football game schedule & IDs, X (Twitter) API docs

> List NFL or college football games in a time window, with teams, kickoff times, live scores & the game IDs X's sports pages use. 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`

**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 -G "https://xquik.com/api/v1/x/sports/nfl/games" \
  --data-urlencode "from=2026-10-15" \
  --data-urlencode "to=2026-10-22" \
  -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 params = new URLSearchParams({ from: "2026-10-15", to: "2026-10-22" });
const response = await fetch(`https://xquik.com/api/v1/x/sports/nfl/games?${params}`, {
  headers: { "x-api-key": "xq_your_api_key_here" },
});
const body = await response.json();
if (!response.ok) throw new Error(JSON.stringify(body));

for (const game of body.games) {
  const home = body.teams[game.home.teamId]?.abbreviation;
  const away = body.teams[game.away.teamId]?.abbreviation;
  console.log(`${game.id} ${away} ${game.away.points} at ${home} ${game.home.points}`);
}
```

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

response = requests.get(
    "https://xquik.com/api/v1/x/sports/nfl/games",
    params={"from": "2026-10-15", "to": "2026-10-22"},
    headers={"x-api-key": "xq_your_api_key_here"},
)
body = response.json()
if not response.ok:
    raise RuntimeError(body)

for game in body["games"]:
    home = body["teams"].get(game["home"]["teamId"], {}).get("abbreviation")
    away = body["teams"].get(game["away"]["teamId"], {}).get("abbreviation")
    print(game["id"], away, game["away"]["points"], "at", home, game["home"]["points"])
```

## Find NFL & college football games

Use `GET /x/sports/{league}/games` to list a league's games & find their IDs.
Send `nfl` for the NFL or `ncaafb` for college football.

* `id` is the game ID that the scoreboard, plays & box score routes take.
* `home` & `away` name each team by `teamId`, with its points so far.
* `teams` holds each team once, by team ID, with its name, colors & logos.
* `status` tells games apart, such as `Scheduled`, `InProgress` or `Closed`.

Games come earliest first. Without `from` or `to`, X picks about 5 weeks around today.
Send 1 of them & the window spans 7 days from it.




To follow 1 team, send its ID in `team`. Copy the ID from `teamIds` of any game.

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

## Query parameters

| Query parameter | Type | Required | Description |
| - | - | - | - |
| `from` | `string` | No | Start of the window. Send an ISO 8601 date or time, such as `2026-10-01`, or Unix seconds. A time without a zone reads as UTC. Defaults to 7 days before `to`. Also read as `sinceTime`. |
| `to` | `string` | No | End of the window, in the forms `from` takes. Defaults to 7 days after `from`. Also read as `untilTime`. |
| `team` | `string` | No | Keeps 1 team's games, by team ID. For example, `689566294702555136` is the San Francisco 49ers. Each game lists its `teamIds`. Also read as `teamId` or `team_id`. |

### Choose fields

| 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 |
| - | - | - |
| `league` | `string` | The league from your request, `nfl` or `ncaafb`. |
| `games` | `object[]` | The league's games in the window, earliest first. |
| `games[].id` | `string` | The game ID that [Get football scoreboard](https://docs.xquik.com/api-reference/x/sports-game.md) and the other game routes take. |
| `games[].seasonType` | `string` | The part of the season, such as `RegularSeason`. |
| `games[].week` | `number` | The week of the season. |
| `games[].startsAt` | `string` | The kickoff time in UTC. Null when X sends a time Xquik cannot read. |
| `games[].status` | `string` | X's game status, such as `Scheduled`, `InProgress` or `Closed`. |
| `games[].clock` | `string` | The game clock, as X writes it. |
| `games[].quarter` | `number` | The current or last quarter. |
| `games[].home` | `object` | The home team's `teamId`, a key of `teams`, & its `points` so far. |
| `games[].away` | `object` | The away team's `teamId`, a key of `teams`, & its `points` so far. |
| `games[].teamIds` | `string[]` | The game's teams, keys of `teams`. |
| `games[].periods` | `object[]` | The periods played so far. Each has `type`, such as `Quarter`. The scoreboard adds each period's points. |
| `games[].odds` | `object` | Betting odds for `home` & `away`, or null when X has none. Each side has `moneyLine`, `spread` & `total`, as X writes them. X sends `moneyLine` for the away team only. |
| `teams` | `object` | The teams the games name, keyed by team 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. |

### 400 Invalid input

`{ "error": "invalid_league", "message": "Send nfl or ncaafb as the league, such as /x/sports/nfl/games." }`




The league is not `nfl` or `ncaafb`. This answer is free. A `from`, `to` or `team` Xquik cannot read
gets `invalid_input`. Its message says what to send.

### 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]
>
> **Next steps.** Pass a game `id` to [Get football scoreboard](https://docs.xquik.com/api-reference/x/sports-game.md). The same `id` works with [Get football plays](https://docs.xquik.com/api-reference/x/sports-game-plays.md) and [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"]}}
{
  "league": "nfl",
  "games": [
    {
      "id": "2055084502741811200",
      "seasonType": "RegularSeason",
      "week": 6,
      "startsAt": "2026-10-20T00:15:00.000Z",
      "status": "Closed"
    }
  ],
  "teams": {}
}
```

* **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." }`
* **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.