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

# Get X trends

> Get trending topics on X by region with configurable count and 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
</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_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_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_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` when a workflow needs ranked regional topics for content
planning, monitor seeding, search jobs, or alert routing. The examples write
one JSON line per trend. Store `trend_name`, `rank`, `description`,
`search_query`, `region_woeid`, `returned_count`, and your own `detected_at`
timestamp, then pass
`search_query` to [Search Tweets](/api-reference/x/search-tweets) when a job
needs matching tweets.

## Query parameters

<ParamField query="woeid" type="integer">
  Positive Where On Earth ID for the region. Invalid or nonpositive values fall back to `1` (worldwide). See [Trends guide](/guides/trends) for common regions.
</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" required>
  Your API key. Session cookie authentication is also supported.
</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="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>
      </Expandable>
    </ResponseField>

    <ResponseField name="count" type="number">Number of trends returned.</ResponseField>
    <ResponseField name="woeid" type="number">WOEID used for the request.</ResponseField>

    ```json theme={null}
    {
      "trends": [
        {
          "name": "#AI",
          "rank": 1,
          "description": "Trending in Technology",
          "query": "%23AI"
        }
      ],
      "count": 1,
      "woeid": 23424977
    }
    ```
  </Tab>

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

    Missing or invalid API key.
  </Tab>

  <Tab title="402 Subscription required">
    ```json theme={null}
    { "error": "no_subscription" }
    ```

    No active subscription or insufficient credits. Possible error values: `no_subscription`, `subscription_inactive`, `no_credits`, `insufficient_credits`.
    For [MPP](/mpp/overview) requests without a valid payment credential, 402 returns a `WWW-Authenticate: Payment` challenge header instead.
  </Tab>

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

    The read service returned an error. Retry after a short delay.
  </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>

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