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

# Community notes by contributor, X (Twitter) API docs

> List every Community Note a contributor wrote, with its text, rating status, rater tags, and the post it is on. Includes notes x.com hides. 1 credit per note.

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

`GET https://xquik.com/api/v1/x/community-notes/contributors/{alias}/notes`

List the Community Notes 1 contributor wrote, newest first. Each note comes with the post it is on.

> [!NOTE]
>
> Requested result counts are upper bounds for paid authenticated calls. When remaining credits cannot cover the full page, Xquik returns fewer results. If zero paid results are affordable, it returns `402 insufficient_credits`.

**1 credit per note returned** · [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/community-notes/contributors/ardent-beach-friarbird/notes" \
  -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 alias = "ardent-beach-friarbird";
const url = `https://xquik.com/api/v1/x/community-notes/contributors/${alias}/notes`;
const response = await fetch(url, {
  headers: { "x-api-key": "xq_your_api_key_here" },
});
const data = await response.json();
if (!response.ok) throw new Error(JSON.stringify(data));

const nextCursor = data.has_next_page ? data.next_cursor : null;
const noteRows = data.notes.map((note) => ({
  contributor_alias: alias,
  note_id: note.id,
  rating_status: note.ratingStatus ?? null,
  text: note.text ?? null,
  post_id: note.postId ?? null,
  post_author: note.post?.author?.username ?? null,
  next_cursor: nextCursor,
}));
```

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

alias = "ardent-beach-friarbird"
response = requests.get(
    f"https://xquik.com/api/v1/x/community-notes/contributors/{alias}/notes",
    headers={"x-api-key": "xq_your_api_key_here"},
)
data = response.json()
if not response.ok:
    raise RuntimeError(data)

next_cursor = data["next_cursor"] if data["has_next_page"] else None
note_rows = [
    {
        "contributor_alias": alias,
        "note_id": note["id"],
        "rating_status": note.get("ratingStatus"),
        "text": note.get("text"),
        "post_id": note.get("postId"),
        "post_author": ((note.get("post") or {}).get("author") or {}).get("username"),
        "next_cursor": next_cursor,
    }
    for note in data["notes"]
]
```

The Node.js and Python snippets build 1 row per note. Store the rows with the cursor before you request the next page.

## Which notes does it return?

It returns every note the contributor wrote, whatever its rating. Only helpful notes show under posts on x.com. So
this list also holds the notes x.com hides.

* `ratingStatus` says how X rates the note now, such as `NeedsMoreRatings` or `CurrentlyRatedHelpful`.
* `helpfulTags` & `notHelpfulTags` say why raters called it helpful or not.
* `timeToHelpfulFromNoteMs` says how long the note took to be rated helpful.
* `post` is the post the note is on. It has the same fields as [Get tweet](https://docs.xquik.com/api-reference/x/get-tweet.md).

For a post X no longer shows, `post` is `null`. `postId` still names it. `postUnavailable.reason` says why when X
gives a reason, such as `Suspended`.

## Page through a contributor's notes

Each page returns `has_next_page` and `next_cursor`. Send `next_cursor` back as `cursor`. Stop when `has_next_page` is
`false`.




A cursor X never issued returns `400 invalid_cursor`, which is free. Start again without `cursor`, then use
`next_cursor`.




Use the note `id` as the key in your store. Overlapping reads then add no duplicates.

## Path parameters

| Path parameter | Type | Required | Description |
| - | - | - | - |
| `alias` | `string` | Yes | Contributor alias, such as `ardent-beach-friarbird`. The URL-encoded contributor URL also works, such as `x.com/i/communitynotes/u/ardent-beach-friarbird`. Any letter case works. |

## Query parameters

| Query parameter | Type | Required | Description |
| - | - | - | - |
| `cursor` | `string` | No | Pagination cursor from a previous response. Omit for the first page. |
| `pageSize` | `integer` | No | Notes per page, from `1` to `10`. Defaults to `10`. Also read as `limit`, `count`, `max_results`, `maxItems`, `max_items` & `per_page`. |

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

X leaves out a field that a note lacks. Only `id` is always present.

| Field | Type | Description |
| - | - | - |
| `notes` | `object[]` | The contributor's notes, newest first. |
| `notes[].id` | `string` | Note ID. |
| `notes[].createdAt` | `string` | When the contributor wrote the note, as ISO 8601. |
| `notes[].language` | `string` | Language code of the note. |
| `notes[].classification` | `string` | What the writer says of the post, such as `MisinformedOrPotentiallyMisleading` or `NotMisleading`. |
| `notes[].text` | `string` | What the note says. |
| `notes[].entities` | `object[]` | Links, tags & accounts inside the text, each with `fromIndex`, `toIndex` & `ref`. |
| `notes[].contributor` | `object` | The note's writer, with the counts X sends beside a note. [Get notes contributor](https://docs.xquik.com/api-reference/x/community-notes-contributor.md) returns every count. |
| `notes[].ratingStatus` | `string` | X's current rating, such as `NeedsMoreRatings`, `CurrentlyRatedHelpful` or `CurrentlyRatedNotHelpful`. |
| `notes[].helpfulTags` | `string[]` | Why raters called the note helpful. |
| `notes[].notHelpfulTags` | `string[]` | Why raters called the note not helpful. |
| `notes[].decidedBy` | `string` | The X scoring model that set the rating. |
| `notes[].fullyVisibleModel` | `boolean` | Whether X marks that scoring model as fully visible. |
| `notes[].abovePcrhThreshold` | `boolean` | Whether the note scores above X's bar for a possible helpful rating. |
| `notes[].appealStatus` | `string` | Whether the rating is under appeal. |
| `notes[].deleted` | `boolean` | Whether the writer deleted the note. |
| `notes[].tombstone` | `string` | X's notice in place of a deleted note. |
| `notes[].isApiAuthor` | `boolean` | Whether the note came through X's API. |
| `notes[].isMediaNote` | `boolean` | Whether the note is about the post's media. |
| `notes[].mediaNoteMatchCount` | `number` | Other posts X matched a media note to. |
| `notes[].isUrlNote` | `boolean` | Whether the note is on a link. |
| `notes[].displayUrl` | `string` | The link a link note is on, as X shows it. |
| `notes[].isTranslatable` | `boolean` | Whether X offers a translation of the note. |
| `notes[].timeToHelpfulFromNoteMs` | `number` | Milliseconds from the note's creation to its helpful rating. |
| `notes[].timeToHelpfulFromPostMs` | `number` | Milliseconds from the post's creation to the note's helpful rating. |
| `notes[].impressionCount` | `number` | Views of the note, when X shares them. |
| `notes[].postId` | `string` | ID of the post the note is on. |
| `notes[].post` | `object \| null` | The post the note is on, or `null` when X no longer shows it. |
| `notes[].postUnavailable` | `object` | Why X shows no post, when X says. It holds `reason`. |
| `has_next_page` | `boolean` | Whether more notes follow. |
| `next_cursor` | `string` | Cursor for the next page. Empty at the end of the list. |

### 400 Invalid alias or cursor

A cursor X never issued returns `invalid_cursor`. Start again without `cursor`. Both answers are free.

### 404 Contributor not found

No contributor holds the alias. 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.

### 429 Rate limit exceeded

You exceeded your tier rate limit. Wait for the `Retry-After` header before retrying.

### 424 Dependency failed

The normalized v1 response contract can return 424 when the read service is unavailable.

> [!NOTE]
>
> **Related.** [Get notes contributor](https://docs.xquik.com/api-reference/x/community-notes-contributor.md) · [Deleted notes](https://docs.xquik.com/api-reference/x/community-notes-contributor-deleted-notes.md) · [Get tweet](https://docs.xquik.com/api-reference/x/get-tweet.md)

> [accordion] Related tweet, reply & media APIs
>
> * Tweets
>   * [Get tweet](https://docs.xquik.com/api-reference/x/get-tweet.md)
>   * [Tweet insights](https://docs.xquik.com/api-reference/x/tweet-engagement-insights.md)
>   * [Batch tweets](https://docs.xquik.com/api-reference/x/batch-tweets.md)
>   * [Tweet thread](https://docs.xquik.com/api-reference/x/tweet-thread.md)
>   * [Hidden replies](https://docs.xquik.com/api-reference/x/tweet-hidden-replies.md)
>   * [Translate tweet](https://docs.xquik.com/api-reference/x/tweet-translation.md)
>   * [Embed tweet](https://docs.xquik.com/api-reference/x/tweet-embed.md)
>   * [Resolve links](https://docs.xquik.com/api-reference/x/resolve-links.md)
>   * [Tweet subtitles](https://docs.xquik.com/api-reference/x/tweet-subtitles.md)
>   * [X Article](https://docs.xquik.com/api-reference/x/get-article.md)
> * Analysis
>   * [Sentiment analysis](https://docs.xquik.com/api-reference/x/sentiment-analysis.md)
>   * [Brand mentions](https://docs.xquik.com/api-reference/x/brand-monitoring.md)
>   * [News classification](https://docs.xquik.com/api-reference/x/news-classification.md)
>   * [Market signals](https://docs.xquik.com/api-reference/x/market-signals.md)
>   * [Viral score](https://docs.xquik.com/api-reference/x/viral-score.md)
>   * [Classify posts](https://docs.xquik.com/api-reference/x/classify-tweets.md)
> * Engagement
>   * [Tweet replies](https://docs.xquik.com/api-reference/x/tweet-replies.md)
>   * [Quote tweets](https://docs.xquik.com/api-reference/x/tweet-quotes.md)
>   * [Likers](https://docs.xquik.com/api-reference/x/favoriters.md)
>   * [Reposters](https://docs.xquik.com/api-reference/x/retweeters.md)
>   * [Reposter IDs](https://docs.xquik.com/api-reference/x/retweeter-ids.md)
>   * [Check repost](https://docs.xquik.com/api-reference/x/tweet-repost-check.md)
> * Profiles
>   * [User tweets](https://docs.xquik.com/api-reference/x/user-tweets.md)
>   * [Batch user tweets](https://docs.xquik.com/api-reference/x/batch-user-tweets.md)
>   * [User replies](https://docs.xquik.com/api-reference/x/user-replies.md)
>   * [User likes](https://docs.xquik.com/api-reference/x/user-likes.md)
>   * [User media](https://docs.xquik.com/api-reference/x/user-media.md)
>   * [User highlights](https://docs.xquik.com/api-reference/x/user-highlights.md)
>   * [User articles](https://docs.xquik.com/api-reference/x/user-articles.md)
> * Feeds
>   * [List tweets](https://docs.xquik.com/api-reference/x/list-tweets.md)
>   * [Trends](https://docs.xquik.com/api-reference/x/trends.md)
>   * [Trends history](https://docs.xquik.com/api-reference/x/trends-history.md)
>   * [Top tweets](https://docs.xquik.com/api-reference/x/top-tweets.md)
>   * [Trend locations](https://docs.xquik.com/api-reference/x/trend-locations.md)
>   * [Search Spaces](https://docs.xquik.com/api-reference/x/search-spaces.md)
>   * [Get Space](https://docs.xquik.com/api-reference/x/get-space.md)
>   * [Space replay](https://docs.xquik.com/api-reference/x/space-replay.md)
>   * [Get broadcast](https://docs.xquik.com/api-reference/x/get-broadcast.md)
>   * [User live status](https://docs.xquik.com/api-reference/x/user-live-status.md)
>   * [User shadowban](https://docs.xquik.com/api-reference/x/user-shadowban.md)
>   * [Notes contributor](https://docs.xquik.com/api-reference/x/community-notes-contributor.md)
>   * [Contributor notes](https://docs.xquik.com/api-reference/x/community-notes-contributor-notes.md)
>   * [Deleted notes](https://docs.xquik.com/api-reference/x/community-notes-contributor-deleted-notes.md)
>   * [Hashflags](https://docs.xquik.com/api-reference/x/hashflags.md)
>   * [Search places](https://docs.xquik.com/api-reference/x/search-places.md)
>   * [Download media](https://docs.xquik.com/api-reference/x/download-media.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"]}}
{
  "notes": [
    {
      "id": "2026375778254868976",
      "createdAt": "2026-02-24T19:16:48.435Z",
      "language": "en",
      "classification": "MisinformedOrPotentiallyMisleading",
      "contributor": {
        "alias": "ardent-beach-friarbird",
        "notesCount": {
          "currentlyRatedHelpful": 1,
          "currentlyRatedNotHelpful": 2
        },
        "ratingsCount": {
          "successful": {
            "total": 49
          },
          "unsuccessful": {
            "helpfulCount": 15,
            "notHelpfulCount": 4
          }
        }
      }
    }
  ],
  "has_next_page": true,
  "next_cursor": "-1767098234260"
}
```

* **400** `{ "error": "invalid_contributor_alias", "message": "Send a Community Notes alias or its x.com/i/communitynotes/u URL." }`
* **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": "contributor_not_found", "message": "Contributor not found. Check the alias on its x.com/i/communitynotes/u page." }`
* **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.