NewX profiles as Markdown
tweet.md logotweet.md

X/Twitter to Markdown API documentation

Posts, threads, profiles, and X Articles via URL rewrite or API—with query parameters, agents, Shortcuts, formats, authentication, and pricing.

New here? Start with the full X/Twitter thread-to-Markdown guide, the X profile-to-Markdown guide, or all X/Twitter-to-Markdown workflows.

Try a no-charge demo

Simply replace x.com with tweet.md in any Tweet URL.

x.comtweet.md/*t-twmduser/status/*-t-thread-3?thread=ancestors
01

X Post as Markdown

Swap x.com → tweet.md in the address bar to convert a single post or thread. You get clean Markdown — plain text, never JSON. Append query params to customize the response.

https://x.com/*t-twmduser/status/*-t-post
→ https://tweet.md/*t-twmduser/status/*-t-post
Example response
# X Post by Lars (@*t-twmduser)

Post ID: *-t-post
Source: https://x.com/*t-twmduser/status/*-t-post
Reply to: none

Captured: 2026-07-14T00:00:00.000Z

Stats:
- Replies: 5
- Reposts: 2
- Quotes: 2
- Likes: 32
- Bookmarks: 2
- Impressions: 3,401

Text:

> new week!
>
> here’s what I shipped this weekend

Query params

ParamDefaultValuesDescription
formatmarkdownmarkdown, obsidianOutput format.
threadbranch-15off, ancestors[-N], branch[-N], all[-N]How much of the conversation to include — see thread scopes below. 1 credit per post returned.
userinfoauthoroff, author, allRich author metadata (bio, metrics, avatar). author covers the root author only (+2 credits); all covers every author (+2 credits per unique author).
statsonoff, root, onEngagement stats (replies, reposts, likes, …) per post. root keeps them on the topmost post only; off removes them everywhere.
metadataonon, offTrailing Thread Metadata and Article Metadata sections. off drops them for pure content.
apikey—twmd_key_…Authenticates paid requests. Prefer Bearer header or session cookie.
url—encoded X URLRequired on /i/api/convert only — when you don’t have handle + ID in the path.

The controlled demos work without a profile. Verified profiles and customers who omit a param get their saved defaults. URL params always win.

Thread scopes

thread controls how much of the conversation comes back with the post in your URL — “your post” below. Each diagram shows the same conversation; filled dots are the posts included in the response.

thread=offone post

The linked post only. Nothing else is fetched.

thread=ancestors

Your post plus the reply chain above it, up to the conversation root.

thread=branch-15Default

Ancestors plus every reply underneath your post; sibling branches are excluded. Fills upward first — the chain above your post up to the root — then replies below with the remaining budget. Paid requests that omit thread get branch-15.

thread=all

The whole conversation, sibling branches included.

Add -N to cap total posts returned, your post included (2–500, default 20) — e.g. thread=branch-8. Omitting thread entirely uses branch-15. Under a cap, branch reads upward first — with 12 posts above yours it spends 13 of 15 on the chain up, leaving 2 for replies below, no matter how many replies exist. full and conversation are accepted as aliases for branch and all.

Examples

# No-charge controlled demo
https://tweet.md/*t-twmduser/status/*-t-post?thread=off&userinfo=off
Example response
# X Post by Lars (@*t-twmduser)

Post ID: *-t-post
Source: https://x.com/*t-twmduser/status/*-t-post
Reply to: none

Captured: 2026-05-17T00:00:00.000Z

Stats:
- Replies: 5
- Reposts: 2
- Quotes: 2
- Likes: 32
- Bookmarks: 2
- Impressions: 3,401

Text:

> new week!
>
> here’s what I shipped this weekend

# thread=ancestors — the reply chain above
https://tweet.md/*t-twmduser/status/*-t-thread-3?thread=ancestors

Response shortened for illustration.

Example response
# 1/2 — Post by Example Account (@exampleuser)

Post ID: 9000000000000000001
Source: https://x.com/exampleuser/status/9000000000000000001
Reply to: none

Stats:
- Replies: 8
- Reposts: 42
- Quotes: 3
- Likes: 610
- Bookmarks: 54
- Impressions: 92,000

Text:

> Shipping notes: what changed in this release and why.

# 2/2 — Post by Example Account (@exampleuser)

Post ID: 9000000000000000002
Source: https://x.com/exampleuser/status/9000000000000000002
Reply to: https://x.com/exampleuser/status/9000000000000000001

Stats:
- Replies: 2
- Reposts: 9
- Quotes: 1
- Likes: 88
- Bookmarks: 12
- Impressions: 18,000

Text:

> Full changelog and migration notes are linked below.

# Thread Metadata

Original post: https://x.com/exampleuser/status/9000000000000000001
Captured: 2026-05-17T00:00:00.000Z
Order: original-post-first
Posts: 2
Root author: Example Account (@exampleuser)

# thread=branch-8 — ancestors plus replies below
https://tweet.md/*t-twmduser/status/*-t-post?thread=branch-8

Response shortened for illustration.

Example response
# 1/3 — Post by Example Account (@exampleuser)

Post ID: 9000000000000000001
Source: https://x.com/exampleuser/status/9000000000000000001
Reply to: none

Stats:
- Replies: 8
- Reposts: 42
- Quotes: 3
- Likes: 610
- Bookmarks: 54
- Impressions: 92,000

Text:

> Shipping notes: what changed in this release and why.

# 2/3 — Post by Example Account (@exampleuser)

Post ID: 9000000000000000002
Source: https://x.com/exampleuser/status/9000000000000000002
Reply to: https://x.com/exampleuser/status/9000000000000000001

Stats:
- Replies: 2
- Reposts: 9
- Quotes: 1
- Likes: 88
- Bookmarks: 12
- Impressions: 18,000

Text:

> Full changelog and migration notes are linked below.

# 3/3 — Post by Sample Dev (@sampledev)

Post ID: 9000000000000000004
Source: https://x.com/sampledev/status/9000000000000000004
Reply to: https://x.com/exampleuser/status/9000000000000000002

Stats:
- Replies: 1
- Reposts: 0
- Quotes: 0
- Likes: 6
- Bookmarks: 0
- Impressions: 1,900

Text:

> Does this release change the v1 API endpoints?

# Thread Metadata

Original post: https://x.com/exampleuser/status/9000000000000000001
Captured: 2026-05-17T00:00:00.000Z
Order: original-post-first
Posts: 3
Root author: Example Account (@exampleuser)

# thread=all — the whole conversation
https://tweet.md/*t-twmduser/status/*-t-post?thread=all

Response shortened for illustration.

Example response
# 1/4 — Post by Example Account (@exampleuser)

Post ID: 9000000000000000001
Source: https://x.com/exampleuser/status/9000000000000000001
Reply to: none

Stats:
- Replies: 8
- Reposts: 42
- Quotes: 3
- Likes: 610
- Bookmarks: 54
- Impressions: 92,000

Text:

> Shipping notes: what changed in this release and why.

# 2/4 — Post by Example Account (@exampleuser)

Post ID: 9000000000000000002
Source: https://x.com/exampleuser/status/9000000000000000002
Reply to: https://x.com/exampleuser/status/9000000000000000001

Stats:
- Replies: 2
- Reposts: 9
- Quotes: 1
- Likes: 88
- Bookmarks: 12
- Impressions: 18,000

Text:

> Full changelog and migration notes are linked below.

# 3/4 — Post by Demo Reader (@demoreader)

Post ID: 9000000000000000003
Source: https://x.com/demoreader/status/9000000000000000003
Reply to: https://x.com/exampleuser/status/9000000000000000001

Stats:
- Replies: 0
- Reposts: 1
- Quotes: 0
- Likes: 14
- Bookmarks: 1
- Impressions: 2,400

Text:

> Congrats on the release — the migration notes were exactly what we needed.

# 4/4 — Post by Sample Dev (@sampledev)

Post ID: 9000000000000000004
Source: https://x.com/sampledev/status/9000000000000000004
Reply to: https://x.com/exampleuser/status/9000000000000000002

Stats:
- Replies: 1
- Reposts: 0
- Quotes: 0
- Likes: 6
- Bookmarks: 0
- Impressions: 1,900

Text:

> Does this release change the v1 API endpoints?

# Thread Metadata

Original post: https://x.com/exampleuser/status/9000000000000000001
Captured: 2026-05-17T00:00:00.000Z
Order: original-post-first
Posts: 4
Root author: Example Account (@exampleuser)

# stats=off — content only, no engagement stats
https://tweet.md/*t-twmduser/status/*-t-post?stats=off
Example response
# X Post by Lars (@*t-twmduser)

Post ID: *-t-post
Source: https://x.com/*t-twmduser/status/*-t-post
Reply to: none

Captured: 2026-05-17T00:00:00.000Z

Text:

> new week!
>
> here’s what I shipped this weekend

# stats=root — stats on the topmost post only
https://tweet.md/*t-twmduser/status/*-t-post?thread=branch-8&stats=root

Response shortened for illustration.

Example response
# 1/3 — Post by Example Account (@exampleuser)

Post ID: 9000000000000000001
Source: https://x.com/exampleuser/status/9000000000000000001
Reply to: none

Stats:
- Replies: 8
- Reposts: 42
- Quotes: 3
- Likes: 610
- Bookmarks: 54
- Impressions: 92,000

Text:

> Shipping notes: what changed in this release and why.

# 2/3 — Post by Example Account (@exampleuser)

Post ID: 9000000000000000002
Source: https://x.com/exampleuser/status/9000000000000000002
Reply to: https://x.com/exampleuser/status/9000000000000000001

Text:

> Full changelog and migration notes are linked below.

# 3/3 — Post by Sample Dev (@sampledev)

Post ID: 9000000000000000004
Source: https://x.com/sampledev/status/9000000000000000004
Reply to: https://x.com/exampleuser/status/9000000000000000002

Text:

> Does this release change the v1 API endpoints?

# Thread Metadata

Original post: https://x.com/exampleuser/status/9000000000000000001
Captured: 2026-05-17T00:00:00.000Z
Order: original-post-first
Posts: 3
Root author: Example Account (@exampleuser)

# metadata=off — no trailing Thread/Article Metadata sections
https://tweet.md/*t-twmduser/status/*-t-post?thread=branch-8&metadata=off

Response shortened for illustration.

Example response
# 1/3 — Post by Example Account (@exampleuser)

Post ID: 9000000000000000001
Source: https://x.com/exampleuser/status/9000000000000000001
Reply to: none

Stats:
- Replies: 8
- Reposts: 42
- Quotes: 3
- Likes: 610
- Bookmarks: 54
- Impressions: 92,000

Text:

> Shipping notes: what changed in this release and why.

# 2/3 — Post by Example Account (@exampleuser)

Post ID: 9000000000000000002
Source: https://x.com/exampleuser/status/9000000000000000002
Reply to: https://x.com/exampleuser/status/9000000000000000001

Stats:
- Replies: 2
- Reposts: 9
- Quotes: 1
- Likes: 88
- Bookmarks: 12
- Impressions: 18,000

Text:

> Full changelog and migration notes are linked below.

# 3/3 — Post by Sample Dev (@sampledev)

Post ID: 9000000000000000004
Source: https://x.com/sampledev/status/9000000000000000004
Reply to: https://x.com/exampleuser/status/9000000000000000002

Stats:
- Replies: 1
- Reposts: 0
- Quotes: 0
- Likes: 6
- Bookmarks: 0
- Impressions: 1,900

Text:

> Does this release change the v1 API endpoints?

curl -H "Authorization: Bearer twmd_key_…" \
  "https://tweet.md/i/api/convert?url=https%3A%2F%2Fx.com%2F*t-twmduser%2Fstatus%2F*-t-post&thread=branch-8"

Responses include X-Tweetmd-Posts-Returned, X-Tweetmd-Credits-Charged, and X-Tweetmd-Cap-Hit headers for transparency.

Paid use in the same browser uses a session cookie after checkout or login — see authentication.

02

X Profile as Markdown

Swap x.com → tweet.md in any profile URL. Returns Markdown with bio, stats, and content sections. Requires credits.

https://x.com/*t-twmduser
→ https://tweet.md/*t-twmduser

# or via API
tweet.md/i/api/profile?handle=*t-twmduser

Response shortened for illustration.

Example response
# @exampleuser (Example Account)

**Bio:** Notes on building and shipping software.

**Stats:**
- Following: 210
- Followers: 4,800
- Posts: 1,320
- Joined: January 2020

**Links:**
- [x.com](https://x.com/exampleuser)
- Location: Internet

![Profile Picture](https://pbs.twimg.com/profile_images/example/avatar.jpg)

---

Query params

ParamDefaultValuesDescription
handlepath segment@handle or handleX profile to fetch. Also available as /i/api/profile?handle=…
formatmarkdownmarkdown, obsidianOutput format.
pinnedpostonon, offInclude pinned post when present (+1 credit).
latest5off, 5–50Recent original posts. Minimum 5 when enabled.
repliesoffoff, 5–20Recent replies. Minimum 5 when enabled.
articlesoffoff, 5–20X Articles. Minimum 5 when enabled.
metadataonon, offProfile stats, links, and images. off keeps just the name, bio, and content sections.

Pricing: 2 credits for the base profile, +1 per post returned, +1 for pinned post when present.

Step-by-step walkthrough: How to fetch an X profile as Markdown.

03

AI agents

Give your agent the skill below and your API key — see authentication. It should rewrite x.com → tweet.md when fetching posts. Install via skills.sh or copy the skill markdown directly.

SKILL.md

npx skills add tweet-md/skill
GET https://tweet.md/i/api/convert?url=https%3A%2F%2Fx.com%2F*t-twmduser%2Fstatus%2F*-t-post

Full URL only? Call /i/api/convert with the target X URL.

04

Apple Shortcuts

Install the prebuilt Shortcut, paste your twmd_key_… once, then share or copy an X URL and run it from Siri or the share sheet. The Shortcut just swaps x.com → tweet.md, sends the key as x-ios-apikey (see authentication), and copies the returned Markdown to your clipboard.

Install the ShortcutRead the guideGet API key

Your API key is stored only in your local copy of the Shortcut. Do not share your customized Shortcut after adding a key. The prebuilt Shortcut uses Shortcuts’ Get Contents of URL action and asks for your key during setup.

HTTP action

GET https://tweet.md/*t-twmduser/status/*-t-post
x-ios-apikey: twmd_key_…

In Shortcuts: accept Share Sheet input, fall back to Clipboard, replace x.com with tweet.md in the URL, call it with x-ios-apikey, then copy the returned Markdown to the clipboard. iOS-key requests return text/html with line breaks converted to <br> so Shortcuts can copy the full markdown properly.

05

Output formats

Append ?format= to any post (tweet.md/…/status/…), profile (tweet.md/handle), or /i/api/convert?url=… / /i/api/profile?handle=… request. Omit it for markdown.

For a complete vault workflow, follow the guide to saving X posts and threads in Obsidian.

formatWhen to use
markdowndefaultDefault — readable notes with stats, media, quotes, and full X Articles when present.
obsidianVault import: YAML frontmatter (source, author, bio, stats, tags) for posts, threads, and profiles.
https://tweet.md/*t-twmduser/status/*-t-post

markdown — default, for agents, notes, and browsers.

Example response
# X Post by Lars (@*t-twmduser)

Post ID: *-t-post
Source: https://x.com/*t-twmduser/status/*-t-post
Reply to: none

Captured: 2026-07-14T00:00:00.000Z

Stats:
- Replies: 5
- Reposts: 2
- Quotes: 2
- Likes: 32
- Bookmarks: 2
- Impressions: 3,401

Text:

> new week!
>
> here’s what I shipped this weekend

https://tweet.md/*t-twmduser/status/*-t-post?format=obsidian

obsidian — YAML frontmatter for vault import (post).

Example response
---
source: https://x.com/*t-twmduser/status/*-t-post
author: "Lars"
author_handle: *t-twmduser
posted: 2026-05-25T13:58:15.000Z
captured: 2026-05-17T00:00:00.000Z
tags: [x-post, tweetmd]
---

# X Post — Lars — 2026-05-25

Post ID: *-t-post
Source: https://x.com/*t-twmduser/status/*-t-post
Reply to: none

Stats:
- Replies: 5
- Reposts: 2
- Quotes: 2
- Likes: 32
- Bookmarks: 2
- Impressions: 3,401

Text:

> new week!
>
> here’s what I shipped this weekend

https://tweet.md/*t-twmduser?format=obsidian

obsidian — same format on profiles.

Example response
---
source: https://x.com/exampleuser
author: "Example Account"
author_handle: exampleuser
captured: 2026-05-17T00:00:00.000Z
bio: "Notes on building and shipping software."
stats:
  following: 210
  followers: 4800
  posts: 1320
  joined: "January 2020"
tags: [x-profile, tweetmd]
---

# X Profile — Example Account

**Bio:** Notes on building and shipping software.

**Stats:**
- Following: 210
- Followers: 4,800
- Posts: 1,320
- Joined: January 2020

**Links:**
- [x.com](https://x.com/exampleuser)
- Location: Internet

![Profile Picture](https://pbs.twimg.com/profile_images/example/avatar.jpg)

---

Inline media in post text is rewritten to Markdown using public preview URLs from X — photos as images, videos and GIFs as labeled links to their preview JPEG.

Text:

> ![image](https://pbs.twimg.com/media/HJJrdtlWkAAiNAQ.jpg)

> [video](https://pbs.twimg.com/tweet_video_thumb/abc123.jpg)

> [animated_gif](https://pbs.twimg.com/tweet_video_thumb/HI6NThtWMAEYPhf.jpg)
06

X Articles

Long-form article posts use the normal status URL — tweet.md pulls the full article body automatically. Same credit as a regular post.

https://x.com/*t-twmduser/status/*-t-article
→ https://tweet.md/*t-twmduser/status/*-t-article

Response shortened for illustration.

Example response
# tweet.md test article

![Cover image](https://pbs.twimg.com/media/HMxjPO7X0AAs7OD.jpg)

This is just a little test article for [tweet.md](https://tweet.md) don't mind me!

But go **checkout** tweet.md :D

## Heading

### Subheading

## I – Test

### II - Test

Body

**BOLD**

*ITALIC*

~~STRIKETROUGH~~

> This is a quote
>
> with multiple lines
>
> – Someone

- Here we have
- a bullet point list
1. and a numbered
2. list too!

This is a [Link](https://tweet.md?link=1) and another [Link](https://tweet.md?link=2)

😅🤣🤝😆😱🙌🚀

![This is an alt text!](https://pbs.twimg.com/media/HMxuoitWoAA8J5x.jpg) — "Image caption"

![Article image](https://pbs.twimg.com/media/HMxkZMfXcAAfnaM.jpg) — "Same image as first one but uploaded again"

Text between images

another image:

![Article image](https://pbs.twimg.com/media/HMxmGYpWIAA-yAh.jpg)

Some gif:

[gif](https://video.twimg.com/tweet_video/HMxknYyW0AAYXsF.mp4)

Video:

[video](https://video.twimg.com/amplify_video/2075144856125497344/vid/avc1/1920x1080/p_3V4WUKerfJdmPY.mp4?tag=28)

A divider:

---

Some code:

```python
print("Hello world")
```

Latex:

$$E = mc^2$$

Table:

| Table Header 1  | Header 2   | Header 3   | Header 4   |
| --- | --- | --- | --- |
|  Stuff  | stufff   | stuff   | stuff   |
|  Stuff  | stufff   | stuff   | stuff   |
|  Stuff  | stufff   | stuff   | stuff   |

a X post:

Embedded post:

Author: Lars (@*t-twmduser)
Post ID: *-t-post
Source: https://x.com/*t-twmduser/status/*-t-post
Reply to: none

Stats:
- Replies: 5
- Reposts: 2
- Quotes: 2
- Likes: 32
- Bookmarks: 2
- Impressions: 3,401

Text:

> new week!
>
> here’s what I shipped this weekend [video](https://video.twimg.com/amplify_video/2058910469214404608/vid/avc1/1280x720/mN6Tp909xoZWDpdf.mp4?tag=14)

Media:
- video: https://video.twimg.com/amplify_video/2058910469214404608/vid/avc1/1280x720/mN6Tp909xoZWDpdf.mp4?tag=14

# Article Metadata

Author: Lars (@*t-twmduser)
Post ID: *-t-article
Source: https://x.com/*t-twmduser/status/*-t-article
Article: https://x.com/i/article/2075141930652962816
Published: 2026-07-09T09:09:45.000Z
Captured: 2026-07-09T00:00:00.000Z

Stats:
- Replies: 0
- Reposts: 0
- Quotes: 0
- Likes: 0
- Bookmarks: 0
- Impressions: 19

Use the status permalink, not x.com/i/article/… alone. The article renders content-first: its title is the document heading and the body keeps its real heading hierarchy, cover image, bold/italic text, quotes, lists, inline links, inline images and video with captions, code blocks, tables, and embedded posts — all at their in-article positions. Author, stats, and source URLs follow in a trailing Article Metadata section — articles inside threads get the same section nested under their title — or move into YAML frontmatter with format=obsidian. Its stats respect stats, and metadata=off drops the whole section, leaving pure article content.

Want the task-focused walkthrough and a complete output example? Read the X Article-to-Markdown guide.

07

Authentication

Paid requests need an API key from the dashboardor a trusted IP.

Send the key one of four ways:

MethodWhen to use
Authorization: Bearer twmd_key_…Scripts, agents, and servers (recommended).
x-ios-apikey: twmd_key_…Apple Shortcuts — returns text/html with line breaks as <br> for iOS compatibility.
?apikey=twmd_key_…Quick manual tests. Avoid sharing URLs that contain it.
Session cookieBrowsers — set automatically after checkout or login.
Trusted IPPublic server IPs — set up in the dashboard.

Trusted IPs

beta

Trusted IPs let fixed servers spend credits without sending an API key. Add up to 5 plain IPv4 or IPv6 addresses per API key from the dashboard. CIDR ranges are not supported yet.

Security model: anyone who can send requests from a trusted IP can spend that key’s credits. Use stable server IPs, remove stale dynamic IPs, and keep your normal API key secret.

Precedence: if a request also includes an Authorization: Bearer twmd_key_… header, x-ios-apikey, ?apikey=, or the session cookie, that API key wins over IP auth.

# After whitelisting your server IP
curl "https://tweet.md/i/api/convert?url=https%3A%2F%2Fx.com%2F*t-twmduser%2Fstatus%2F*-t-post&thread=branch-8"
08

Pricing

Pricing

1 credit per post returned, including quoted posts and article-embedded posts rendered with full post fields. Author metadata adds 2 credits per unique author.

1 credit per post. Author metadata adds 2 credits per unique author. Controlled demos are no-charge; create a profile to convert your own content.