twitr.sh

Read live X/Twitter data: look up a single tweet or user profile, batch-read up to 100 tweets or users at once, check whether one account follows another, fetch trending topics by region, extract a long-form article, or download tweet media. Pay per call in USDC — no API key, no signup; failed calls are never charged. Guidance: resource=get-tweet|get-user (id), batch-tweets|batch-users (ids array, ≤100), check-follower (source+target usernames), trends (optional woeid/count), article (tweet id), followers-you-know (id + mandatory resultsLimit), download-media (id or ids ≤50 — returns media file URLs on THIS origin; links live 7 days). Fixed-price per call/id except followers-you-know which is per-result.

{
  "type": "object",
  "properties": {
    "resource": {
      "type": "string",
      "enum": [
        "get-tweet",
        "get-user",
        "batch-tweets",
        "batch-users",
        "check-follower",
        "trends",
        "article",
        "followers-you-know",
        "download-media"
      ],
      "description": "Which read operation to run."
    },
    "id": {
      "type": "string",
      "description": "Tweet ID, user ID, or username (depends on resource)."
    },
    "ids": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "batch-tweets|batch-users: up to 100 tweet IDs or user IDs/usernames."
    },
    "source": {
      "type": "string",
      "description": "check-follower: source username."
    },
    "target": {
      "type": "string",
      "description": "check-follower: target username."
    },
    "woeid": {
      "type": "integer",
      "description": "trends: region WOEID (default 1 = worldwide)."
    },
    "count": {
      "type": "integer",
      "description": "trends: number of trends to return."
    },
    "resultsLimit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 10000,
      "description": "Mandatory for followers-you-know: max results, billed per result."
    }
  },
  "required": [
    "resource"
  ],
  "allOf": [
    {
      "if": {
        "properties": {
          "resource": {
            "const": "followers-you-know"
          }
        }
      },
      "then": {
        "required": [
          "resultsLimit"
        ]
      }
    }
  ]
}

Search X/Twitter tweets with the full operator set — keyword, exact phrase, from-user, language, date range, media type, minimum likes/retweets, verified-only — or search user profiles by keyword. Billed per tweet returned against your resultsLimit cap. Built for tracking what people say about a topic, brand, or ticker in real time. Guidance: type=search-tweets (default): q required, resultsLimit MANDATORY (billed per tweet returned). Supports the full filter set: fromUser, language, sinceDate/untilDate, mediaType, minFaves, verifiedOnly, exactPhrase, excludeWords, advancedQuery, and more. type=search-users: q required; returns one results page per call — follow report.next_cursor for the next page (each page is a separate paid call).

{
  "type": "object",
  "properties": {
    "type": {
      "type": "string",
      "enum": [
        "search-tweets",
        "search-users"
      ],
      "description": "Search tweets (default) or users."
    },
    "q": {
      "type": "string",
      "description": "Search query (X operator syntax supported for tweets)."
    },
    "resultsLimit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 10000,
      "description": "search-tweets: MANDATORY max tweets returned, billed per tweet."
    },
    "cursor": {
      "type": "string",
      "description": "search-users: pagination cursor from a previous call's report.next_cursor."
    },
    "fromUser": {
      "type": "string"
    },
    "language": {
      "type": "string"
    },
    "sinceDate": {
      "type": "string",
      "description": "YYYY-MM-DD"
    },
    "untilDate": {
      "type": "string",
      "description": "YYYY-MM-DD"
    },
    "mediaType": {
      "type": "string",
      "enum": [
        "images",
        "videos",
        "gifs",
        "media"
      ]
    },
    "minFaves": {
      "type": "integer"
    },
    "minRetweets": {
      "type": "integer"
    },
    "minReplies": {
      "type": "integer"
    },
    "verifiedOnly": {
      "type": "boolean"
    },
    "exactPhrase": {
      "type": "string"
    },
    "excludeWords": {
      "type": "string"
    },
    "advancedQuery": {
      "type": "string",
      "description": "Raw X search operator string appended to q."
    }
  },
  "required": [
    "q"
  ],
  "allOf": [
    {
      "if": {
        "properties": {
          "type": {
            "const": "search-users"
          }
        }
      },
      "then": {},
      "else": {
        "required": [
          "resultsLimit"
        ]
      }
    }
  ]
}

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. Guidance: kind selects the timeline: user-tweets|user-replies|user-likes|user-media|user-mentions|followers|following|verified-followers (id = user) or tweet-replies|tweet-quotes|tweet-thread|tweet-favoriters|tweet-retweeters (id = tweet). resultsLimit is MANDATORY — billed per item returned. Search-operator filters (fromUser, language, mediaType, minFaves, …) apply to tweet timelines.

{
  "type": "object",
  "properties": {
    "kind": {
      "type": "string",
      "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"
      ],
      "description": "Which timeline to fetch."
    },
    "id": {
      "type": "string",
      "description": "User ID/username or tweet ID (depends on kind)."
    },
    "resultsLimit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 10000,
      "description": "MANDATORY: max items returned, billed per item."
    },
    "includeReplies": {
      "type": "boolean"
    },
    "includeParentTweet": {
      "type": "boolean"
    },
    "language": {
      "type": "string"
    },
    "mediaType": {
      "type": "string",
      "enum": [
        "images",
        "videos",
        "gifs",
        "media"
      ]
    },
    "minFaves": {
      "type": "integer"
    },
    "verifiedOnly": {
      "type": "boolean"
    }
  },
  "required": [
    "kind",
    "id",
    "resultsLimit"
  ]
}

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. Guidance: kind=tweets|members|followers; id = list ID. resultsLimit is MANDATORY — billed per item returned. tweets supports sinceTime/untilTime and includeReplies.

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

Read an X/Twitter Community: profile info, member and moderator rosters, the community's tweets, or keyword search inside the community. Fixed price for info; billed per item for rosters, tweets, and search. Guidance: kind=info (fixed price) or members|moderators|tweets|search (per-item — resultsLimit MANDATORY). id = community ID. search additionally requires q.

{
  "type": "object",
  "properties": {
    "kind": {
      "type": "string",
      "enum": [
        "info",
        "members",
        "moderators",
        "tweets",
        "search"
      ],
      "description": "What to read."
    },
    "id": {
      "type": "string",
      "description": "Community ID."
    },
    "q": {
      "type": "string",
      "description": "search: query within the community."
    },
    "resultsLimit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 10000,
      "description": "Mandatory for members/moderators/tweets/search: max items, billed per item."
    }
  },
  "required": [
    "kind",
    "id"
  ],
  "allOf": [
    {
      "if": {
        "properties": {
          "kind": {
            "const": "search"
          }
        }
      },
      "then": {
        "required": [
          "q"
        ]
      }
    }
  ]
}

Bulk-export X/Twitter data as downloadable datasets: followers, following, repliers, quoters, reposters, likers, mentions, full threads, list and community members, spaces, or people/tweet search results — 23 extractors. Runs async: you get a claim check immediately and poll a free status URL for the download link. Billed per result. Guidance: tool selects the extractor (23 options). Provide the matching target: targetTweetId (reply/repost/quote/thread/article/favoriters extractors), targetUsername (follower/following/verified/post/mention/likes/media), targetCommunityId, targetListId, targetSpaceId, or searchQuery (people_search, tweet_search_extractor). resultsLimit is MANDATORY — billed per result (article_extractor bills 5× per result). Runs ASYNC: the response is a claim check {snapshot_id, status_url}; poll status_url (free, SIWX) until status=ready for the download link. Idempotency-Key header is required so retries reuse the same job.

{
  "type": "object",
  "properties": {
    "tool": {
      "type": "string",
      "enum": [
        "follower_explorer",
        "following_explorer",
        "verified_follower_explorer",
        "post_extractor",
        "reply_extractor",
        "repost_extractor",
        "quote_extractor",
        "thread_extractor",
        "article_extractor",
        "favoriters",
        "mention_extractor",
        "user_likes",
        "user_media",
        "community_extractor",
        "community_moderator_explorer",
        "community_post_extractor",
        "community_search",
        "list_member_extractor",
        "list_post_extractor",
        "list_follower_explorer",
        "space_explorer",
        "people_search",
        "tweet_search_extractor"
      ],
      "description": "Which extractor to run."
    },
    "resultsLimit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 10000,
      "description": "MANDATORY: max results extracted, billed per result."
    },
    "targetTweetId": {
      "type": "string"
    },
    "targetUsername": {
      "type": "string"
    },
    "targetCommunityId": {
      "type": "string"
    },
    "targetListId": {
      "type": "string"
    },
    "targetSpaceId": {
      "type": "string"
    },
    "searchQuery": {
      "type": "string"
    },
    "language": {
      "type": "string"
    },
    "sinceDate": {
      "type": "string"
    },
    "untilDate": {
      "type": "string"
    },
    "mediaType": {
      "type": "string",
      "enum": [
        "images",
        "videos",
        "gifs",
        "media"
      ]
    },
    "minFaves": {
      "type": "integer"
    },
    "verifiedOnly": {
      "type": "boolean"
    }
  },
  "required": [
    "tool",
    "resultsLimit"
  ]
}

Watch an X/Twitter account or keyword query in real time: new tweets, replies, quotes, mentions, hashtags, and profile changes, delivered to your agent by free polling or HMAC-signed webhooks. Prepaid by the hour with a hard stop at expiry — no open-ended billing. The way to track a brand, competitor, or topic without re-polling paid reads. Guidance: action=create needs username (account monitor, e.g. "vercel") OR query (keyword monitor, X search syntax, ≤512 chars), optional eventTypes — 21 available: post events (tweet.new, .reply, .retweet, .quote, .media, .link, .poll, .mention, .hashtag, .longform) for any monitor, plus profile-change events (profile.avatar/banner/name/username/bio/location/url/verified/protected/pinned_tweet/unavailable.changed) for ACCOUNT monitors only; default all applicable — and hours (1–168, default 1). action=extend needs monitorId + hours; hours append to the current expiry (total prepaid window ≤ 720h). Extend at least 5 minutes BEFORE expiry — extends inside the final 5 minutes are refused (unpaid) to keep settlement from racing the expiry teardown. PREPAID: the monitor stops and is removed at expires_at unless extended — no open-ended billing; early deletion does not refund remaining hours. Idempotency-Key header REQUIRED — retries replay the original monitor instead of re-charging (on the MCP door, retries are protected by single-use payment credentials instead). Pay with USDC on Base (x402) or Tempo (MPP); Solana is not offered for monitors (stateful resources need a recoverable owner wallet). After creation: poll events at /api/monitors/{id}/events (free — SIWX sign-in with the paying wallet; do NOT poll in a tight loop) or register an HTTPS webhook once at /api/webhooks to push signed events straight to your AI agent (Claude, OpenClaw, Hermes, or any endpoint) in real time. Manage monitors at /api/monitors (SIWX).

{
  "type": "object",
  "properties": {
    "action": {
      "type": "string",
      "enum": [
        "create",
        "extend"
      ],
      "description": "Create a new monitor or extend an existing one."
    },
    "type": {
      "type": "string",
      "enum": [
        "account",
        "keyword"
      ],
      "description": "Monitor kind (create). Inferred from username/query when omitted."
    },
    "username": {
      "type": "string",
      "description": "X handle to monitor, without @ (create, type=account)."
    },
    "query": {
      "type": "string",
      "maxLength": 512,
      "description": "X search query to monitor (create, type=keyword)."
    },
    "eventTypes": {
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "tweet.new",
          "tweet.reply",
          "tweet.retweet",
          "tweet.quote",
          "tweet.media",
          "tweet.link",
          "tweet.poll",
          "tweet.mention",
          "tweet.hashtag",
          "tweet.longform",
          "profile.avatar.changed",
          "profile.banner.changed",
          "profile.name.changed",
          "profile.username.changed",
          "profile.bio.changed",
          "profile.location.changed",
          "profile.url.changed",
          "profile.verified.changed",
          "profile.protected.changed",
          "profile.pinned_tweet.changed",
          "profile.unavailable.changed"
        ]
      },
      "description": "Event types to receive (default: all applicable). Post events (tweet.*) work for any monitor; profile-change events (profile.*.changed) apply to ACCOUNT monitors only."
    },
    "hours": {
      "type": "integer",
      "minimum": 1,
      "maximum": 168,
      "description": "Prepaid hours to purchase (default 1)."
    },
    "monitorId": {
      "type": "string",
      "description": "Monitor to extend (extend only)."
    }
  },
  "required": [
    "action"
  ]
}

Run a provably fair giveaway on X/Twitter: pick crypto-random winners from a tweet's replies, with retweet, follow, hashtag, keyword, minimum-follower, and account-age conditions. Fixed price set upfront from your estimated entry count. Guidance: tweetUrl required. Optional: winnerCount (default 1), backupCount, uniqueAuthorsOnly, mustRetweet, mustFollowUsername, filterMinFollowers, filterAccountAgeDays, filterLanguage, requiredHashtags/Keywords/Mentions. Pricing is fixed upfront from the estimatedEntries you set (default 1000, max 10000) — set it near the tweet's reply count; that number is enforced as a hard cap. Payment settles before the draw runs, so pay only when you intend to run it; a failed draw does not auto-refund (contact support). Idempotency-Key header required — retries with the same key replay the original result instead of re-charging.

{
  "type": "object",
  "properties": {
    "tweetUrl": {
      "type": "string",
      "description": "Full tweet URL (https://x.com/user/status/ID)."
    },
    "winnerCount": {
      "type": "integer",
      "minimum": 1
    },
    "backupCount": {
      "type": "integer"
    },
    "uniqueAuthorsOnly": {
      "type": "boolean"
    },
    "mustRetweet": {
      "type": "boolean"
    },
    "mustFollowUsername": {
      "type": "string"
    },
    "filterMinFollowers": {
      "type": "integer"
    },
    "filterAccountAgeDays": {
      "type": "integer"
    },
    "filterLanguage": {
      "type": "string"
    },
    "requiredHashtags": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "requiredKeywords": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "requiredMentions": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "estimatedEntries": {
      "type": "integer",
      "minimum": 1,
      "maximum": 10000,
      "description": "Expected replies inspected — drives the fixed price (default 1000)."
    }
  },
  "required": [
    "tweetUrl"
  ]
}

Act on X/Twitter through an account you connect: post a tweet, reply, like, retweet, follow or unfollow, send a DM, delete a tweet, remove a follower, or upload media. Ownership is checked server-side — an agent can only write as a handle its own wallet connected. Guidance: PREREQUISITE: connect an X account first — POST /api/x-accounts/start (free, SIWX) with {username} only; it returns a one-time connect_url the USER opens in their own browser to sign in there. Never ask the user for their X password, email, or 2FA secret. Poll GET /api/x-accounts until the handle shows linked, then reference it in `account`. Actions: post (text) | reply (text + reply_to_tweet_id) | like|unlike|retweet|unretweet|delete_tweet (target_tweet_id) | follow|unfollow (target_user_id — the NUMERIC user id, get it from x_read get-user) | remove_follower (target_user_id of the follower) | send_dm (target_user_id + text) | upload_media (media_url → returns media_id). You can only write as a handle THIS wallet connected (checked server-side; the input account is not trusted). Payment settles before the action runs and is non-refundable; a write may return status=pending_confirmation with an actionId to poll — do NOT resend. Idempotency-Key header is required so a retry replays the original result instead of acting twice.

{
  "type": "object",
  "properties": {
    "action": {
      "type": "string",
      "enum": [
        "post",
        "reply",
        "like",
        "unlike",
        "retweet",
        "unretweet",
        "follow",
        "unfollow",
        "delete_tweet",
        "send_dm",
        "remove_follower",
        "upload_media"
      ],
      "description": "Which write to perform."
    },
    "account": {
      "type": "string",
      "description": "A connected X handle owned by this wallet (no @)."
    },
    "text": {
      "type": "string",
      "description": "post|reply|send_dm: the message body."
    },
    "reply_to_tweet_id": {
      "type": "string",
      "description": "reply: the tweet being replied to."
    },
    "target_tweet_id": {
      "type": "string",
      "description": "like|unlike|retweet|unretweet|delete_tweet: the target tweet ID."
    },
    "target_user_id": {
      "type": "string",
      "description": "follow|unfollow|send_dm|remove_follower: the numeric X user id of the target (not the @handle). Get it from x_read get-user."
    },
    "media_url": {
      "type": "string",
      "description": "upload_media: public URL of the file to upload; returns a media_id."
    },
    "media_ids": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "send_dm: optional uploaded media ids to attach."
    },
    "community_id": {
      "type": "string",
      "description": "post: optional community to post into."
    },
    "is_note_tweet": {
      "type": "boolean",
      "description": "post: long-form note tweet."
    }
  },
  "required": [
    "action",
    "account"
  ]
}

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. Guidance: PREREQUISITE: connect an X account (see /api/x-accounts/start). Reads act AS that account, so you can only read the inbox of a handle THIS wallet connected. action=bookmarks (optional folderId) | bookmark_folders | notifications (optional type) | dm_history (target_user_id required). bookmarks/notifications/dm_history are billed per item — set resultsLimit (1–10000). account (the connected handle) is required.

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

Edit a connected X/Twitter account's profile: display name, bio, location, website link, avatar image, and banner image. Acts only on handles this wallet connected. Guidance: PREREQUISITE: connect an X account. Acts as a handle THIS wallet owns. action=update_profile (any of name, description, location, url) | set_avatar (media_url) | set_banner (media_url). account required. Payment settles before the change; Idempotency-Key required.

{
  "type": "object",
  "properties": {
    "action": {
      "type": "string",
      "enum": [
        "update_profile",
        "set_avatar",
        "set_banner"
      ],
      "description": "Which profile edit to make."
    },
    "account": {
      "type": "string",
      "description": "A connected X handle owned by this wallet (no @)."
    },
    "name": {
      "type": "string",
      "description": "update_profile: new display name."
    },
    "description": {
      "type": "string",
      "description": "update_profile: new bio."
    },
    "location": {
      "type": "string",
      "description": "update_profile: new location."
    },
    "url": {
      "type": "string",
      "description": "update_profile: new website URL."
    },
    "media_url": {
      "type": "string",
      "description": "set_avatar|set_banner: public image URL."
    }
  },
  "required": [
    "action",
    "account"
  ]
}

Manage X/Twitter Communities as a connected account: create a new community, join or leave an existing one, or delete a community you own. Guidance: PREREQUISITE: connect an X account. Acts as a handle THIS wallet owns. action=create (name, optional description) | join|leave (community_id) | delete (community_id + community_name confirmation). account required. Payment settles before the action; Idempotency-Key required.

{
  "type": "object",
  "properties": {
    "action": {
      "type": "string",
      "enum": [
        "create",
        "join",
        "leave",
        "delete"
      ],
      "description": "Which community action."
    },
    "account": {
      "type": "string",
      "description": "A connected X handle owned by this wallet (no @)."
    },
    "name": {
      "type": "string",
      "description": "create: the community name."
    },
    "description": {
      "type": "string",
      "description": "create: optional community description."
    },
    "community_id": {
      "type": "string",
      "description": "join|leave|delete: the community ID."
    },
    "community_name": {
      "type": "string",
      "description": "delete: the community name, as confirmation."
    }
  },
  "required": [
    "action",
    "account"
  ]
}

Trending topics and breaking stories across tech, dev, science, business, culture, politics, and entertainment — aggregated from multiple public sources with regional and time-window filters. Flat sub-cent price per call; the cheap first stop for what is happening right now. Guidance: Optional filters: category, region, hours (lookback), limit, source. Use report.next_cursor via `after` for the next page. Flat floor price per call.

{
  "type": "object",
  "properties": {
    "category": {
      "type": "string",
      "enum": [
        "general",
        "tech",
        "dev",
        "science",
        "culture",
        "politics",
        "business",
        "entertainment"
      ],
      "description": "Topic category filter."
    },
    "region": {
      "type": "string"
    },
    "hours": {
      "type": "integer"
    },
    "limit": {
      "type": "integer"
    },
    "source": {
      "type": "string",
      "enum": [
        "github",
        "google_trends",
        "hacker_news",
        "polymarket",
        "reddit",
        "trustmrr",
        "wikipedia"
      ],
      "description": "Trend source filter."
    },
    "after": {
      "type": "string",
      "description": "Pagination cursor."
    }
  }
}

Draft tweets with AI: generate variants from a topic and goal, refine an existing draft, or score a draft for likely engagement — with tone, call-to-action, and style-matching options. Flat sub-cent price per step. Guidance: step=generate (topic + goal required; optional tone/styleUsername/additionalContext/callToAction/mediaType/hasLink/hasMedia), refine (draft required), or score (draft required). Returns text variants with scores and suggestions. Flat floor price per call.

{
  "type": "object",
  "properties": {
    "step": {
      "type": "string",
      "enum": [
        "generate",
        "refine",
        "score"
      ],
      "description": "Composer step."
    },
    "topic": {
      "type": "string"
    },
    "goal": {
      "type": "string"
    },
    "draft": {
      "type": "string"
    },
    "tone": {
      "type": "string"
    },
    "styleUsername": {
      "type": "string"
    },
    "additionalContext": {
      "type": "string"
    },
    "callToAction": {
      "type": "string"
    },
    "mediaType": {
      "type": "string"
    },
    "hasLink": {
      "type": "boolean"
    },
    "hasMedia": {
      "type": "boolean"
    }
  },
  "required": [
    "step"
  ]
}