# twitr.sh X/Twitter List Reader

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

Reads an X/Twitter List's tweet timeline, member roster, or follower list, returning up to a specified number of items billed per result.

## Facts

- Endpoint: POST https://twitr.sh/api/tools/x_lists
- Price: $0.024/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-list-reader-615cd07c
- Structured record (JSON): https://api.zero.xyz/v1/capabilities/cap_HtI5bkNVmBK6T6BZMsdiu

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-list-reader-615cd07c -d '<json body>'
```

Example prompt: Pull the latest 50 tweets from Twitter list ID 1234567890, including replies, so I can see what the accounts in that curated list have been posting.

## When to prefer this

Choose this endpoint when you need to aggregate content or members from a pre-curated X/Twitter List rather than searching broadly or fetching a single user's timeline. It is ideal for monitoring a defined group of accounts as one unified feed, auditing list membership, or understanding a list's follower base. Prefer it over the search endpoint when the set of accounts is already defined as a Twitter List, and over the user timeline endpoint when you need multi-account aggregation in a single call.

## Known failure modes

- Invalid or non-existent List ID returns a 404-style error
- List is private or restricted and the caller lacks access, returning an authorization error
- resultsLimit not provided (mandatory field) causes request rejection
- sinceTime/untilTime in wrong format causes parsing failure
- Rate limits or quota exhaustion on the underlying Twitter API returning a 429 or service error
- Billing failure if USDC balance is insufficient for the requested resultsLimit

## How this service works

Read an X/Twitter List: its combined tweet timeline, its member roster, or its followers. Billed per item returned. Useful for following a curated set of accounts as one feed.

## Output

An array of items matching the requested kind: for 'tweets', tweet objects with content, author, timestamp, engagement metrics and reply metadata; for 'members' or 'followers', user profile objects with handle, display name, bio, follower count, and verification status. The number of items is capped at resultsLimit and billed per item returned.

## Request schema (JSON Schema)

```json
{
 "type": "object",
 "properties": {
  "id": {
   "type": "string",
   "description": "List ID."
  },
  "kind": {
   "enum": [
    "tweets",
    "members",
    "followers"
   ],
   "type": "string",
   "description": "What to read from the list."
  },
  "sinceTime": {
   "type": "string"
  },
  "untilTime": {
   "type": "string"
  },
  "resultsLimit": {
   "type": "integer",
   "maximum": 10000,
   "minimum": 1,
   "description": "MANDATORY: max items returned, billed per item."
  },
  "includeReplies": {
   "type": "boolean"
  }
 }
}
```

## Response schema (JSON Schema)

```json
{
 "type": "json",
 "example": {
  "items": [
   {
    "id": "1893710452812718080",
    "text": "This is a great thread, thanks for sharing.",
    "createdAt": "2026-02-24T10:05:00.000Z",
    "likeCount": 1180,
    "authorUsername": "elonmusk"
   }
  ],
  "runId": "tw_example",
  "payment": {
   "amount": "0.120000",
   "currency": "USD",
   "protocol": "x402"
  },
  "duration": 2
 }
}
```

## More

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