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

# List trends

> Get ranked X trends by region with WOEID filtering

<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/overview): 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 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: data.total,
  }));

  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()
  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": data["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)
    }

    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:  data.Total,
      }); err != nil {
        log.Fatal(err)
      }
    }
  }
  ```
</CodeGroup>

## Direct trends handoff

Use `GET /trends` when a dashboard, alerting job, content queue, warehouse, or
agent needs ranked X topics for a supported WOEID region.

The Node.js, Python, and Go examples shape one JSON line per trend. Store
`trend_name`, `rank`, `description`, `search_query`, `region_woeid`,
`requested_count`, and `returned_total`. Pass `search_query` to
[Search Tweets](/api-reference/x/search-tweets) when the next step needs
matching tweets.

`total` is the number of valid trends available before `count` slicing. Use it
to detect whether a smaller `count` hid extra rows.

## 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. Default: `1` (Worldwide).
</ParamField>

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

## Response

<Tabs>
  <Tab title="200 OK">
    <ResponseField name="trends" type="object[]">
      Array of trending topics.

      <Expandable title="trend object">
        <ResponseField name="name" type="string">Trend name or hashtag.</ResponseField>
        <ResponseField name="description" type="string">Short description. Omitted if unavailable.</ResponseField>
        <ResponseField name="rank" type="number">Position in the trending list. Omitted if unavailable.</ResponseField>
        <ResponseField name="query" type="string">Search query for this trend. Omitted if unavailable.</ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="total" type="number">
      Full count of available trends before slicing by `count`.
    </ResponseField>

    <ResponseField name="woeid" type="number">
      Region WOEID used for this request.
    </ResponseField>

    ```json theme={null}
    {
      "trends": [
        {
          "name": "#SuperBowl",
          "description": "Trending in United States",
          "rank": 1,
          "query": "%23SuperBowl"
        },
        {
          "name": "Taylor Swift",
          "rank": 2,
          "query": "%22Taylor%20Swift%22"
        }
      ],
      "total": 50,
      "woeid": 1
    }
    ```
  </Tab>

  <Tab title="400 Invalid Input">
    ```json theme={null}
    { "error": "invalid_input" }
    ```

    Unsupported or malformed `woeid`. Use one of the WOEIDs in the regions table. `count` is clamped between 1 and 50; nonnumeric values fall back to 30.
  </Tab>

  <Tab title="401 Unauthenticated">
    ```json theme={null}
    { "error": "unauthenticated" }
    ```

    Missing or invalid API key. Check the `x-api-key` header value.
  </Tab>

  <Tab title="402 Payment required">
    Account keys get account options; guest keys get guest top-up only.
    Anonymous calls receive a direct MPP `WWW-Authenticate: Payment` challenge plus a guest wallet creation action.
    No checkout starts automatically. Confirm any payment action.
  </Tab>

  <Tab title="502 X API Unavailable">
    ```json theme={null}
    { "error": "x_api_unavailable" }
    ```

    The read service is temporarily unavailable. Retry with exponential backoff.
  </Tab>

  <Tab title="429 Rate Limit Exceeded">
    ```json theme={null}
    { "error": "rate_limit_exceeded", "retryAfter": 60 }
    ```

    Your tier rate limit was exceeded. Wait for the `Retry-After` header before retrying.
  </Tab>

  <Tab title="424 Dependency Failed">
    ```json theme={null}
    { "error": "x_api_unavailable" }
    ```

    The normalized v1 response contract can return 424 when the read service is unavailable.
  </Tab>
</Tabs>

## Regions

Use these WOEIDs in the `woeid` query parameter. Omit `woeid` or pass `1` for
worldwide trends.

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