# Twitter/X Search API

> Twitter/X Search API is a paid API for AI agents from twitter.use.x402atlas.com, paid per call via x402, $0.005/call, status unknown (last checked 2026-09-14).

Search Twitter/X posts using keywords or advanced-search syntax, returning up to 20 normalized tweets with full text, author details, and engagement metrics.

## Facts

- Endpoint: GET https://twitter.use.x402atlas.com/search
- Price: $0.005/call
- Payment: x402
- Status: unknown
- Last checked: 2026-09-14
- Activations on Zero: 0
- Tags: x402
- Canonical page: https://www.zero.xyz/c/twitter-x-search-api-b281b9a1
- Structured record (JSON): https://api.zero.xyz/v1/capabilities/cap_aTQsQJlmB6LeUgx-NC5yX

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 twitter-x-search-api-b281b9a1
```

Example prompt: Search Twitter/X for the latest tweets containing the words 'OpenAI GPT-5' and show me the top results with engagement metrics like likes, retweets, and views.

## When to prefer this

Use this endpoint when you need to search public Twitter/X posts by keyword or phrase and require normalized, structured output including full author profiles and engagement metrics. Prefer this over building your own Twitter scraper or using the official Twitter API directly when cost predictability per call ($0.005 USDC) and simplified schema normalization matter. Choose this over sibling endpoints (user timeline, media timeline, lists) when you are doing open keyword search rather than fetching posts from a known specific user or community.

## Known failure modes

- Missing or invalid 'words' query parameter returns no results or an error
- Rate limiting or upstream Twitter API restrictions may return empty results
- Private or suspended accounts' tweets will not appear in results
- Pagination cursor expiry may prevent deep pagination
- Network timeout from upstream X API causing delayed or failed responses
- Ambiguous query keywords may return irrelevant tweets

## How this service works

Search Twitter/X with structured filters or raw advanced-search syntax. Returns up to 20 normalized tweets with full text, author details, engagement metrics and a pagination cursor.

## Output

Returns up to 20 tweet objects, each containing the tweet ID, full text, BCP-47 language code, creation timestamp, expanded URLs, and a nested author object (ID, name, screen name, avatar, follower count, bio, verification status) plus engagement counts (likes, retweets, replies, quotes, views, bookmarks). Also returns the assembled advanced-search query string, result ranking type (top/latest/media), a pagination cursor for the next page, and the UTC timestamp when the query was executed.

## Request schema (JSON Schema)

```json
{
 "type": "object",
 "$schema": "https://json-schema.org/draft/2020-12/schema",
 "required": [
  "input"
 ],
 "properties": {
  "input": {
   "type": "object",
   "required": [
    "type",
    "method"
   ],
   "properties": {
    "type": {
     "type": "string",
     "const": "http"
    },
    "method": {
     "enum": [
      "GET"
     ],
     "type": "string"
    },
    "queryParams": {
     "type": "object",
     "properties": {
      "words": {
       "type": "string",
       "description": "Tweets containing all these words"
      }
     }
    }
   },
   "additionalProperties": false
  },
  "output": {
   "type": "object",
   "required": [
    "type"
   ],
   "properties": {
    "type": {
     "type": "string"
    },
    "example": {
     "type": "object",
     "properties": {
      "type": {
       "enum": [
        "top",
        "latest",
        "media"
       ],
       "type": "string",
       "description": "Result ranking used for this page"
      },
      "query": {
       "type": "string",
       "description": "The assembled X advanced-search query string sent upstream"
      },
      "cursor": {
       "type": "string",
       "description": "Pagination cursor for the next page, if any"
      },
      "tweets": {
       "type": "array",
       "items": {
        "type": "object",
        "properties": {
         "id": {
          "type": "string",
          "description": "Tweet ID"
         },
         "lang": {
          "type": "string",
          "description": "BCP-47 language code"
         },
         "text": {
          "type": "string"
         },
         "urls": {
          "type": "array",
          "items": {
           "type": "string"
          },
          "description": "Expanded URLs linked in the tweet"
         },
         "likes": {
          "type": "integer"
         },
         "views": {
          "type": "integer"
         },
         "author": {
          "type": "object",
          "properties": {
           "id": {
            "type": "string"
           },
           "name": {
            "type": "string"
           },
           "avatar": {
            "type": "string"
           },
           "verified": {
            "type": "boolean",
            "description": "Blue-check verification status"
           },
           "followers": {
            "type": "integer"
           },
           "description": {
            "type": "string"
           },
           "screen_name": {
            "type": "string"
   
… (truncated)
```

## Response schema (JSON Schema)

```json
{
 "type": "json",
 "example": {
  "type": "top",
  "query": "from:@PancakeSwap filter:replies",
  "cursor": "DAACCgACHMe1FCaAJxAKAAMcx7UU…",
  "tweets": [
   {
    "id": "2071965671001608665",
    "lang": "en",
    "text": "Stack your tokenized assets ⬇️\nhttps://t.co/peohoKiMyQ",
    "urls": [
     "https://pancakeswap.finance/stocks"
    ],
    "likes": 16,
    "views": 3534,
    "author": {
     "id": "1305349277422477313",
     "name": "PancakeSwap",
     "avatar": "https://pbs.twimg.com/profile_images/2004910939959967744/wr7-zpVh_normal.jpg",
     "verified": true,
     "followers": 2132825,
     "description": "Everyone's favorite DEX. Swap, trade, and earn across 10+ chains.",
     "screen_name": "PancakeSwap"
    },
    "quotes": 0,
    "replies": 1,
    "is_quote": false,
    "retweets": 2,
    "bookmarks": 0,
    "created_at": "2026-06-30T14:34:45Z",
    "conversation_id": "2071965667491000381"
   }
  ],
  "queried_at": "2026-07-05T12:00:00Z",
  "tweet_count": 1
 }
}
```

## More

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