{"uid":"cap_w04cne-_48FXE1JwClNTD","slug":"twitr-sh-x-twitter-timeline-engagement-fetcher-ae087fa5","name":"twitr.sh X/Twitter Timeline & Engagement Fetcher","description":"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.","url":"https://twitr.sh/api/tools/x_timeline","method":"POST","headers":{},"bodySchema":{"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"}}},"responseSchema":{"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}},"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_YZ7dAwUOeDpVsZR0WXi16","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":"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.","exampleAgentPrompt":"Fetch the last 50 tweets posted by @elonmusk, including replies, and return them so I can analyze his recent activity.","exampleUseCases":[{"title":"Monitor competitor brand account activity","prompt":"Pull the most recent 200 tweets and replies from @OpenAI's Twitter account so I can track what they've been announcing this month."},{"title":"Identify top engagers on a viral tweet","prompt":"Get me up to 500 people who retweeted tweet ID 1823456789012345678 so I can see who's amplifying that post."},{"title":"Build follower list for audience research","prompt":"Fetch the first 1000 followers of the Twitter account @ycombinator, only verified ones, so I can analyze the makeup of their verified audience."}],"resultDescription":"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.","failureModes":["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"],"whenToPreferThis":"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.","instructions":null,"reviewSummary":null,"reviewSummaryHighlights":null,"reviewSummaryConcerns":null,"reviewSummaryGeneratedAt":null,"activationCount":0,"lastUsedAt":null,"lastSuccessfullyRanAt":null,"lastHealthCheckAt":"2026-09-14T12:44:40.662Z","isFirstParty":false}