> ## 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 for WOEID topics & hashtags

> Use the Twitter Trends API to get ranked topics and hashtags by WOEID. Return search queries, ranks, public post counts, URLs, and regional result totals.

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

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

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

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

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

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

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

    <Tab title="503" id="response-trends-list-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>

## Use the top-level Twitter trends API

`GET /trends` is Xquik's top-level alias for ranked WOEID topics.
It returns `total`. `/x/trends` returns `count` instead.
Keep one response shape throughout each client.

<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 "https://xquik.com/api/v1/trends?woeid=23424977&count=10" \
    -H "x-api-key: xq_your_api_key_here" | jq
  ```

  ```javascript Node.js theme={null}
  const regionWoeid = "23424977";
  const requestedCount = "10";
  const params = new URLSearchParams({ woeid: regionWoeid, count: requestedCount });
  const response = await fetch(`https://xquik.com/api/v1/trends?${params}`, {
    headers: { "x-api-key": "xq_your_api_key_here" },
  });
  const data = await response.json();
  const returnedTotal = data.trends.length;
  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,
    requested_count: Number(requestedCount),
    returned_total: returnedTotal,
  }));

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

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

  region_woeid = 23424977
  requested_count = 10
  response = requests.get(
      "https://xquik.com/api/v1/trends",
      params={"woeid": region_woeid, "count": requested_count},
      headers={"x-api-key": "xq_your_api_key_here"},
  )
  data = response.json()
  returned_total = len(data["trends"])
  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"],
          "requested_count": requested_count,
          "returned_total": returned_total,
      }
      for trend in data["trends"]
  ]
  for row in trend_rows:
      print(json.dumps(row))
  ```

  ```go Go theme={null}
  package main

  import (
    "encoding/json"
    "log"
    "net/http"
    "os"
  )

  type Trend struct {
    Name        string  `json:"name"`
    Rank        *int    `json:"rank,omitempty"`
    Description *string `json:"description,omitempty"`
    Query       *string `json:"query,omitempty"`
  }

  type TrendsResponse struct {
    Trends []Trend `json:"trends"`
    Total  int     `json:"total"`
    Woeid  int     `json:"woeid"`
  }

  type TrendRow struct {
    TrendName      string  `json:"trend_name"`
    Rank           *int    `json:"rank"`
    Description    *string `json:"description"`
    SearchQuery    string  `json:"search_query"`
    RegionWoeid    int     `json:"region_woeid"`
    RequestedCount int     `json:"requested_count"`
    ReturnedTotal  int     `json:"returned_total"`
  }

  func main() {
    const requestedCount = 10
    req, err := http.NewRequest("GET", "https://xquik.com/api/v1/trends?woeid=23424977&count=10", nil)
    if err != nil {
      log.Fatal(err)
    }
    req.Header.Set("x-api-key", "xq_your_api_key_here")

    resp, err := http.DefaultClient.Do(req)
    if err != nil {
      log.Fatal(err)
    }
    defer resp.Body.Close()

    var data TrendsResponse
    if err := json.NewDecoder(resp.Body).Decode(&data); err != nil {
      log.Fatal(err)
    }

    returnedTotal := len(data.Trends)
    encoder := json.NewEncoder(os.Stdout)
    for _, trend := range data.Trends {
      searchQuery := trend.Name
      if trend.Query != nil {
        searchQuery = *trend.Query
      }
      if err := encoder.Encode(TrendRow{
        TrendName:      trend.Name,
        Rank:           trend.Rank,
        Description:    trend.Description,
        SearchQuery:    searchQuery,
        RegionWoeid:    data.Woeid,
        RequestedCount: requestedCount,
        ReturnedTotal:  returnedTotal,
      }); err != nil {
        log.Fatal(err)
      }
    }
  }
  ```
</CodeGroup>

## Build a regional Twitter trending monitor

Use `GET /trends` for regional dashboards, alerts, queues, warehouses, or agents.
The examples emit one JSON line per trend.
Store `trend_name`, `rank`, `description`, and `search_query`.
Record `region_woeid` and `requested_count` with each snapshot.
Record `returned_total` beside those request fields.

Map `name` and `query` to the 2 trend text fields.
Map `woeid` and request `count` to the 2 request fields.
Derive `returned_total` from `trends.length`.
The raw `total` counts valid trends before `count` slicing.

Pass `search_query` to [Search Tweets](/api-reference/x/search-tweets).
That search finds related tweets, hashtags, or brand mentions.
Save each snapshot before you search.
Compare ranks only within one WOEID.
Keep missing optional fields unset. Store null `tweetVolume` values as null.

## 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` authenticates `paid_reads` guest keys. Direct MPP uses the `Payment ...` credential. Get it from the `WWW-Authenticate: Payment` challenge.
</ParamField>

## Query parameters

<ParamField query="woeid" type="number">
  Region WOEID. See supported regions below. Omit it to use `1` for Worldwide.
</ParamField>

<ParamField query="count" type="number">
  Number of trends to return. Max `50`, default `30`.
</ParamField>

## Response

### 200 OK

<ResponseField name="trends" type="object[]">
  Ranked topic records.
  **Trend object fields.**

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

  <ResponseField name="description" type="string">
    Optional trend description.
  </ResponseField>

  <ResponseField name="rank" type="number">
    Optional ranking position.
  </ResponseField>

  <ResponseField name="query" type="string">
    Optional tweet-search query.
  </ResponseField>

  <ResponseField name="promotedContent" type="string | null">
    Optional promotion ID. Null for organic trends.
  </ResponseField>

  <ResponseField name="tweetVolume" type="number | null">
    Optional public post count.
  </ResponseField>

  <ResponseField name="url" type="string">
    Optional trend search URL.
  </ResponseField>
</ResponseField>

<ResponseField name="total" type="number">
  Valid trend count before `count` slicing.
</ResponseField>

<ResponseField name="woeid" type="number">
  Requested region WOEID.
</ResponseField>

```json theme={null}
{
  "trends": [
    {
      "name": "#SuperBowl",
      "description": "Trending in United States",
      "rank": 1,
      "query": "%23SuperBowl",
      "promotedContent": null,
      "tweetVolume": 250000,
      "url": "https://x.com/search?q=%23SuperBowl"
    },
    {
      "name": "Taylor Swift",
      "rank": 2,
      "query": "%22Taylor%20Swift%22"
    }
  ],
  "total": 50,
  "woeid": 1
}
```

### 400 Invalid input

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

Use a supported WOEID. Invalid `count` values fall back to `30`.

### 401 Unauthenticated

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

Replace the missing or invalid API key.

### 402 Payment required

Account keys get account options. Guest keys get a top-up option.
Anonymous direct MPP shows 2 payment choices.
Choose either the payment challenge or the guest wallet action.
No checkout starts automatically.

### 502 X API unavailable

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

The read service failed. 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 }
```

Wait for `Retry-After` before retrying.

### 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 /trends` with a WOEID and result count.
Read each returned topic field described above.

### Can I get location-based trending topics?

Yes. Use a listed WOEID and keep it with each rank snapshot.

### Does the API return historical Twitter trends?

No. Each call returns one regional snapshot.
Save timestamped snapshots on your own schedule.

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

Send an account key, OAuth token, guest key, or direct MPP credential.

### Is the Twitter trends API free?

No. The pricing callout shows each successful call's cost.

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

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

## Regions

Use these WOEIDs in the `woeid` query parameter. Use `1` for Worldwide.

<CardGroup cols={3}>
  <Card title="Global & Americas" icon="globe">
    * `1` - Worldwide
    * `23424977` - United States
    * `23424775` - Canada
    * `23424900` - Mexico
    * `23424768` - Brazil
  </Card>

  <Card title="Europe" icon="map-pin">
    * `23424975` - United Kingdom
    * `23424969` - Turkey
    * `23424950` - Spain
    * `23424829` - Germany
    * `23424819` - France
  </Card>

  <Card title="Asia" icon="building-2">
    * `23424856` - Japan
    * `23424848` - India
  </Card>
</CardGroup>

<Note>
  **Related.** [Billing & Usage](/guides/billing) · [Search Tweets](/api-reference/x/search-tweets)
</Note>


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