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. Product overview: Twitter search API.

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`	Replies by a user, returned as a single page (no cursor). A response can contain fewer replies than `count`.
`GET /twitter/replies/post`	A best-effort sample of replies to one post, returned as a single page (not the full thread, no cursor).
`GET /twitter/post/retweeters`	Who retweeted a post. The response includes `next_cursor`; pass it as the `cursor` query parameter on the next request to get more retweeters. Stop when a page returns no users.
`GET /twitter/urls`	Posts linking to a URL.

GET /twitter/replies/post returns a best-effort sample of replies to an X post. It is not the full reply thread.

Paging: This endpoint returns a single page. It does not return a cursor, a next-page token, or a way to request more replies.
Result count: count is the maximum number of replies to return. Accepted values: 1 to 100. A response often contains fewer replies than count and fewer than the reply count shown on the post. Calls for the same post can return a different number of replies and different replies.
Totals: The response does not include a total. To show how many replies a post has, use the post's reply_count, not the length of this response.
Thread shape: The response can include replies to other replies. The original post is not included.

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.