> ## 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 play-by-play API by drive

> Get every drive & play of 1 NFL or college football game from X, with each down & distance, players, penalties & linked video posts. 1 credit per request.

**200**

```json theme={null}
{
  "id": "2055084502741811200",
  "league": "nfl",
  "homeTeamId": "689566294702555136",
  "awayTeamId": "689566304366292992",
  "quarters": [
    {
      "id": "quarter-1",
      "number": 1,
      "sequence": 1,
      "drives": []
    }
  ],
  "teams": {},
  "players": {}
}
```

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

**404**

```json theme={null}
{
  "error": "not_found",
  "message": "Resource not found."
}
```

**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 "https://xquik.com/api/v1/x/sports/nfl/games/2055084502741811200/plays" \
  -H "x-api-key: xq_your_api_key_here" | jq
```

```javascript Node.js theme={null}
const gameId = "2055084502741811200";
const response = await fetch(`https://xquik.com/api/v1/x/sports/nfl/games/${gameId}/plays`, {
  headers: { "x-api-key": "xq_your_api_key_here" },
});
const game = await response.json();
if (!response.ok) throw new Error(JSON.stringify(game));

for (const quarter of game.quarters) {
  for (const drive of quarter.drives) {
    for (const play of drive.plays) {
      console.log(`Q${quarter.number} ${play.clock} ${play.description}`);
    }
  }
}
```

```python Python theme={null}
import requests

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

for quarter in game["quarters"]:
    for drive in quarter["drives"]:
        for play in drive["plays"]:
            print(f"Q{quarter['number']}", play["clock"], play["description"])
```

## Read every drive & play of a game

Use `GET /x/sports/{league}/games/{id}/plays` for a game's full play-by-play. Find the game ID with
[List football games](/api-reference/x/sports-games.md).

* `quarters` lists each quarter in order. Each quarter lists its `drives`, and each drive its `plays`.
* A drive has its clock, how it started & ended, its first downs & its net yards.
* A play has its clock, down & distance, description & the score after it.
* `details` lists each step of a play, with its players, yards & any penalty.
* `post` is the post X links to the play. `videoPostId` & `videoReplyPostId` point to its video.

Each player appears once in `players`, keyed by ID. Steps name players by `playerId`, with a
`playerRole` such as `Pass` or `Tackle`. Pass a post ID to [Get tweet](/api-reference/x/get-tweet.md)
to read it.

A whole game fits 1 response, so there are no pages. `quarters` is empty before kickoff.

NFL games name a side as `Home` or `Away` in `offense`, `defense`, `possession` & `yardlineSide`.
College games name it by the team's `alternateId` from `teams`.

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

**id** `string` *required*

Game ID, a number up to 19 digits, such as `2055084502741811200`.
[List football games](/api-reference/x/sports-games.md) returns it as `id`. Another value gets a free
`400 invalid_game_id`.

## Query parameters

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

**id** `string`

The game ID from your request.

**league** `string`

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

**homeTeamId** `string`

The home team, a key of `teams`.

**awayTeamId** `string`

The away team, a key of `teams`.

**quarters** `object[]`

The game's quarters, in order. Empty before kickoff.

**id** `string`

X's ID for the quarter within the game.

**number** `number`

The quarter's number.

**sequence** `number`

The quarter's place in the game, from 1.

**drives** `object[]`

The quarter's drives, in order.

**id** `string`

X's ID for the drive within the game.

**sequence** `number`

The drive's place in the game, from 1.

**offense** `string`

The team with the ball. `Home` or `Away` in NFL games, the team's `alternateId` in college games.

**defense** `string`

The team on defense, named the way `offense` names it.

**startClock** `string`

The game clock when the drive started, as `HH:MM:SS`.

**endClock** `string`

The game clock when the drive ended, as `HH:MM:SS`.

**startReason** `string`

How the drive started, such as `Kickoff` or `Punt`.

**endReason** `string`

How the drive ended, such as `Touchdown` or `Punt`.

**playCount** `number`

The drive's plays.

**firstDowns** `number`

The first downs the drive gained.

**netYards** `number`

The yards the drive gained.

**scoring** `boolean`

Whether the drive scored.

**plays** `object[]`

The drive's plays, in order.

**id** `string`

X's ID for the play within the game.

**sequence** `string`

The play's place in its drive, as X writes it.

**clock** `string`

The game clock when the play started, as `HH:MM:SS`.

**type** `string`

X's kind of play, such as `Pass`, `Rush`, `Punt` or `Conversion`.

**direction** `string`

Where the play went, such as `Left` or `Middle`.

**description** `string`

The play as the official play-by-play writes it.

**scoring** `boolean`

Whether the play scored points.

**homePoints** `number`

The home team's points after the play.

**awayPoints** `number`

The away team's points after the play.

**score** `object`

For a scoring play, its `points` & the `homePoints` & `awayPoints` after it. Null otherwise.

**start** `object`

Down & distance when the play started, or null.

**down** `number`

The down, from 1 to 4.

**yardsToGo** `number`

The yards needed for a first down.

**yardline** `number`

The yard line of the ball.

**yardlineSide** `string`

Whose half the ball was in. `Home` or `Away` in NFL games, the team's `alternateId` in college
games.

**possession** `string`

The team with the ball. `Home` or `Away` in NFL games, the team's `alternateId` in college games.

**onField** `object`

Flags X shows on the field, or null. `calledBack` means a penalty called the play back.
`penaltyOnField` means a flag was thrown. `timeout` means a timeout followed. `underReview` means
officials were reviewing the play.

**details** `object[]`

The play's steps, in order, such as a pass, a tackle or a penalty.

**sequence** `number`

The step's place in the play, from 1.

**category** `string`

X's kind of step, such as `Pass`, `Tackle` or `Penalty`.

**description** `string`

What happened in the step.

**direction** `string`

The direction X gives for the step.

**yards** `number`

The yards the step gained or lost.

**players** `object[]`

The players in the step. Each has `playerId`, a key of `players`, & `playerRole`, such as `Pass`,
`Receive` or `Tackle`.

**penalty** `object`

The penalty this step called, or null. It has `description`, `nextDown`, `result`, `yards` &
`teamId`, the penalized team.

**post** `object`

The post X links to the play, with `id` & the author's `username`. Null when X links none.

**videoPostId** `string`

The ID of a post with the play's video.

**videoReplyPostId** `string`

The ID of a reply with the play's video.

**teams** `object`

The teams this answer names, 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).

**players** `object`

The players this answer names, keyed by player ID.

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

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

### 400 Invalid game ID

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

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

```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]
>
> **Related.** [List football games](/api-reference/x/sports-games.md) · [Get football scoreboard](/api-reference/x/sports-game.md) · [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.