> ## 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 tweet feed, X (Twitter) API docs

> Get top or latest X (Twitter) posts about 1 NFL or college football game. Read them before, during or after it, with the search behind them. 1 credit per post.

> 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}/posts`

**1 credit per post** · Up to 20 posts per page

[All plans](https://xquik.com) from \$0.00012/credit · 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/posts?queryType=Top" \
  -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}/posts?queryType=Top`,
  { headers: { "x-api-key": "xq_your_api_key_here" } },
);
const page = await response.json();
if (!response.ok) throw new Error(JSON.stringify(page));

for (const tweet of page.tweets) {
  console.log(`@${tweet.author.username}: ${tweet.likeCount} likes`);
}
```

```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}/posts",
    params={"queryType": "Top"},
    headers={"x-api-key": "xq_your_api_key_here"},
)
page = response.json()
if not response.ok:
    raise RuntimeError(page)

for tweet in page["tweets"]:
    print(f"@{tweet['author']['username']}: {tweet['likeCount']} likes")
```

## Read what X shows about a game

Use `GET /x/sports/{league}/games/{id}/posts` for the posts on a game's page on X. Find the game ID
with [List football games](https://docs.xquik.com/api-reference/x/sports-games.md).

* `queryType=Top` returns the posts X ranks highest. `queryType=Latest` returns the newest first.
* Each post has the same fields as [Search tweets](https://docs.xquik.com/api-reference/x/search-tweets.md) returns.
* `query` is the X (Twitter) search that finds the posts. X builds it from the teams, hashtags, team
  accounts & star players. X adds the game's time window.

Pass `query` to [Search tweets](https://docs.xquik.com/api-reference/x/search-tweets.md) to add filters like language,
media or minimum likes. A game has posts before kickoff, during the game & after it.

## 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 |
| - | - | - | - |
| `queryType` | `string` | No | `Top` for the posts X ranks highest or `Latest` for the newest. Any case works. `Relevance` & `Recency` work too, & so do the names `order` & `sort`. Send the same value with each cursor. |
| `cursor` | `string` | No | `next_cursor` from the previous page. |
| `pageSize` | `number` | No | Posts per page, up to `10000`. A larger value gets the largest page. The source or your credits can return fewer. Default `20`. |

### 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 |
| - | - | - |
| `tweets` | `object[]` | The posts in X's order, as [Search tweets](https://docs.xquik.com/api-reference/x/search-tweets.md) returns them. Each has its author, text, media & metrics. |
| `has_next_page` | `boolean` | `true` while more posts follow. |
| `next_cursor` | `string` | Pass it as `cursor` for the next page. Empty on the last page. |
| `query` | `string \| null` | The X (Twitter) search that finds this game's posts for your order. It's `null` when X sends a timeline Xquik cannot read. |

### 400 Invalid input

`{ "error": "invalid_params", "message": "Unknown queryType. Use Latest or Top." }`




`queryType` is not `Top`, `Latest`, `Relevance` or `Recency`. A league other than `nfl` or `ncaafb`
gets `invalid_league`. A game ID that is not a number gets `invalid_game_id`. These 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. 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.

### 503 Service busy

Xquik is busy, or X sent an answer Xquik cannot read. Wait for the `Retry-After` header, then send
the request again. The request costs nothing.

> [!NOTE]
>
> **Related.** [List football games](https://docs.xquik.com/api-reference/x/sports-games.md) · [Get football scoreboard](https://docs.xquik.com/api-reference/x/sports-game.md) · [Search tweets](https://docs.xquik.com/api-reference/x/search-tweets.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"]}}
{
  "tweets": [
    {
      "id": "2102761519985332442",
      "text": "This galaxy is a little extra.\n\nMeet Messier 106, a spiral galaxy with an extra set of arms. These two additional arms are made of gas heated up by jets from the galaxy’s central black hole. The jets’ superheated shockwaves are depicted in royal blue by @chandraxray. https://t.co/421Lzs0r0c",
      "retweetCount": 1364,
      "replyCount": 271,
      "likeCount": 9775
    }
  ],
  "has_next_page": true,
  "next_cursor": "DAACCgACHVOxUHMAJxAKAAMdU7FQcv_Y8AgABAAAAAILAAUAAADwRW1QQzZ3QUFBZlEvZ0dKTjB2R3AvQUFBQUJRZFVMTzZONXZBcWgxUTBKTlBXeERDSFZDN3g5QVd3SThkVVhQNHN0ZXdKaDFRcGJ5Zm1uQnpIVkNuT040YnNIVWRVTUcxMUZaaGVSMVJTek56VnVBbEhWQzR5NEFhNGVZZFVMTDVZOXNCckIxUXJmN0NtMUZCSFZDeCt2ZWFNTEFkVUtSRkF4b2dsaDFRbVJETUY3QmNIVkNJNGpjV0lLa2RVVW15QTFkUlh4MVJHclhDVjJIdEhWQ3lGeWthUU1FZFVMSmlFOW9BVEIxUmxiS1gxdEZCCAAGAAAAAAgABwAAAAAMAAgKAAEdUIjiNxYgqQAAAA",
  "query": "(#WASvsSF OR #WASatSF OR \"San Francisco 49ers\" OR \"Washington Commanders\" OR @49ers OR @Commanders) since_time:1792455300 until_time:1792541700 -filter:nativeretweets"
}
```

* **400** `{ "error": "invalid_input", "message": "Invalid input. Check the request body." }`
* **401** `{ "error": "unauthenticated", "message": "Authentication required." }`
* **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.