> ## 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 API by region, WOEID & search

> Get Twitter and X trends for a country, town, or WOEID. Return ranked topics, hashtags, search queries, descriptions, and tweet volume. 3 credits per call.

<Panel>
  <Tabs defaultTabIndex={0} sync={false}>
    <Tab title="200" id="response-x-trends-200">
      ```json theme={null}
      {
        "trends": [
          {
            "name": "#AI",
            "description": "Artificial intelligence discussions",
            "promotedContent": null,
            "query": "%23AI",
            "rank": 1
          }
        ],
        "count": 30,
        "woeid": 1
      }
      ```
    </Tab>

    <Tab title="400" id="response-x-trends-400">
      ```json theme={null}
      {
        "error": "invalid_input",
        "message": "X lists no trends for that place. List places with GET /x/trends/locations."
      }
      ```
    </Tab>

    <Tab title="401" id="response-x-trends-401">
      ```json theme={null}
      {
        "error": "unauthenticated",
        "message": "Authentication required. Provide a valid API key or bearer token."
      }
      ```
    </Tab>

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

    <Tab title="424" id="response-x-trends-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-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-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-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">
  **3 credits per call** · [All plans](https://xquik.com/#pricing) from \$0.00012/credit · Direct [MPP](/mpp/machine-payments-protocol): USD 0.00045 per call
</Callout>

<CodeGroup>
  ```bash cURL theme={null}
  curl -G https://xquik.com/api/v1/x/trends \
    --data-urlencode "woeid=23424977" \
    --data-urlencode "count=10" \
    -H "x-api-key: xq_your_api_key_here" | jq
  ```

  ```javascript Node.js theme={null}
  const params = new URLSearchParams({ woeid: "23424977", count: "10" });
  const response = await fetch(`https://xquik.com/api/v1/x/trends?${params}`, {
    headers: { "x-api-key": "xq_your_api_key_here" },
  });
  const data = await response.json();
  const detectedAt = new Date().toISOString();
  const trendRows = data.trends.map((trend) => ({
    trend_name: trend.name,
    rank: trend.rank ?? null,
    description: trend.description ?? null,
    search_query: trend.query ?? trend.name,
    region_woeid: data.woeid,
    returned_count: data.count,
    detected_at: detectedAt,
  }));

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

  ```python Python theme={null}
  from datetime import datetime, timezone
  import json
  import requests

  response = requests.get(
      "https://xquik.com/api/v1/x/trends",
      params={"woeid": 23424977, "count": 10},
      headers={"x-api-key": "xq_your_api_key_here"},
  )
  data = response.json()
  detected_at = datetime.now(timezone.utc).isoformat().replace("+00:00", "Z")
  trend_rows = [
      {
          "trend_name": trend["name"],
          "rank": trend.get("rank"),
          "description": trend.get("description"),
          "search_query": trend.get("query", trend["name"]),
          "region_woeid": data["woeid"],
          "returned_count": data["count"],
          "detected_at": detected_at,
      }
      for trend in data["trends"]
  ]
  for row in trend_rows:
      print(json.dumps(row))
  ```
</CodeGroup>

Use `GET /x/trends` to retrieve X's ranked trends for a place you choose.
Pick the place by `country`, `location`, or `woeid`. Without one, trends are worldwide.
Use trends for planning, monitor setup, search jobs, and alerts.
Each example emits one JSON record for every returned trend.
Store `trend_name` for every result.
Keep `rank`, `description`, and `query` when the response includes them.
Leave omitted fields unset. Use the trend name when `query` is missing.
Also store `region_woeid`, `returned_count`, and your own `detected_at` timestamp.
Pass `search_query` to [Search Tweets](/api-reference/x/search-tweets) for matching tweets.
Save each snapshot before you search.

## Build a regional trend monitor

Poll one WOEID on a consistent schedule.
Store every trend name and returned optional field.
Keep missing values unset. Keep `tweetVolume` as null when X returns null.

Compare ranks within the same region. Do not mix worldwide and country results
inside one ranking. Keep the WOEID on every row.

Use the returned search query to retrieve matching tweets. Keep the trend
snapshot before starting that search. Each tweet batch then links to the
regional topic that started it.

Missing tweet volume means unknown. Do not convert it to 0. X may omit
that field for some trends.

## 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). See [Trends guide](/guides/trends) for common regions, or [List trend locations](/api-reference/x/trend-locations) for every place.
</ParamField>

<ParamField query="country" type="string">
  Country to read trends 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 for, by name, such as `Istanbul`. Case insensitive. Add `country` when 2 towns share a name. [List trend locations](/api-reference/x/trend-locations) returns every name.
</ParamField>

<ParamField query="count" type="integer">
  Number of trends to return. Default `30`, max `50`. Invalid or below-minimum values fall back to `30`.
</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` authenticates `paid_reads` guest keys through the API-key scheme's Bearer alias. Direct MPP uses the `Payment ...` credential from the `WWW-Authenticate: Payment` challenge.
</ParamField>

## Response

### 200 OK

<ResponseField name="trends" type="object[]">
  Array of trending topics.
  **Trend object fields.**

  <ResponseField name="name" type="string">
    Trend name or hashtag.
  </ResponseField>

  <ResponseField name="rank" type="number">
    Trend rank. Omitted if unavailable.
  </ResponseField>

  <ResponseField name="description" type="string">
    Trend description. Omitted if unavailable.
  </ResponseField>

  <ResponseField name="query" type="string">
    Search query for this trend. Omitted if unavailable.
  </ResponseField>

  <ResponseField name="promotedContent" type="string | null">
    Promotion identifier. Null for organic trends.
  </ResponseField>

  <ResponseField name="tweetVolume" type="number | null">
    Approximate public post volume when X supplies it.
  </ResponseField>

  <ResponseField name="url" type="string">
    X search URL for the trend.
  </ResponseField>
</ResponseField>

<ResponseField name="count" type="number">Number of trends returned.</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>

```json theme={null}
{
  "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": 23424977
}
```

A request with `location=Istanbul` also names the place it read:

```json theme={null}
{
  "trends": [],
  "count": 0,
  "woeid": 2344116,
  "location": {
    "woeid": 2344116,
    "name": "Istanbul",
    "country": "Turkey",
    "countryCode": "TR",
    "placeType": "Town",
    "placeTypeCode": 7,
    "parentWoeid": 23424969,
    "url": "http://where.yahooapis.com/v1/place/2344116"
  }
}
```

### 400 Unknown place

```json theme={null}
{
  "error": "invalid_input",
  "message": "X lists no trends for that place. List places with GET /x/trends/locations."
}
```

X lists no trends for that `country` or `location`. The request costs nothing.

### 401 Unauthenticated

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

Missing or invalid API key.

### 402 Payment required

Account keys receive account payment options.
Guest keys receive only the guest top-up action.
Anonymous calls receive `WWW-Authenticate: Payment` plus a guest wallet action.
Failed requests never create checkout. Confirm a payment option first.

### 502 X API unavailable

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

The read service returned an error. Retry after a short delay.

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

### How do I get Twitter trends programmatically?

Call `GET /x/trends` with a `country`, a `location`, or a `woeid`, and a result `count`.
Read each trend's name, rank, query, description, and available tweet volume.

### Can I get Twitter trends by country or city name?

Yes. Send `country=TR` or `location=Istanbul`. Names ignore case.
The response returns the place it read as `location`.

### Can I track trending hashtags by region?

Yes. Poll the same WOEID on a stable schedule.
Compare ranks within the same region. Save each detection time.
Use `query` to search tweets related to each trending hashtag.
Use the trend name when the response omits `query`.

### How do I authenticate to the Twitter trends API?

Send an Xquik API key or OAuth bearer token.
A `paid_reads` guest key can use the API-key scheme's Bearer alias.
For direct MPP, anonymous requests get a payment challenge.

### How much does a trends request cost?

The pricing callout above shows the current credit and direct MPP cost.
Failed requests return a documented error without creating checkout.

### How do I build trend tracking into an app?

Schedule one regional request, then store each returned snapshot.
Compare the latest ranks with the previous snapshot.
Send rank changes you care about to a dashboard, monitor, or alert queue.

### 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>
  This endpoint returns trends directly from X. For broader Radar topic discovery, use [List Radar Items](/api-reference/radar/list).
</Note>

<Note>
  **Next steps.** [Search Tweets](/api-reference/x/search-tweets) to find tweets about a trending topic.
</Note>

<div className="related-api-links">
  <Accordion title="Related tweet, reply & media APIs" icon="link">
    * Tweets: [Get tweet](/api-reference/x/get-tweet) · [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) · [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) · [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) · [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.