# PayToll Twitter Search

> PayToll Twitter Search is a paid API for AI agents from api.paytoll.io, paid per call via x402, $0.08/call, status down (last checked 2026-09-16, last successful call 2026-07-15).

Searches Twitter/X posts using X API query syntax and returns matching tweets with author data, metrics, and pagination support

## Facts

- Endpoint: POST https://api.paytoll.io/v1/twitter/search
- Price: $0.08/call
- Payment: x402
- Status: down
- Last checked: 2026-09-16
- Last successful call: 2026-07-15
- Success rate: 100% of calls made through Zero
- Rating: 4.7 / 5 from 1 review
- Activations on Zero: 42
- Tags: x402
- Canonical page: https://www.zero.xyz/c/api-paytoll-io-f2feb2d8
- Structured record (JSON): https://api.zero.xyz/v1/capabilities/cap_a87Btk_rlGf3RRfq3wiEl

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 api-paytoll-io-f2feb2d8 -d '<json body>'
```

Example prompt: Search Twitter for the 20 most recent English-language tweets about 'ethereum price' that aren't retweets — sort by recency and include the author profiles and public engagement metrics for each tweet.

## When to prefer this

Use this endpoint when you need to search Twitter/X posts programmatically with full X API query syntax support (operators like lang:, -is:retweet, etc.), need author metadata alongside tweets, and want to pay per-call in USDC without a Twitter API subscription. Prefer over direct Twitter API access when you lack API credentials or want simple per-use billing.

## Known failure modes

- Invalid X API query syntax returns a 400 error
- Query string under 1 character or over 512 characters is rejected
- maxResults outside 10-20 range is rejected
- Invalid nextToken causes pagination error
- Payment not provided or insufficient results in 402 Payment Required
- Rate limits or X API downtime return 5xx errors

## How this service works

Payment required: $0.08

## Output

A list of up to 20 tweets matching the query, each with requested fields (id, text, author_id, created_at, public_metrics by default), optionally including full author user objects, plus a nextToken for pagination if more results exist.

## Example request

```json
{
 "query": "artificial intelligence lang:en -is:retweet",
 "sortOrder": "recency",
 "maxResults": 10,
 "tweetFields": [
  "id",
  "text",
  "author_id",
  "created_at",
  "public_metrics"
 ],
 "includeAuthor": true
}
```

## Request schema (JSON Schema)

```json
{
 "type": "object",
 "properties": {
  "query": {
   "type": "string",
   "maxLength": 512,
   "minLength": 1,
   "description": "Search query (X API query syntax). Example: \"bitcoin lang:en -is:retweet\""
  },
  "nextToken": {
   "type": "string",
   "description": "Pagination token from a previous response"
  },
  "sortOrder": {
   "enum": [
    "recency",
    "relevancy"
   ],
   "type": "string",
   "default": "recency",
   "description": "Sort order for results"
  },
  "maxResults": {
   "type": "integer",
   "default": 10,
   "maximum": 20,
   "minimum": 10,
   "description": "Number of results (10-20)"
  },
  "tweetFields": {
   "type": "array",
   "items": {
    "enum": [
     "id",
     "text",
     "author_id",
     "created_at",
     "public_metrics",
     "conversation_id",
     "in_reply_to_user_id",
     "lang",
     "possibly_sensitive",
     "source"
    ],
    "type": "string"
   },
   "description": "Tweet fields to return. Defaults to: id, text, author_id, created_at, public_metrics"
  },
  "includeAuthor": {
   "type": "boolean",
   "default": true,
   "description": "Include author user objects in response"
  }
 }
}
```

## More

- Live health (JSON, refreshed every minute): https://www.zero.xyz/c/api-paytoll-io-f2feb2d8/health.json
- [Zero catalog index](https://www.zero.xyz/llms.txt)
- [Other services from api.paytoll.io](https://www.zero.xyz/host/api.paytoll.io/llms.txt)