---
title: "X/Twitter Read"
method: POST
path: "/api/tools/x_read"
tags: ["Social"]
---

# X/Twitter Read

`POST /api/tools/x_read`

## Request

- Base URL: `https://twitr.sh`
- URL: `https://twitr.sh/api/tools/x_read`
- Auth: none declared

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.

## Request body

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

## Response `200`

Result dataset.

- object
  - `items` object[], required: Array of returned items. Shape varies per tool — see each tool's documentation.
  - `runId` string: Run ID for debugging/audit.
  - `duration` integer: Run duration in seconds.

## Other responses

- `202`: Async extraction accepted — body carries {snapshot_id, status_url} (x_extract only).
- `400`: Bad request — missing resultsLimit or Idempotency-Key where required. Body is a Problem with `retryable:false` and a `hint`; never charged.
- `402`: Payment Required. Per-result reads require x402 upto on Base: authorize the maximum and pay only for delivered records, with a $0.0024 non-empty minimum and zero for empty results. Fixed-price operations may additionally offer exact x402 and MPP.
- `403`: Acting handle not connected to this wallet — connect it via /api/x-accounts/start first; never charged.
- `404`: Unknown tool path — GET /openapi.json for the valid list; never charged.
- `429`: Rate limited — `retryable:true`; retry unchanged after the Retry-After header; never charged.
- `500`: Unexpected handler error — inspect payment receipt before retrying.
- `502`: Upstream provider error — `retryable:true`; inspect payment receipt before retrying; prepaid operations may already be charged.
- `503`: Service capacity temporarily unavailable — `retryable:true`; retry later; never charged.

---

[API](https://skmtc.dev/twitr/apis/twitr-sh.md) · [All operations](https://skmtc.dev/twitr/apis/twitr-sh/llms.txt) · [OpenAPI document](https://skmtc.dev/twitr/apis/twitr-sh/revisions/f6390fcee344?raw)