> ## 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 schedule API with game IDs

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

**200**

```json theme={null}
{
  "league": "nfl",
  "games": [
    {
      "id": "2055084502741811200",
      "seasonType": "RegularSeason",
      "week": 6,
      "startsAt": "2026-10-20T00:15:00.000Z",
      "status": "Closed"
    }
  ],
  "teams": {}
}
```

**400**

```json theme={null}
{
  "error": "invalid_input",
  "message": "Invalid input. Check the request body."
}
```

**401**

```json theme={null}
{
  "error": "unauthenticated",
  "message": "Authentication required. Provide a valid API key or bearer token."
}
```

**402**

```json theme={null}
{
  "error": "insufficient_credits",
  "message": "Insufficient credits. Top up or subscribe to continue."
}
```

**424**

```json theme={null}
{
  "error": "x_api_unavailable",
  "message": "X data source temporarily unavailable. Try again later."
}
```

**429**

```json theme={null}
{
  "error": "rate_limit_exceeded",
  "message": "Too many requests. Try again later.",
  "retryAfter": 60
}
```

**502**

```json theme={null}
{
  "error": "x_api_unavailable",
  "message": "X data source temporarily unavailable. Try again later."
}
```

**503**

```json theme={null}
{
  "error": "x_api_unavailable",
  "message": "Xquik is busy right now. Retry shortly."
}
```

> For the complete documentation index, see [llms.txt](/llms.txt).

**1 credit per request** · [All plans](https://xquik.com/#pricing) from \$0.00012/credit · Direct [MPP](/mpp/machine-payments-protocol.md) at USD 0.00015 per call · Supports [guest paid reads](/guides/guest-wallets.md)

```bash cURL theme={null}
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={null}
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={null}
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

**league** `string` *required*

`nfl` for the NFL or `ncaafb` for college football, in any case. Another value gets a free
`400 invalid_league`.

## Query parameters

**from** `string`

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`

End of the window, in the forms `from` takes. Defaults to 7 days after `from`. Also read as
`untilTime`.

**team** `string`

Keeps 1 team's games, by team ID, such as `689566294702555136` for the San Francisco 49ers. Each
game lists its `teamIds`. Also read as `teamId` or `team_id`.

### Choose fields

**fields** `string`

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`

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

**x-api-key** `string`

Full account key. Sessions and OAuth also work.

**Authorization** `string`

`Bearer xq_your_guest_key_here` for `paid_reads`.

## Response

### 200 OK

**league** `string`

The league from your request, `nfl` or `ncaafb`.

**games** `object[]`

The league's games in the window, earliest first.

**id** `string`

The game ID that [Get football scoreboard](/api-reference/x/sports-game.md) and the other game routes
take.

**seasonType** `string`

The part of the season, such as `RegularSeason`.

**week** `number`

The week of the season.

**startsAt** `string`

The kickoff time in UTC. Null when X sends a time Xquik cannot read.

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

**home** `object`

The home team's `teamId`, a key of `teams`, & its `points` so far.

**away** `object`

The away team's `teamId`, a key of `teams`, & its `points` so far.

**teamIds** `string[]`

The game's teams, keys of `teams`.

**periods** `object[]`

The periods played so far. Each has `type`, such as `Quarter`. The scoreboard adds each period's
points.

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

**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 a college team plays for. X sends it only in college schedules.

**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](/api-reference/x/twitter-profile-lookup.md).

### 400 Invalid input

```json theme={null}
{
  "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`, and 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.

```json theme={null}
{ "error": "unauthenticated" }
```

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

```json theme={null}
{ "error": "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](/api-reference/x/sports-game.md), [Get football plays](/api-reference/x/sports-game-plays.md) or [Get football box score](/api-reference/x/sports-game-box-score.md).


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