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

# Trends history by date, X (Twitter) API docs

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

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

`GET https://xquik.com/api/v1/x/trends/history`

**1 credit per list returned** · [All plans](https://xquik.com) from \$0.00012/credit

```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 -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={"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 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={"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 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))
```

Use `GET /x/trends/history` to read the Twitter trends archive of a place.
It answers what was trending on Twitter yesterday or last week. It covers any day since 2026-10-13.
Xquik stores 1 list per place every 5 minutes. It 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`.
`from` and `to` take a time or span back from now, such as `7d`. A schedule can then read the last day on every run.
The answer names the range it read in `fromTime` and `toTime`.
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](https://docs.xquik.com/api-reference/x/trends.md) instead.

## Query parameters

| Query parameter | Type | Required | Description |
| - | - | - | - |
| `woeid` | `integer` | No | 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](https://docs.xquik.com/api-reference/x/trend-locations.md) returns every place. |
| `country` | `string` | No | Country to read trends history for, by name or 2-letter code. Examples are `Turkey` and `TR`. Case insensitive. |
| `location` | `string` | No | Town or country to read trends history for, by name, such as `Istanbul`. Case insensitive. Add `country` when 2 towns share a name. |
| `from` | `string` | No | 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. It also takes a span back from now. A span is a number and `s`, `m`, `h`, or `d`. For example, `from=7d` reads the last 7 days. Defaults to 24 hours before `to`. History starts 2026-10-13 02:20 UTC. A range that begins earlier returns the stored part. Alias `sinceTime`. |
| `to` | `string` | No | End of the range, which it leaves out. Takes the forms of `from`. For example, `from=2d` with `to=1d` reads the day before the last 24 hours. Defaults to now. Alias `untilTime`. |
| `every` | `string` | No | Step between 2 returned lists, as a number and `m`, `h`, or `d`. Examples are `15m`, `1h`, and `1d`. Default `1h`. A step under `5m` returns every stored list. |
| `count` | `integer` | No | Number of trends in each list. Default `30`, max `50`. Invalid or below-minimum values fall back to `30`. |
| `limit` | `integer` | No | Maximum lists 1 request returns and charges. Default `24`, max `100`. Your credit balance can return fewer. |
| `cursor` | `string` | No | The `next_cursor` of the page before, for the next lists. It keeps the time of the first request. That way, a range of spans stays the same on every 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 | Send a full Xquik account API key. |
| `Authorization` | `string` | No | `Bearer xq_your_guest_key_here` for `paid_reads`. |

## Response

### 200 OK

| Field | Type | Description |
| - | - | - |
| `snapshots` | `object[]` | 1 stored list per step, oldest first. A step with no stored list is left out. |
| `snapshots[].capturedAt` | `string` | When Xquik read this list from X, as ISO 8601 in UTC. It comes from the stored list and is never estimated. |
| `snapshots[].count` | `number` | Trends in this list. |
| `snapshots[].trends` | `object[]` | The trends of the list, with the fields of [Get X trends](https://docs.xquik.com/api-reference/x/trends.md). `rank` is the trend's place in X's list at that time. |
| `count` | `number` | Lists returned and charged. |
| `fromTime` | `string` | Start of the range as Xquik read it, as ISO 8601 in UTC. A span such as `7d` shows here as the time it counted back to. |
| `toTime` | `string` | End of the range as Xquik read it, which the range leaves out. Without `to`, it is the time of the first request. |
| `woeid` | `number` | WOEID used for the request. |
| `location` | `object` | The place `country` or `location` named, with the fields of a [trend location](https://docs.xquik.com/api-reference/x/trend-locations.md). Absent when `woeid` picked the place or the request named none. |
| `has_next_page` | `boolean` | Whether the range holds more lists. |
| `next_cursor` | `string` | Send it as `cursor` for the next lists. Empty on the last page. |

```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"]}}
{
  "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,
  "fromTime": "2026-10-13T00:00:00.000Z",
  "toTime": "2026-10-14T00:00:00.000Z",
  "woeid": 1,
  "has_next_page": false,
  "next_cursor": ""
}
```

### 400 Invalid input

An unknown place returns 400. So does a `from` that is not earlier than `to`.
A time, step or `cursor` Xquik cannot read also returns 400. So does a value past its length limit.
The request costs nothing.

### 404 No stored list

The range ends before the place's first stored list. The message names when its archive starts. X serves no older lists.
The request costs nothing.

### 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. Wait for `Retry-After`, then retry.

### 429 Rate limit exceeded

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

### 424 Dependency failed

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. Add `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 404 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](https://docs.xquik.com/api-reference/x/trends.md) reads the current trends of a place. With `at`, it reads 1 past moment.

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

* **400** `{ "error": "invalid_input", "message": "X lists no trends for that place. List places with GET /x/trends/locations." }`
* **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": "Xquik stores no trends for this place before 2026-10-13 02:20 UTC. X serves no older lists, so ask for that time or later." }`
* **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.