API Docs

The TwitterViewer API reads public X (Twitter) content and returns it as clean Markdown, Obsidian notes, plain text, JSON or PDF. It is an independent service. It is not X's official API, it is not affiliated with X Corp., and you do not need an X developer account to use it. It cannot post, like, follow, send messages or read private accounts.

The base URL is https://twitterviewer.app. Endpoints live under /api/v1. Requests and responses are JSON in UTF-8 unless a section says otherwise. Every endpoint is billed in credits: 1 credit is 1 post returned.

Create a key on the API & credits page after signing in. The full key is shown once; only a hash is stored, so a lost key has to be replaced. Keys look like tv_live_ followed by 32 letters and digits. Send the key as a Bearer token:

Authorization: Bearer tv_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Calls are billed to the account that owns the key. Keep keys out of client-side code and public repositories; delete a key on the API page the moment it leaks. A request with no key or a wrong key gets 401 and costs nothing. Keys per account: Plus 2, Pro 5, Business 20, and 1 for a free account.

Turns an X link into a document. Send a post link to get the thread by the same author, a profile link to get recent posts. POST takes a JSON body; GET takes the same names as query parameters, which is handy with curl.

curl -X POST https://twitterviewer.app/api/v1/convert \
  -H "Authorization: Bearer $TWITTERVIEWER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://x.com/username/status/1234567890123456789", "scope": "thread", "format": "markdown", "stats": "root" }'

{
  "kind": "thread",
  "title": "How we shipped the new release:",
  "sourceUrl": "https://x.com/username/status/1234567890123456789",
  "author": { "handle": "username", "name": "Example", "followers": 1204 },
  "markdown": "# How we shipped the new release…",
  "text": "How we shipped the new release…",
  "posts": [ { "id": "1234567890123456789", "text": "…" } ],
  "replies": [],
  "postsReturned": 31,
  "wordCount": 2214,
  "credits": { "charged": 31, "remaining": 2969 }
}

curl "https://twitterviewer.app/api/v1/convert?url=https://x.com/username/status/1234567890123456789&format=obsidian" \
  -H "Authorization: Bearer $TWITTERVIEWER_API_KEY" \
  -H "Accept: text/markdown" -o thread.md

Replace x.com in a post or profile address with twitterviewer.app. When the request carries a valid key and an Accept header that does not ask for HTML, the response is the Markdown body, the same as convert. A browser that asks for HTML still gets the normal viewer page. Without a key the call returns 401 with a note on how to get one, and nothing is fetched from X.

The query parameters scope, format, stats and max work as in convert. ?thread=off is the same as scope=post.

# x.com/username/status/1234567890123456789 becomes:
curl -H "Authorization: Bearer $TWITTERVIEWER_API_KEY" \
  https://twitterviewer.app/username/status/1234567890123456789

# only the first post, as Obsidian Markdown
curl -H "Authorization: Bearer $TWITTERVIEWER_API_KEY" \
  "https://twitterviewer.app/username/status/1234567890123456789?scope=post&format=obsidian"

Searches public posts with X search operators such as from:, min_faves:, since: and lang:. X only serves search to signed-in users, so this endpoint is part of Pro and Business and needs an X account connected on the X account page. Other plans get 403 X_ACCOUNT_REQUIRED. Billed 1 credit per post returned.

curl "https://twitterviewer.app/api/v1/search?q=from%3Ausername%20min_faves%3A100&max=20" \
  -H "Authorization: Bearer $TWITTERVIEWER_API_KEY"

{
  "query": "from:username min_faves:100",
  "posts": [ { "id": "…", "text": "…" } ],
  "postsReturned": 20,
  "credits": { "charged": 20, "remaining": 2949 }
}

Returns the public replies under a post. The first page needs no X account; further pages are included when your plan and connected X account allow them, otherwise you get the first page. Billed 1 credit per reply returned.

curl "https://twitterviewer.app/api/v1/replies?url=https://x.com/username/status/1234567890123456789&max=30" \
  -H "Authorization: Bearer $TWITTERVIEWER_API_KEY"

{
  "sourceUrl": "https://x.com/username/status/1234567890123456789",
  "replies": [ { "id": "…", "text": "…" } ],
  "postsReturned": 30,
  "credits": { "charged": 30, "remaining": 2919 }
}

Returns what is trending in a region, cached for about 10 minutes. Billed 1 credit per call, however many trends come back.

curl "https://twitterviewer.app/api/v1/trends?region=united-states" \
  -H "Authorization: Bearer $TWITTERVIEWER_API_KEY"

{
  "region": "united-states",
  "trends": [ { "name": "…", "postCount": "…" } ],
  "credits": { "charged": 1, "remaining": 2918 }
}

Returns your balance split by source. It costs nothing and still counts toward the rate limit.

curl https://twitterviewer.app/api/v1/credits -H "Authorization: Bearer $TWITTERVIEWER_API_KEY"

{
  "total": 3050,
  "plan": { "remaining": 3000, "granted": 3000, "expiresAt": "2026-11-22T00:00:00.000Z" },
  "purchased": { "remaining": 50 }
}

plan is the monthly pool of your subscription and expiresAt is when it resets. purchased covers credit packs and the 50 sign-up credits, which never expire.

• 1 credit = 1 post returned. A quoted post counts as one more post. Author details are free.
• Replies, search results and conversation replies count the same way. Trends cost 1 credit per call.
• Failed calls are free: errors, empty results and PDF rendering failures are not charged.
• A call is refused with 402 when the balance is 0. If the balance is lower than the result, you get as many posts as the balance covers.
• Credits are spent from the pool that expires first: the monthly plan pool, then purchased credits.
• Every account gets 50 credits once, at sign-up. Plans add a monthly pool; credit packs (1,000 credits, 6,000 credits, 20,000 credits) are one-time and never expire.
• The same key asking for the same link with the same parameters within 10 minutes is not charged twice. On the website everyone gets 1 free conversion a day; the API always uses credits.

Requests are limited per account per minute. Every response carries x-ratelimit-remaining; credit-billed responses also carry x-credits-charged and x-credits-remaining. Past the limit you get 429 RATE_LIMITED with retryAfterSec.

Prices and credit packs are on the pricing page. Without an account, the website allows 3 views a day; the API always needs a key.

Errors use one shape: { "error": { "code", "message", "retryAfterSec?", "details?" } }, with the HTTP status in the table below.

HTTP/1.1 402 Payment Required

{
  "error": {
    "code": "LIMIT_REACHED",
    "message": "Not enough credits",
    "details": { "reason": "INSUFFICIENT_CREDITS", "required": 31, "balance": 12 }
  }
}

The remote MCP server at https://twitterviewer.app/mcp speaks Streamable HTTP. Sign in with your browser the first time a client connects, or send an API key as Authorization: Bearer. All tools are read-only and use the same credits as the REST API. The full guide is on the Twitter MCP Server page.

claude mcp add --transport http twitterviewer https://twitterviewer.app/mcp

{
  "mcpServers": {
    "twitterviewer": { "url": "https://twitterviewer.app/mcp" }
  }
}

[mcp_servers.twitterviewer]
url = "https://twitterviewer.app/mcp"

When credits run out, a tool answers with one line and a link to the pricing page instead of an error.

The twitterviewer package on npm wraps the API. It reads the key from TWITTERVIEWER_API_KEY first, then from the file twitterviewer login writes.

npx twitterviewer https://x.com/username/status/1234567890123456789 --scope thread --format obsidian -o thread.md

npx twitterviewer login      # opens your browser, approve the device code
npx twitterviewer credits    # prints your balance
npx twitterviewer logout     # removes the saved key

Exit codes: 0 ok, 1 error, 2 bad arguments, 3 sign-in or credits needed.

An Agent Skill teaches an agent what to do when it meets an X link: swap the domain, call the CLI or use the MCP tools. It is published at https://twitterviewer.app/.well-known/agent-skills/twitterviewer/SKILL.md. Point your agent at that address or copy the file into its skills folder.

The site also publishes /llms.txt for agents, and every page has a Markdown version at the same address plus .md.