# twit.sh Tweet Search

> twit.sh Tweet Search is a paid API for AI agents from twit.sh, paid per call via x402, $0.006/call, status unknown (last checked 2026-10-13).

Search Twitter/X in real-time by keywords, hashtags, users, date ranges, and engagement filters, paying per request in USDC via x402 with no API keys required.

## Facts

- Endpoint: GET https://twit.sh/tweets/search?utm_source=zero.xyz
- Price: $0.006/call
- Payment: x402
- Status: unknown
- Last checked: 2026-10-13
- Activations on Zero: 0
- Tags: x402
- Canonical page: https://www.zero.xyz/c/twit-sh-tweet-search-a552307d
- Structured record (JSON): https://api.zero.xyz/v1/capabilities/cap_mAo36EErzjxIIFZmy4BRP

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 twit-sh-tweet-search-a552307d
```

Example prompt: Search Twitter for tweets mentioning 'bitcoin' that have at least 1000 likes, posted between 2024-01-01 and 2024-06-30, and show me the top results.

## When to prefer this

Choose this endpoint when an AI agent needs to search Twitter/X data in real-time without setting up Twitter developer credentials or managing OAuth tokens. It is ideal for autonomous agents that pay per request in USDC on Base via x402 and need flexible tweet search with rich filters (date range, engagement minimums, hashtags, exact phrases, user scoping). Prefer it over direct Twitter API access when zero setup friction and crypto-native micropayment billing are priorities.

## Known failure modes

- No results returned when search filters are too restrictive — try broadening the date range or lowering engagement thresholds
- Payment failure if the calling agent's USDC balance on Base is insufficient
- Invalid date format (must be YYYY-MM-DD) causes rejected request
- Conflicting filters (e.g. both 'words' and 'noneWords' containing the same term) may return empty results
- next_token expires or becomes invalid if too much time passes between paginated requests

## How this service works

Real-time Twitter/X data for AI agents. No sign-up, no API keys. Pay per request in USDC on Base via x402. Fully autonomous.

## Output

Returns a JSON array of tweet objects, each containing the tweet ID, full text, author name, username, creation timestamp, and public metrics (like count, retweet count, reply count, quote count). Also includes a next_token for cursor-based pagination to fetch additional pages of results.

## 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": {
      "to": {
       "type": "string",
       "description": "Tweets replying to this username"
      },
      "from": {
       "type": "string",
       "description": "Tweets from this username"
      },
      "since": {
       "type": "string",
       "description": "Start date (YYYY-MM-DD)"
      },
      "until": {
       "type": "string",
       "description": "End date (YYYY-MM-DD)"
      },
      "words": {
       "type": "string",
       "description": "All these words must appear"
      },
      "phrase": {
       "type": "string",
       "description": "Exact phrase match"
      },
      "anyWords": {
       "type": "string",
       "description": "Any of these words"
      },
      "hashtags": {
       "type": "string",
       "description": "Filter by hashtag"
      },
      "minLikes": {
       "type": "string",
       "description": "Minimum like count"
      },
      "noneWords": {
       "type": "string",
       "description": "Exclude these words"
      },
      "mentioning": {
       "type": "string",
       "description": "Tweets mentioning this username"
      },
      "minReplies": {
       "type": "string",
       "description": "Minimum reply count"
      },
      "minReposts": {
       "type": "string",
       "description": "Minimum retweet count"
      },
      "next_token": {
       "type": "string",
       "description": "Pagination cursor"
      }
     }
    }
   },
   "additionalProperties": false
  },
  "output": {
   "type": "object",
   "required": [
    "type"
   ],
   "properties": {
    "type": {
     "type": "string"
    },
    "example": {
     "type": "object"
    }
   }
  }
 }
}
```

## Response schema (JSON Schema)

```json
{
 "type": "json",
 "example": {
  "data": [
   {
    "id": "1110302988",
    "text": "Running bitcoin",
    "author": {
     "id": "9253672",
     "name": "Hal Finney",
     "username": "halfin"
    },
    "created_at": "2009-01-11T03:39:18.000Z",
    "public_metrics": {
     "like_count": 134000,
     "quote_count": 3500,
     "reply_count": 5400,
     "retweet_count": 32000
    }
   }
  ],
  "meta": {
   "next_token": "abc123"
  }
 }
}
```

## More

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