{"uid":"cap_Z-jKRx5ES-emBTxIehnZB","slug":"twitr-sh-x-twitter-private-inbox-reader-4ac924f9","name":"twitr.sh X/Twitter Private Inbox Reader","description":"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.","url":"https://twitr.sh/api/tools/x_inbox","method":"POST","headers":{},"bodySchema":{"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."}}},"responseSchema":{"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}},"example":null,"exampleRequest":null,"tags":["x402"],"displayCostAmount":"0.024","displayCostAsset":"USDC","priceDynamic":false,"priceHint":null,"priceStatus":"priced","priceSource":"probe","requiresHandshake":false,"reviewCount":0,"rating":{"score":"0.00","successRate":"0.00","reviews":0,"stars":null,"state":"unrated"},"availabilityStatus":"unknown","priceObserved":null,"sessionDeposit":null,"pricing":{"kind":"static","summary":"$0.024/call","primary":{"kind":"static","protocol":"x402","network":"base","amountUsd":"0.024","per":"call","confidence":"exact"},"accepted":[{"kind":"static","protocol":"x402","network":"base","amountUsd":"0.024","per":"call","confidence":"exact"}]},"paymentMethods":[{"uid":"pm_5ob9e5KmuPgJ_W_n4c4JI","protocol":"x402","methodType":"crypto","chain":"base","mode":"charge","costAmount":"0.024","costPer":"request","priority":0,"asset":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913","unit":"request","depositMicros":null,"planRef":null}],"brandName":null,"brandSlug":null,"brandBaseUrl":null,"brandDocsUrl":null,"whatItDoes":"Reads private X/Twitter account surfaces — bookmarks, bookmark folders, notifications, and DM history — for a wallet-connected handle.","exampleAgentPrompt":"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.","exampleUseCases":[{"title":"Monitor brand mentions in notifications","prompt":"Fetch the latest 200 notifications for my X account 'brandaccount' and filter them to mentions only — I want to see everyone who's been tagging us today."},{"title":"Review saved bookmarks in a folder","prompt":"Get my bookmarks from the 'Research' folder on my X account 'janedoe', up to 100 items — I want to review what I've saved there."},{"title":"Retrieve DM history with a contact","prompt":"Show me the last 50 direct messages between my X account 'myhandle' and user ID '123456789' so I can catch up on the conversation thread."}],"resultDescription":"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.","failureModes":["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"],"whenToPreferThis":"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.","instructions":null,"reviewSummary":null,"reviewSummaryHighlights":null,"reviewSummaryConcerns":null,"reviewSummaryGeneratedAt":null,"activationCount":0,"lastUsedAt":null,"lastSuccessfullyRanAt":null,"lastHealthCheckAt":"2026-09-14T12:33:08.503Z","isFirstParty":false}