# twitr.sh X/Twitter Search

> twitr.sh X/Twitter Search is a paid API for AI agents from twitr.sh, paid per call via x402, $0.024/call, status unknown (last checked 2026-09-14).

Search X/Twitter tweets or user profiles using advanced operators including keywords, exact phrases, from-user, language, date range, media type, and engagement filters.

## Facts

- Endpoint: POST https://twitr.sh/api/tools/x_search
- Price: $0.024/call
- Payment: x402
- Status: unknown
- Last checked: 2026-09-14
- Activations on Zero: 0
- Tags: x402
- Canonical page: https://www.zero.xyz/c/twitr-sh-x-twitter-search-a98c999f
- Structured record (JSON): https://api.zero.xyz/v1/capabilities/cap_pUBfTxyU-DzIcyGSwHOyj

Status and success rate cover calls made through Zero and Zero's own probes. Third-party monitors may report differently.

## How to call it through Zero

Zero handles the 402 payment challenge and records the run. With the Zero CLI installed (`npm i -g @zeroxyz/cli`):

```sh
zero fetch --capability twitr-sh-x-twitter-search-a98c999f -d '<json body>'
```

Example prompt: Search X/Twitter for up to 50 tweets mentioning 'NVDA earnings' from verified accounts only, with at least 10 likes, posted between 2024-10-01 and 2024-10-31, and only include tweets with images.

## When to prefer this

Choose this endpoint when you need flexible, operator-rich search across X/Twitter tweets or user profiles — especially when you need to combine multiple filters like date ranges, engagement thresholds, language, media type, and verified-only status in a single call. Prefer this over generic social listening tools when you need real-time X data with fine-grained control over what you retrieve and a per-tweet billing model that scales with usage.

## Known failure modes

- Missing required resultsLimit for tweet searches returns an error
- Invalid date format (not YYYY-MM-DD) causes query rejection
- Unsupported mediaType enum value causes validation failure
- Empty or malformed query string with no operators may return zero results
- resultsLimit exceeding 10000 is rejected
- Rate limiting or X API unavailability may cause timeouts or partial results

## How this service works

Search X/Twitter tweets with the full operator set — keyword, exact phrase, from-user, language, date range, media type, minimum likes/retweets, verified-only — or search user profiles by keyword. Billed per tweet returned against your resultsLimit cap. Built for tracking what people say about a topic, brand, or ticker in real time.

## Output

Returns a list of matching tweets (or user profiles for search-users) including tweet content, author info, engagement counts (likes, retweets, replies), timestamps, and media metadata, up to the resultsLimit cap. For user searches, returns a pagination cursor for fetching additional results.

## Request schema (JSON Schema)

```json
{
 "type": "object",
 "properties": {
  "q": {
   "type": "string",
   "description": "Search query (X operator syntax supported for tweets)."
  },
  "type": {
   "enum": [
    "search-tweets",
    "search-users"
   ],
   "type": "string",
   "description": "Search tweets (default) or users."
  },
  "cursor": {
   "type": "string",
   "description": "search-users: pagination cursor from a previous call's report.next_cursor."
  },
  "fromUser": {
   "type": "string"
  },
  "language": {
   "type": "string"
  },
  "minFaves": {
   "type": "integer"
  },
  "mediaType": {
   "enum": [
    "images",
    "videos",
    "gifs",
    "media"
   ],
   "type": "string"
  },
  "sinceDate": {
   "type": "string",
   "description": "YYYY-MM-DD"
  },
  "untilDate": {
   "type": "string",
   "description": "YYYY-MM-DD"
  },
  "minReplies": {
   "type": "integer"
  },
  "exactPhrase": {
   "type": "string"
  },
  "minRetweets": {
   "type": "integer"
  },
  "excludeWords": {
   "type": "string"
  },
  "resultsLimit": {
   "type": "integer",
   "maximum": 10000,
   "minimum": 1,
   "description": "search-tweets: MANDATORY max tweets returned, billed per tweet."
  },
  "verifiedOnly": {
   "type": "boolean"
  },
  "advancedQuery": {
   "type": "string",
   "description": "Raw X search operator string appended to q."
  }
 }
}
```

## Response schema (JSON Schema)

```json
{
 "type": "json",
 "example": {
  "items": [
   {
    "id": "1893710452812718080",
    "text": "This is a great thread, thanks for sharing.",
    "createdAt": "2026-02-24T10:05:00.000Z",
    "likeCount": 1180,
    "authorUsername": "elonmusk"
   }
  ],
  "runId": "tw_example",
  "payment": {
   "amount": "0.060000",
   "currency": "USD",
   "protocol": "x402"
  },
  "duration": 2
 }
}
```

## More

- Live health (JSON, refreshed every minute): https://www.zero.xyz/c/twitr-sh-x-twitter-search-a98c999f/health.json
- [Zero catalog index](https://www.zero.xyz/llms.txt)
- [Other services from twitr.sh](https://www.zero.xyz/host/twitr.sh/llms.txt)