# twitr.sh X/Twitter Private Inbox Reader

> twitr.sh X/Twitter Private Inbox 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 private X/Twitter account surfaces — bookmarks, bookmark folders, notifications, and DM history — for a wallet-connected handle.

## Facts

- Endpoint: POST https://twitr.sh/api/tools/x_inbox
- 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-private-inbox-reader-4ac924f9
- Structured record (JSON): https://api.zero.xyz/v1/capabilities/cap_Z-jKRx5ES-emBTxIehnZB

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-private-inbox-reader-4ac924f9 -d '<json body>'
```

Example prompt: Pull up to 50 of my latest X notifications filtered by mentions for my account handle 'johndoe' — I want to see who's been tagging me recently.

## When to prefer this

Use this endpoint when you need to read private, authenticated surfaces of an X/Twitter account — specifically bookmarks, bookmark folders, notifications, or DM history — that are not accessible via public APIs. Requires the wallet to have already connected the target X handle. Prefer this over the public tweet/user lookup endpoint when you need private inbox data rather than public profile or tweet data.

## Known failure modes

- Account not connected to wallet — returns authorization error
- Handle not owned by calling wallet — access denied
- Invalid action enum value — validation error
- DM target_user_id not found or no conversation exists — empty or error response
- resultsLimit exceeds maximum of 10000 — validation error
- Rate limiting or X API quota exceeded — upstream error
- folderId not found for bookmarks — empty or error result

## How this service works

Read a connected X/Twitter account's private surfaces: bookmarks and bookmark folders, notifications, and DM history. Billed per item returned; readable only for handles this wallet connected.

## Output

Returns a list of items matching the requested action: bookmark objects (tweet data, metadata), bookmark folder listings, notification objects (type, actor, tweet reference), or DM message objects (sender, content, timestamp). Billed per item returned; max items controlled by resultsLimit.

## Request schema (JSON Schema)

```json
{
 "type": "object",
 "properties": {
  "type": {
   "type": "string",
   "description": "notifications: optional filter (e.g. mentions)."
  },
  "maxId": {
   "type": "string",
   "description": "dm_history: paginate before this message id."
  },
  "action": {
   "enum": [
    "bookmarks",
    "bookmark_folders",
    "notifications",
    "dm_history"
   ],
   "type": "string",
   "description": "Which inbox read to run."
  },
  "account": {
   "type": "string",
   "description": "A connected X handle owned by this wallet (no @)."
  },
  "folderId": {
   "type": "string",
   "description": "bookmarks: optional folder to read."
  },
  "resultsLimit": {
   "type": "integer",
   "maximum": 10000,
   "minimum": 1,
   "description": "Max items to return (billed per item); ignored for bookmark_folders."
  },
  "target_user_id": {
   "type": "string",
   "description": "dm_history: the other party's user id."
  }
 }
}
```

## Response schema (JSON Schema)

```json
{
 "type": "json",
 "example": {
  "items": [
   {
    "id": "1893710452812718080",
    "text": "saved this thread",
    "createdAt": "2026-02-24T10:05:00.000Z"
   }
  ],
  "runId": "tw_example",
  "payment": {
   "amount": "0.060000",
   "currency": "USD",
   "protocol": "x402"
  },
  "duration": 1
 }
}
```

## More

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