# tweet.md > X (Twitter) posts as clean Markdown for LLMs, agents, and research. Swap `x.com` → `tweet.md` in any post URL, or call the conversion API. Responses are `text/markdown` only — JSON is intentionally rejected. Tweet.md calls the official X API and normalizes posts to LLM-ready Markdown with required attribution (author, timestamp, canonical permalink, capture timestamp, platform attribution). Use it in a browser, paste into chat assistants, or wire it into agents with an API key. **No-charge access:** controlled CTA demos. **Ongoing use:** prepaid packs, API keys, and profile sessions. ## Getting started - [Home](https://tweet.md/): Product overview, demo, agent skill, pricing, and FAQ - [Docs](https://tweet.md/i/docs): URL rewrite, agents, Apple Shortcuts, query params, output formats, profiles, X Articles, and pricing - [Guides](https://tweet.md/i/guides): Post, profile, Apple Shortcuts, and chatbot copy-paste workflows - [Apple Shortcuts guide](https://tweet.md/i/guides/save-x-threads-to-markdown-with-apple-shortcuts): Save X posts and threads as Markdown from Siri, the share sheet, or clipboard - [Fetch X profile as Markdown](https://tweet.md/i/guides/fetch-x-profile-as-markdown): Step-by-step profile URL swap guide - [Agent skill](https://tweet.md/i/skill.md): Full Cursor/agent skill markdown — fetch or install for LLM agents - [Top up credits](https://tweet.md/i/topup): Buy credit packs (Stripe Checkout) - [Login](https://tweet.md/i/login): Restore API key in browser via session cookie - [Dashboard](https://tweet.md/i/dashboard): API key, balance, and usage ## How it works ### URL rewrite (browser) Replace `x.com` or `twitter.com` with `tweet.md` in any post URL: ```text https://x.com/larsbuilds/status/2058910520800133391 → https://tweet.md/larsbuilds/status/2058910520800133391 ``` After checkout or login, the browser stores a session cookie — no `?apikey=` in shared links. ### Programmatic access | Goal | Method | |------|--------| | Know handle + post ID | `GET https://tweet.md/{handle}/status/{tweetId}` | | Have full X URL only | `GET https://tweet.md/i/api/convert?url={encoded_x_url}` | **Auth (paid):** `Authorization: Bearer twmd_key_…` or `?apikey=twmd_key_…` or session cookie after login/topup. **Examples (live Markdown responses):** - [Single post](https://tweet.md/larsbuilds/status/2058910520800133391?thread=off): Controlled default Markdown demo - [Reply chain, Obsidian format](https://tweet.md/larsbuilds/status/2076768374269292760?thread=ancestors&format=obsidian): Controlled vault-import demo - [Convert from X URL](https://tweet.md/i/api/convert?url=https%3A%2F%2Fx.com%2Flarsbuilds%2Fstatus%2F2058910520800133391): API demo when you only have the X link - [X Article example](https://tweet.md/larsbuilds/status/2075145371328627089): Controlled long-form article demo ## Query parameters Append to any `https://tweet.md/{handle}/status/{id}` URL or to `/i/api/convert?url=…` (plus the same params). | Param | Default | Values | |-------|---------|--------| | `format` | `markdown` | `markdown`, `obsidian` | | `thread` | `branch-5` | `off`, `ancestors[-N]`, `branch[-N]`, `all[-N]` (cap 2–500, default N=20) | | `userinfo` | `author` | `off`, `author`, `all` | | `stats` | `on` | `off`, `root`, `on` | | `metadata` | `on` | `on`, `off` | | `apikey` | — (use Bearer or cookie) | `twmd_key_…` | **Precedence:** URL param > [dashboard defaults](https://tweet.md/i/dashboard) > system defaults. - `thread=off` — single post only - `thread=ancestors-11` — opened post + up to 10 ancestors (cap includes requested post) - `thread=branch-8` — ancestors first, then replies underneath (context-first cap) - `thread=all-200` — opened post + 199 most recent other conversation posts (`sortOrder: recency`, rendered oldest-first) - Aliases: `full` → `branch-20`, `conversation` → `all-20`, bare `N` → `branch-N` - `userinfo=author` — rich author metadata for the root author only (flat +2 credits) - `userinfo=all` — rich author metadata for every author (+2 credits per unique author) **Response headers (agents):** `X-Tweetmd-Posts-Returned`, `X-Tweetmd-Credits-Charged`, plus `X-Tweetmd-Thread-Cap` / `X-Tweetmd-Cap-Hit` when threading is on and `X-Tweetmd-Credits-Would-Cost` on uncharged demo responses — never appended to the Markdown body. **Examples:** - [Single post demo](https://tweet.md/larsbuilds/status/2058910520800133391?thread=off) - [Ancestors + Obsidian demo](https://tweet.md/larsbuilds/status/2076768374269292760?thread=ancestors&format=obsidian) - [Convert API demo](https://tweet.md/i/api/convert?url=https%3A%2F%2Fx.com%2Flarsbuilds%2Fstatus%2F2058910520800133391&thread=off) ## Profile fetching Replace `x.com` with `tweet.md` in any profile URL to get bio, stats, pics, the pinned post, and a timeline of recent posts as clean Markdown. The controlled @larsbuilds profile is a no-charge demo; other profiles use purchased credits. **URL:** `GET https://tweet.md/{handle}` (replace `x.com/thepetermick` with `tweet.md/thepetermick`) **Programmatic:** `GET https://tweet.md/i/api/profile?handle=thepetermick` **Query params:** | Param | Default | Values | |-------|---------|--------| | `pinnedpost` | `on` | `on`, `off` | | `max` | `10` | `10`–`500` | | `replies` | `off` | `on`, `off` | | `retweets` | `off` | `on`, `off` | `max` is how many timeline posts come back, newest first. `replies` and `retweets` add the profile's replies and reposts to that same timeline; with both `off` you get original posts only. Every timeline entry says what it is in its heading: `# 📝 Post 3/15`, `# 💬 Reply 4/15 → @handle` (the account replied to), or `# 🔁 Repost 5/15 → @handle` (the account reposted). A repost renders the original post's text, byline, media, and stats — not the `RT @…` wrapper. Quote posts count as originals. **Pricing:** Base profile (name, bio, stats, pics) = 2 credits. Pinned post = 1 credit. Each timeline post returned = 1 credit. Default (pinned + 10 posts) = 13 credits; `max=50&replies=on&retweets=on` = 53 credits. Billing follows the posts actually returned, so a sparse timeline costs less than `max`. Guide: [Fetch X profile as Markdown](https://tweet.md/i/guides/fetch-x-profile-as-markdown). Reference: [docs — Profile fetching](https://tweet.md/i/docs#profile). ## Output formats - **markdown** (default): Readable notes with stats, media, quotes, and full X Articles when present. Best for agents, notes, and browsers. - **obsidian**: Vault import — YAML frontmatter (source, author, tags) plus headings per post in a thread. See [output formats](https://tweet.md/i/docs#output-formats) on the docs page. ## X Articles Long-form posts linked from a status URL are fetched automatically via the X API `article` field. Use the **status URL**, not `x.com/i/article/…` alone. The article renders content-first with its real structure (headings, quotes, lists, inline links/media, code, tables, embedded posts); no extra query param. Same credit as a regular post (1 credit per post returned). ## AI agents Install or fetch the [agent skill](https://tweet.md/i/skill.md) — plain Markdown at `/i/skill.md` with triggers, auth, query params, checkout links, and curl examples. The same skill is copyable from [Docs](https://tweet.md/i/docs) and the [homepage](https://tweet.md/). Give your agent a `twmd_key_…` (or send the user to checkout first). The skill instructs agents to rewrite `x.com` → `tweet.md` when fetching posts. **If the user has no API key**, link them to a checkout pack: - [Small — $5 / 200 credits](https://tweet.md/i/checkout?pack=small) - [Medium — $17 / 1,000 credits](https://tweet.md/i/checkout?pack=medium) - [Big — $42 / 3,000 credits](https://tweet.md/i/checkout?pack=big) Pattern: `GET https://tweet.md/i/checkout?pack=small|medium|big`. A signed-in profile or existing API-key session goes straight to Stripe as a top-up; new buyers are routed through profile login + onboarding with the chosen pack pre-selected. After payment, the browser session shows the generated API key (also in the [dashboard](https://tweet.md/i/dashboard)) and the order email contains a Stripe receipt plus an opaque, one-time profile-claim link. Raw API keys are never emailed. **Do not use for:** drafting tweets, engagement-only metrics, or JSON consumers (`format=json` is rejected). ## Apple Shortcuts Use Tweet.md from Apple Shortcuts to convert X/Twitter URLs into Markdown from Siri, the share sheet, or your clipboard. **Docs:** [Apple Shortcuts](https://tweet.md/i/docs#apple-shortcuts) **Install:** [tweet.md Apple Shortcut](https://tweet.md/i/shortcuts/apple) **Guide:** [Save X threads as Markdown with Apple Shortcuts](https://tweet.md/i/guides/save-x-threads-to-markdown-with-apple-shortcuts) **Shortcut HTTP action:** ```text GET https://tweet.md/i/api/convert?url={encoded_x_url}&thread=branch-20&format=markdown Authorization: Bearer twmd_key_… ``` The shared Shortcut must use the user's own API key. The key is stored in the user's local copy of the Shortcut; users should not share a customized Shortcut after adding their key. ## Pricing **Formula:** `credits = postCount + (userinfo = author ? 2 : userinfo = all ? uniqueAuthorCount × 2 : 0)` - **1 credit** per post returned, including quoted posts rendered with full post fields - **+2 credits** flat when `userinfo=author` (root author only); **+2 credits per unique author** when `userinfo=all` - Cache hits do **not** discount price — same request shape costs the same regardless of cache - Credits never expire ### Credit packs | Pack | Price (pre-tax) | Credits | Per credit | |------|-----------------|---------|------------| | Small | $5 | 200 | ~$0.0250 | | Medium | $17 | 1,000 | ~$0.0170 | | Big | $42 | 3,000 | ~$0.0140 | Prices exclude tax: any applicable sales tax, VAT, or GST is added on top at checkout, so the amount charged can exceed the pack price. Buy at [Top up](https://tweet.md/i/topup), or link directly to checkout: `/i/checkout?pack=small`, `/i/checkout?pack=medium`, or `/i/checkout?pack=big`. After payment, credits are granted via Stripe webhook. The browser shows the generated key; the email carries a receipt and recovery claim link, never the raw key. ### No-charge access - Controlled CTA post, thread, X Article, onboarding, and profile resources work anonymously - Purchased credits never expire On `402` (credits required or insufficient), send the user to checkout: `https://tweet.md/i/checkout?pack=big` (or `small` / `medium`). ## Errors Plain-text response body (not JSON): - `400` — bad input, unsupported param, or invalid URL - `401` — invalid or disabled API key - `402` — paid feature required or insufficient credits - `404` — post unavailable - `503` — upstream / X API unavailable ## Optional - [Terms of service](https://tweet.md/i/legal/terms) - [Privacy policy](https://tweet.md/i/legal/privacy) - [Acceptable use](https://tweet.md/i/legal/acceptable-use)