X API - APIs | Desearch Docs

The X API returns posts and related metadata from X/Twitter: keyword search, a user's posts, replies, retweeters, and trends.

Search posts

text

GET https://api.desearch.ai/twitter

bash

curl --request GET 'https://api.desearch.ai/twitter?query=Bittensor&sort=Top&count=20' \
  --header "Authorization: $DESEARCH_API_KEY"

The query string supports X's full operator syntax: from:, to:, since:, min_faves:, exact phrases, and boolean logic. The complete list is in X query syntax.

Everything else on X

Endpoint	Returns
`GET /twitter/post`	A single post by ID.
`GET /twitter/user/posts`	A user's recent posts.
`GET /twitter/replies` · `/twitter/replies/post`	Replies, by user or by post.
`GET /twitter/post/retweeters`	Who retweeted a post.
`GET /twitter/urls`	Posts linking to a URL.

For semantic search over posts with AI ranking, use the Search API with "tools": ["twitter"] instead. It answers a prompt, while these endpoints match queries exactly.

Parameters and response schemas are in the API Reference.

Trends

GET /twitter/trends returns current X trends for a location (woeid).

Required query param: woeid (Where On Earth ID). Example: 23424977 = United States.
Optional: count (how many trends to return). Minimum 30, maximum 100. Values below 30 fail validation (422). Missing auth or an invalid API key returns 401. Some malformed or unrecognized Authorization values, such as an unreplaced placeholder, can return 403 instead (see Auth and API keys). An unsupported woeid returns 422 with {"detail":"WOEID is not supported"}.

Base URL: https://api.desearch.ai
Auth: Authorization: $DESEARCH_API_KEY (raw key in examples).

bash

curl --request GET \
  'https://api.desearch.ai/twitter/trends?woeid=23424977&count=30' \
  --header "Authorization: $DESEARCH_API_KEY"

Truncated successful body (live shape; list length matches count):

json

{
  "trends": [
    { "name": "#ExampleTrend", "query": "#ExampleTrend", "rank": 1 },
    { "name": "Example Name", "query": "\"Example Name\"", "rank": 2 },
    { "name": "Another", "query": "Another", "rank": 3 }
  ],
  "woeid": { "name": "United States", "id": 23424977 }
}

Each trend item has name, query (search string), and rank. Successful billable responses also carry billing metadata via X-Desearch-* response headers (and matching optional body fields). Do not hard-code dollar rates here; see Pricing and Billing.

Search posts for a trend

Pass a trend's query to GET /twitter to get posts for it. Also set start_date (UTC, YYYY-MM-DD), for example yesterday's date:

bash

curl --get 'https://api.desearch.ai/twitter' \
  --data-urlencode 'query=#ExampleTrend' \
  --data-urlencode 'sort=Top' \
  --data-urlencode 'start_date=2026-10-03' \
  --data-urlencode 'count=20' \
  --header "Authorization: $DESEARCH_API_KEY"

sort=Top (the default) is a ranking, not a recency order, and does not limit post age. Without start_date, an older post that used the same tag can come first: in a 2026-10-04 test, the top result for the trend #strictly was a post from 2024-10-12. Use start_date (and end_date if needed) to bound the date range, or sort=Latest for the newest posts first. Check each post's created_at if your app needs a stricter time window.

For a natural-language answer that may cite X posts, use AI Search with tools including "twitter". For TikTok trending posts, use Social APIs GET /desearch/tiktok/trending, not this endpoint.

Which surface should I use?

Goal	Use
X trends by location	REST `GET /twitter/trends` or MCP `x-trends`
X keyword / post / user / replies	Other `GET /twitter…` routes on the X guide
NL answer that may include X	AI Search `tools: ["twitter"]`
TikTok trending posts	`GET /desearch/tiktok/trending` (Social hub)

Who this is for

Humans

Copy the curl, set woeid for your market, keep count ≥ 30, then open API Reference for the full schema.

Agents / tool authors

Prefer MCP x-trends when the host already exposes it. Always send woeid. If you set count, use 30–100 only. When you then search a trend's query with GET /twitter, set a UTC start_date: sort=Top is ranking, not recency.