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

# Top tweets API: most liked & viewed posts on X

> Get the top Twitter and X tweets by likes, replies, quotes, bookmarks, shares, or views for a day, week, or month, worldwide or by country. 1 credit per tweet.

<Panel>
  <Tabs defaultTabIndex={0} sync={false}>
    <Tab title="200" id="response-x-top-tweets-200">
      ```json theme={null}
      {
        "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": "DAAHCgABHTK6Vr___-sLAAIAAAATMjEwMTc3MDE4NjE1NjA1Mjk1OQgAAwAAAAIAAA",
        "filtered_count": 0
      }
      ```
    </Tab>

    <Tab title="400" id="response-x-top-tweets-400">
      ```json theme={null}
      {
        "error": "invalid_input",
        "message": "Invalid input. Check the request body."
      }
      ```
    </Tab>

    <Tab title="401" id="response-x-top-tweets-401">
      ```json theme={null}
      {
        "error": "unauthenticated",
        "message": "Authentication required."
      }
      ```
    </Tab>

    <Tab title="402" id="response-x-top-tweets-402">
      ```json theme={null}
      {
        "error": "insufficient_credits",
        "message": "Insufficient credits. Top up or subscribe to continue."
      }
      ```
    </Tab>

    <Tab title="424" id="response-x-top-tweets-424">
      ```json theme={null}
      {
        "error": "x_api_unavailable",
        "message": "X data source temporarily unavailable. Try again later."
      }
      ```
    </Tab>

    <Tab title="429" id="response-x-top-tweets-429">
      ```json theme={null}
      {
        "error": "rate_limit_exceeded",
        "message": "Too many requests. Try again later.",
        "retryAfter": 60
      }
      ```
    </Tab>

    <Tab title="502" id="response-x-top-tweets-502">
      ```json theme={null}
      {
        "error": "x_api_unavailable",
        "message": "X data source temporarily unavailable. Try again later."
      }
      ```
    </Tab>

    <Tab title="503" id="response-x-top-tweets-503">
      ```json theme={null}
      {
        "error": "x_api_unavailable",
        "message": "Xquik is busy right now. Retry shortly."
      }
      ```
    </Tab>
  </Tabs>
</Panel>

<blockquote className="agent-llms-directive">
  For the complete documentation index, see <a href="/llms.txt">llms.txt</a>.
</blockquote>

<Callout icon="coins" color="#5c3327">
  **1 credit per tweet** · Up to 100 tweets per list · [All plans](https://xquik.com/#pricing) from \$0.00012/credit · Supports [guest paid reads](/guides/guest-wallets)
</Callout>

<CodeGroup>
  ```bash cURL theme={null}
  curl --get "https://xquik.com/api/v1/x/tweets/top" \
    --data-urlencode "metric=views" \
    --data-urlencode "window=week" \
    --data-urlencode "country=US" \
    -H "x-api-key: xq_your_api_key_here" | jq
  ```

  ```javascript Node.js theme={null}
  const params = new URLSearchParams({ metric: "views", window: "week", country: "US" });
  const response = await fetch(`https://xquik.com/api/v1/x/tweets/top?${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 tweet of body.tweets) {
    console.log(`@${tweet.author.username}: ${tweet.viewCount} views`);
  }
  ```

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

  response = requests.get(
      "https://xquik.com/api/v1/x/tweets/top",
      params={"metric": "views", "window": "week", "country": "US"},
      headers={"x-api-key": "xq_your_api_key_here"},
  )
  body = response.json()
  if not response.ok:
      raise RuntimeError(body)

  for tweet in body["tweets"]:
      print(f'@{tweet["author"]["username"]}: {tweet.get("viewCount")} views')
  ```
</CodeGroup>

## The tweets X ranks highest

Use `GET /x/tweets/top` to list the tweets X ranks highest by one metric, as x.com's Inspiration page shows them. Pick
the metric and how far back to look. Narrow it to one country or one language, or leave both out for all of X.

Pages hold up to 20 tweets. Pass `next_cursor` as `cursor` for the next page. The list ends at 100 tweets.

## Query parameters

<ParamField query="metric" type="string" default="likes">
  What to rank tweets by: `likes`, `replies`, `quotes`, `bookmarks`, `shares`, or `views`. Singular names work too, such
  as `like`.
</ParamField>

<ParamField query="window" type="string" default="day">
  How far back to look: `day`, `week`, or `month`. Also takes `24h`, `7d`, `30d`, `daily`, `weekly`, and `monthly`.
</ParamField>

<ParamField query="country" type="string">
  Only tweets from one country, as a 2- or 3-letter ISO 3166 code, such as `US` or `USA`. Send `country` or `language`,
  not both.
</ParamField>

<ParamField query="language" type="string">
  Only tweets in one language, as a 2-letter code, such as `en`. Send `country` or `language`, not both.
</ParamField>

<ParamField query="cursor" type="string">
  `next_cursor` from the previous page.
</ParamField>

<ParamField query="pageSize" type="number" default="20">
  Tweets per page, from 1 to 100. Your credits can return fewer.
</ParamField>

## Headers

<ParamField header="x-api-key" type="string">
  Full account key. Sessions and OAuth also work.
</ParamField>

<ParamField header="Authorization" type="string">
  `Bearer xq_your_guest_key_here` for `paid_reads`.
</ParamField>

## Response

### 200 OK

<ResponseField name="tweets" type="object[]">
  The tweets in X's order, each with its author, text, media, and metrics, as [Search tweets](/api-reference/x/search-tweets)
  returns them.
</ResponseField>

<ResponseField name="has_next_page" type="boolean">
  `true` while more tweets follow, up to 100.
</ResponseField>

<ResponseField name="next_cursor" type="string">
  Pass it as `cursor` for the next page. Empty on the last page.
</ResponseField>

### 400 Invalid input

```json theme={null}
{ "error": "invalid_input", "message": "Send country or language, not both." }
```

The message says which parameter to fix.

### 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.** [Search tweets](/api-reference/x/search-tweets) · [Trends](/api-reference/x/trends) · [Get tweet](/api-reference/x/get-tweet)
</Note>

<div className="related-api-links">
  <Accordion title="Related tweet, reply & media APIs" icon="link">
    * Tweets: [Get tweet](/api-reference/x/get-tweet) · [Tweet insights](/api-reference/x/tweet-engagement-insights) · [Batch tweets](/api-reference/x/batch-tweets) · [Tweet thread](/api-reference/x/tweet-thread) · [Hidden replies](/api-reference/x/tweet-hidden-replies) · [Translate tweet](/api-reference/x/tweet-translation) · [Embed tweet](/api-reference/x/tweet-embed) · [Resolve links](/api-reference/x/resolve-links) · [Tweet subtitles](/api-reference/x/tweet-subtitles) · [X Article](/api-reference/x/get-article)
    * Analysis: [Sentiment analysis](/api-reference/x/sentiment-analysis) · [Brand mentions](/api-reference/x/brand-monitoring) · [News classification](/api-reference/x/news-classification) · [Market signals](/api-reference/x/market-signals) · [Viral score](/api-reference/x/viral-score) · [Classify posts](/api-reference/x/classify-tweets)
    * Engagement: [Tweet replies](/api-reference/x/tweet-replies) · [Quote tweets](/api-reference/x/tweet-quotes) · [Likers](/api-reference/x/favoriters) · [Reposters](/api-reference/x/retweeters) · [Reposter IDs](/api-reference/x/retweeter-ids) · [Check repost](/api-reference/x/tweet-repost-check)
    * Profiles: [User tweets](/api-reference/x/user-tweets) · [Batch user tweets](/api-reference/x/batch-user-tweets) · [User replies](/api-reference/x/user-replies) · [User likes](/api-reference/x/user-likes) · [User media](/api-reference/x/user-media) · [User highlights](/api-reference/x/user-highlights) · [User articles](/api-reference/x/user-articles)
    * Feeds: [List tweets](/api-reference/x/list-tweets) · [Trends](/api-reference/x/trends) · [Top tweets](/api-reference/x/top-tweets) · [Trend locations](/api-reference/x/trend-locations) · [Search Spaces](/api-reference/x/search-spaces) · [Get Space](/api-reference/x/get-space) · [Space replay](/api-reference/x/space-replay) · [Get broadcast](/api-reference/x/get-broadcast) · [User live status](/api-reference/x/user-live-status) · [Hashflags](/api-reference/x/hashflags) · [Search places](/api-reference/x/search-places) · [Download media](/api-reference/x/download-media)
  </Accordion>
</div>


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