# twitr.sh X/Twitter Timeline & Engagement Fetcher

> twitr.sh X/Twitter Timeline & Engagement Fetcher 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).

Fetch a Twitter/X user's timeline (tweets, replies, likes, media, mentions), follower/following lists, or per-tweet engagement lists (repliers, quoters, retweeters, favoriters) billed per item returned.

## Facts

- Endpoint: POST https://twitr.sh/api/tools/x_timeline
- 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-timeline-engagement-fetcher-ae087fa5
- Structured record (JSON): https://api.zero.xyz/v1/capabilities/cap_w04cne-_48FXE1JwClNTD

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-timeline-engagement-fetcher-ae087fa5 -d '<json body>'
```

Example prompt: Fetch the last 50 tweets posted by @elonmusk, including replies, and return them so I can analyze his recent activity.

## When to prefer this

Choose this endpoint when you need to retrieve timeline or engagement data for a specific Twitter/X user or tweet — such as fetching someone's post history, follower/following lists, or the list of accounts who interacted with a specific tweet. It covers 13 distinct kinds of Twitter list data in one endpoint, making it the right choice for account monitoring, audience analysis, and engagement extraction tasks. Prefer sibling endpoints for search queries, trending topics, single-tweet lookups, or community/list-specific data.

## Known failure modes

- Invalid or nonexistent user ID/username returns a not-found error
- Invalid tweet ID for tweet-level kinds returns an error
- resultsLimit not provided causes request rejection (mandatory field)
- Requesting private/protected account data without authorization returns an access error
- Rate limits or quota exhaustion may return a 429 or payment-related error
- Unsupported combination of kind and filters may return empty results or validation error

## How this service works

Fetch a user's X/Twitter timeline — their tweets, replies, likes, media posts, or mentions — plus follower and following lists, and per-tweet engagement lists (who replied, quoted, retweeted, or favorited). Billed per item returned. The building block for monitoring what an account posts or ranking accounts by activity.

## Output

A list of items (tweets, users, or engagement records) matching the requested timeline kind, up to the specified resultsLimit. Each item includes the relevant tweet or user data (text, timestamps, engagement counts, media, author info) as returned by the X/Twitter API. Billing is per item returned.

## Request schema (JSON Schema)

```json
{
 "type": "object",
 "properties": {
  "id": {
   "type": "string",
   "description": "User ID/username or tweet ID (depends on kind)."
  },
  "kind": {
   "enum": [
    "user-tweets",
    "user-replies",
    "user-likes",
    "user-media",
    "user-mentions",
    "followers",
    "following",
    "verified-followers",
    "tweet-replies",
    "tweet-quotes",
    "tweet-thread",
    "tweet-favoriters",
    "tweet-retweeters"
   ],
   "type": "string",
   "description": "Which timeline to fetch."
  },
  "language": {
   "type": "string"
  },
  "minFaves": {
   "type": "integer"
  },
  "mediaType": {
   "enum": [
    "images",
    "videos",
    "gifs",
    "media"
   ],
   "type": "string"
  },
  "resultsLimit": {
   "type": "integer",
   "maximum": 10000,
   "minimum": 1,
   "description": "MANDATORY: max items returned, billed per item."
  },
  "verifiedOnly": {
   "type": "boolean"
  },
  "includeReplies": {
   "type": "boolean"
  },
  "includeParentTweet": {
   "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": 3
 }
}
```

## More

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