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

# Twitter trends archive API & trends history by date

> Read the Twitter trends archive of any place. Get past X trends by date and time, 1 stored list per step, from 2026-10-13 on. 1 credit per list returned.

<Panel>
  <Tabs defaultTabIndex={0} sync={false}>
    <Tab title="200" id="response-x-trends-history-200">
      ```json theme={null}
      {
        "snapshots": [
          {
            "capturedAt": "2026-10-13T14:00:26.000Z",
            "count": 1,
            "trends": [
              {
                "name": "#AI",
                "description": "Artificial intelligence discussions",
                "promotedContent": null,
                "query": "%23AI",
                "rank": 1
              }
            ]
          }
        ],
        "count": 1,
        "woeid": 1,
        "has_next_page": false,
        "next_cursor": ""
      }
      ```
    </Tab>

    <Tab title="400" id="response-x-trends-history-400">
      ```json theme={null}
      {
        "error": "invalid_input",
        "message": "Trends history for this place starts 2026-10-13 02:20 UTC. Ask for a later time."
      }
      ```
    </Tab>

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

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

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

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

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

    <Tab title="503" id="response-x-trends-history-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 list returned** · [All plans](https://xquik.com/#pricing) from \$0.00012/credit
</Callout>

<CodeGroup>
  ```bash cURL theme={null}
  curl -G https://xquik.com/api/v1/x/trends/history \
    --data-urlencode "country=TR" \
    --data-urlencode "from=2026-10-13" \
    --data-urlencode "to=2026-10-14" \
    --data-urlencode "every=1h" \
    -H "x-api-key: xq_your_api_key_here" | jq
  ```

  ```javascript Node.js theme={null}
  const params = new URLSearchParams({
    country: "TR",
    from: "2026-10-13",
    to: "2026-10-14",
    every: "1h",
  });
  const response = await fetch(`https://xquik.com/api/v1/x/trends/history?${params}`, {
    headers: { "x-api-key": "xq_your_api_key_here" },
  });
  const data = await response.json();
  const trendRows = data.snapshots.flatMap((snapshot) =>
    snapshot.trends.map((trend) => ({
      captured_at: snapshot.capturedAt,
      region_woeid: data.woeid,
      rank: trend.rank,
      trend_name: trend.name,
      tweet_volume: trend.tweetVolume ?? null,
    })),
  );

  for (const row of trendRows) {
    process.stdout.write(`${JSON.stringify(row)}\n`);
  }
  ```

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

  response = requests.get(
      "https://xquik.com/api/v1/x/trends/history",
      params={"country": "TR", "from": "2026-10-13", "to": "2026-10-14", "every": "1h"},
      headers={"x-api-key": "xq_your_api_key_here"},
  )
  data = response.json()
  trend_rows = [
      {
          "captured_at": snapshot["capturedAt"],
          "region_woeid": data["woeid"],
          "rank": trend["rank"],
          "trend_name": trend["name"],
          "tweet_volume": trend.get("tweetVolume"),
      }
      for snapshot in data["snapshots"]
      for trend in snapshot["trends"]
  ]
  for row in trend_rows:
      print(json.dumps(row))
  ```
</CodeGroup>

Use `GET /x/trends/history` to read the Twitter trends archive of a place.
It answers what was trending on Twitter yesterday, last week, or on any day since 2026-10-13.
Xquik stores 1 list per place every 5 minutes and keeps each list for 25 months.
The archive starts 2026-10-13 02:20 UTC. Earlier trends are not available.
Each returned list costs 1 credit, so 24 lists cost 24 credits.
A step with no stored list returns nothing and costs nothing.

## Read Twitter trends history by date

Pick the place by `country`, `location`, or `woeid`. Without one, trends are worldwide.
Set the range with `from` and `to`, and the step with `every`.
Each step returns the first list Xquik stored in it, oldest first.
Every list carries `capturedAt`, the time Xquik read it from X. Xquik never estimates that time.

A request returns 24 lists, or up to 100 with `limit`.
A wider range answers `has_next_page` as `true`. Send `next_cursor` as `cursor` for the next lists.
For 1 past moment, send `at` to [Get X trends](/api-reference/x/trends) instead.

## Query parameters

<ParamField query="woeid" type="integer">
  Positive Where On Earth ID for the region. It wins over `country` and `location`. Invalid or nonpositive values fall back to those names, then to `1` (worldwide). [List trend locations](/api-reference/x/trend-locations) returns every place.
</ParamField>

<ParamField query="country" type="string">
  Country to read trends history for, by name or 2-letter code, such as `Turkey` or `TR`. Case insensitive.
</ParamField>

<ParamField query="location" type="string">
  Town or country to read trends history for, by name, such as `Istanbul`. Case insensitive. Add `country` when 2 towns share a name.
</ParamField>

<ParamField query="from" type="string">
  Start of the range. Takes an ISO 8601 time, a date such as `2026-10-13`, or Unix seconds. A time without a zone reads as UTC. Defaults to 24 hours before `to`. History starts 2026-10-13 02:20 UTC, and a range that begins earlier returns the stored part. Alias `sinceTime`.
</ParamField>

<ParamField query="to" type="string">
  End of the range, which it leaves out. Takes the forms of `from`. Defaults to now. Alias `untilTime`.
</ParamField>

<ParamField query="every" type="string">
  Step between 2 returned lists, as a number and `m`, `h`, or `d`, such as `15m`, `1h`, or `1d`. Default `1h`. A step under `5m` returns every stored list.
</ParamField>

<ParamField query="count" type="integer">
  Number of trends in each list. Default `30`, max `50`. Invalid or below-minimum values fall back to `30`.
</ParamField>

<ParamField query="limit" type="integer">
  Maximum lists 1 request returns and charges. Default `24`, max `100`. Your credit balance can return fewer.
</ParamField>

<ParamField query="cursor" type="string">
  The `next_cursor` of the page before, for the next lists.
</ParamField>

### Choose fields

<ParamField query="fields" type="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.
</ParamField>

<ParamField query="omit" type="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.
</ParamField>

## Headers

<ParamField header="x-api-key" type="string">
  Send a full Xquik account API key.
</ParamField>

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

## Response

### 200 OK

<ResponseField name="snapshots" type="object[]">
  1 stored list per step, oldest first. A step with no stored list is left out.
  **Snapshot object fields.**

  <ResponseField name="capturedAt" type="string">
    When Xquik read this list from X, as ISO 8601 in UTC. It comes from the stored list and is never
    estimated.
  </ResponseField>

  <ResponseField name="count" type="number">
    Trends in this list.
  </ResponseField>

  <ResponseField name="trends" type="object[]">
    The trends of the list, with the fields of [Get X trends](/api-reference/x/trends). `rank` is the
    trend's place in X's list at that time.
  </ResponseField>
</ResponseField>

<ResponseField name="count" type="number">Lists returned and charged.</ResponseField>
<ResponseField name="woeid" type="number">WOEID used for the request.</ResponseField>

<ResponseField name="location" type="object">
  The place `country` or `location` named, with the fields of a [trend location](/api-reference/x/trend-locations). Absent when `woeid` picked the place or the request named none.
</ResponseField>

<ResponseField name="has_next_page" type="boolean">Whether the range holds more lists.</ResponseField>

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

```json theme={null}
{
  "snapshots": [
    {
      "capturedAt": "2026-10-13T14:00:26.000Z",
      "count": 1,
      "trends": [
        {
          "name": "#AI",
          "rank": 1,
          "description": "Trending in Technology",
          "query": "%23AI",
          "promotedContent": null,
          "tweetVolume": 250000,
          "url": "https://x.com/search?q=%23AI"
        }
      ]
    }
  ],
  "count": 1,
  "woeid": 1,
  "has_next_page": false,
  "next_cursor": ""
}
```

### 400 Invalid input

```json theme={null}
{
  "error": "invalid_input",
  "message": "Trends history for this place starts 2026-10-13 02:20 UTC. Ask for a later time."
}
```

The range ends before the place's first stored list. The message names that first time.
An unknown place, a time or step Xquik cannot read, and a `from` after `to` also return 400.
The request costs nothing.

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

### 503 Service busy

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

Xquik is busy. Wait for `Retry-After`, then retry.

### 429 Rate limit exceeded

```json theme={null}
{ "error": "rate_limit_exceeded", "retryAfter": 60 }
```

The Xquik tier limit blocked the request.
Use `Retry-After` when present. Otherwise, use the JSON `retryAfter` field.

### 424 Dependency failed

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

The opt-in normalized contract returns 424 when the read service fails.
Send `xquik-api-contract: 2026-04-29` to opt in. Default v1 returns 502.

## Twitter trends archive API questions

### How do I see what was trending on Twitter yesterday?

Call `GET /x/trends/history` with yesterday's date as `from` and today's date as `to`.
Add `every=1h` for 1 list per hour, or `every=1d` for the first list of the day.

### How far back does the Twitter trends archive go?

It starts 2026-10-13 02:20 UTC. Xquik keeps each list for 25 months.
A range that ends before the start returns 400 and costs nothing.

### How often does Xquik store a list?

Every 5 minutes, for every place X offers trends for.
A step under `5m` returns every stored list.

### How much does trends history cost?

Each returned list costs 1 credit, so 24 lists cost 24 credits.
A step with no stored list costs nothing. A request returns 100 lists at most.

### What if no list matches a step?

The response leaves that step out. Xquik never fills a gap with a made-up list.
Each returned list states its own `capturedAt`.

### Does this replace X's official API?

No. This page documents Xquik, an independent third-party service.
It does not document X's official API.

<Note>
  **Next steps.** [Get X trends](/api-reference/x/trends) reads the current trends of a place, or 1 past moment with `at`.
</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) · [Trends history](/api-reference/x/trends-history) · [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) · [Notes contributor](/api-reference/x/community-notes-contributor) · [Contributor notes](/api-reference/x/community-notes-contributor-notes) · [Deleted notes](/api-reference/x/community-notes-contributor-deleted-notes) · [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.