# twitr.sh X/Twitter Read API

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

Read live X/Twitter data — look up tweets, user profiles, follower relationships, trending topics, articles, and media — pay per call in USDC with no API key required

## Facts

- Endpoint: POST https://twitr.sh/api/tools/x_read
- Price: $0.0012/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-read-api-b69e610b
- Structured record (JSON): https://api.zero.xyz/v1/capabilities/cap_tgcEwbHvHTlBKkL0QL5zt

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-read-api-b69e610b -d '<json body>'
```

Example prompt: Can you look up the tweet with ID 1234567890123456789 on X and also grab the full profile for username @elonmusk? Use the twitr.sh read API — no API key needed, just pay per call in USDC.

## When to prefer this

Choose this endpoint when you need live, structured X/Twitter data without setting up a Twitter developer account or managing API keys. Ideal for agents that need occasional or event-driven reads (single tweet lookup, profile enrichment, follower checks, trending topics) and want pay-as-you-go USDC billing with zero-charge guarantees on failed calls. Prefer over Twitter's own API when avoiding OAuth setup friction matters, or when you need a unified multi-resource read interface (tweets, users, trends, articles, media) under one endpoint.

## Known failure modes

- Invalid or deleted tweet ID returns not-found error; call is not charged
- Suspended or private user account returns access-denied error; call is not charged
- Invalid WOEID returns error for trends endpoint
- Batch input exceeding 100 IDs returns validation error
- Missing required resource-specific fields (e.g. source/target for check-follower) returns parameter error
- Network or upstream X API outage returns 503; call is not charged on failure

## How this service works

Read live X/Twitter data: look up a single tweet or user profile, batch-read up to 100 tweets or users at once, check whether one account follows another, fetch trending topics by region, extract a long-form article, or download tweet media. Pay per call in USDC — no API key, no signup; failed calls are never charged.

## Output

Returns structured JSON containing the requested data: tweet objects (text, author, timestamp, engagement metrics), user profile objects (bio, follower count, following count, verification status), boolean follower relationship, ranked list of trending topics with tweet volumes, extracted article text, or downloaded media URLs — depending on the resource type called.

## Request schema (JSON Schema)

```json
{
 "type": "object",
 "properties": {
  "id": {
   "type": "string",
   "description": "Tweet ID, user ID, or username (depends on resource)."
  },
  "ids": {
   "type": "array",
   "items": {
    "type": "string"
   },
   "description": "batch-tweets|batch-users: up to 100 tweet IDs or user IDs/usernames."
  },
  "count": {
   "type": "integer",
   "description": "trends: number of trends to return."
  },
  "woeid": {
   "type": "integer",
   "description": "trends: region WOEID (default 1 = worldwide)."
  },
  "source": {
   "type": "string",
   "description": "check-follower: source username."
  },
  "target": {
   "type": "string",
   "description": "check-follower: target username."
  },
  "resource": {
   "enum": [
    "get-tweet",
    "get-user",
    "batch-tweets",
    "batch-users",
    "check-follower",
    "trends",
    "article",
    "followers-you-know",
    "download-media"
   ],
   "type": "string",
   "description": "Which read operation to run."
  },
  "resultsLimit": {
   "type": "integer",
   "maximum": 10000,
   "minimum": 1,
   "description": "Mandatory for followers-you-know: max results, billed per result."
  }
 }
}
```

## Response schema (JSON Schema)

```json
{
 "type": "json",
 "example": {
  "items": [
   {
    "id": "2079908425904042170",
    "text": "Ship early, ship often.",
    "createdAt": "2026-02-24T10:05:00.000Z",
    "likeCount": 4210,
    "retweetCount": 512,
    "authorUsername": "vercel"
   }
  ],
  "runId": "tw_example",
  "payment": {
   "amount": "0.001200",
   "currency": "USD",
   "protocol": "x402"
  },
  "duration": 1
 }
}
```

## More

- Live health (JSON, refreshed every minute): https://www.zero.xyz/c/twitr-sh-x-twitter-read-api-b69e610b/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)