# X Trends

> X API v2 trends source (PRD §4.1, §6.8). Calls GET /2/trends/by/woeid (default WOEID 1 = worldwide) with Bearer auth from X_API_KEY. Skips gracefully when the key is absent. Capped at 20 trends per run; hashtag-only entries are filtered out.

- Skill: `guillaumemeyer/x-trends` (Agent Skill)
- Install (CLI): `npx skillmds@latest add guillaumemeyer/x-trends`
- Raw SKILL.md: https://api.skillmd.com/api/skills/guillaumemeyer/x-trends/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Product & Planning
- Author: guillaumemeyer (https://skillmd.com/u/guillaumemeyer)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/guillaumemeyer/x-trends

---


# X Trends (X API v2)

## How to run

1. If `X_API_KEY` is missing → `{ok: false, skipped: true, error:
   "X_API_KEY not configured"}` — the detection stage records the gap.
2. `GET https://api.x.com/2/trends/by/woeid/{woeid}?expansions=geo` with
   `Authorization: Bearer $X_API_KEY`, 15s timeout.
3. Take `data[0].trends`, drop entries whose name starts with `#`, cap at 20.

## Signal shape (zod `SignalSchema`)

```text
source: "x_trends"
source_ref: stable dedup key from source+title
title: trend name
volume: tweet_volume (if present)
detected_at: now (ISO)
```

Non-200 → `{ok: false, error}`; do not retry more than once.