The Twitter API on this page is a pay-per-post way to read public X content from code. Send a post link, a thread link or a profile link to one endpoint and get the content back as clean Markdown, Obsidian notes, plain text, JSON or PDF. It is built for AI agents, research scripts and developers who want the words of a thread in a form a model or a notes app can use, without setting up an X developer account first.
It is an independent service. It is not X's official API and TwitterViewer is not affiliated with X Corp. It reads public posts only, so it cannot post, like, follow, send messages or open private accounts. This guide explains what the Twitter API does, how it differs from the official X API, how to make your first call, how credits work, which limits apply, and where the MCP server, the command-line tool and the Agent Skill fit in.
What is the Twitter API on this page?
The Twitter API here is a read-only HTTP API for public posts on X, the service that used to be called Twitter. You create an API key, send it as a Bearer token, and call endpoints under https://twitterviewer.app/api/v1. The core Twitter API endpoint is convert: give it an X link and it returns the post, the whole thread by the same author, or the recent posts of a profile.
What comes back is shaped for reuse. The Markdown version has a title, the author, the date of every post, the text, image links and the links the author shared. The JSON version carries the same content as structured data: one object per post with its id, text, date, media, counts and quoted post. Both versions come in one response, so a script can keep the structure and an agent can read the prose.
Every Twitter API call is billed in credits, and one credit is one post returned. Author details are free and a failed call costs nothing. A free account gets 50 credits once, the paid plans add a monthly pool of 3,000, 8,000 or 25,000 credits, and credit packs never expire. The full parameter list is in the API docs.
How is it different from the official X API?
The official X API is a separate product run by X. It needs a developer account, an app and a plan, and it is built around posting, accounts and permissions as much as reading. If you need to publish posts or act as a user, that is the right tool, and nothing on this page replaces it.
This Twitter API does one narrower job: it reads what anyone can already see on X and hands it back as a document. There is no developer account, no app review and no monthly minimum, because credits are the only unit you pay for. You do not give it your X password, cookies or tokens for the core endpoints. Search is the exception, because X only serves search to signed-in users; that endpoint belongs to Pro and Business and uses an X account you connect yourself.
Think of the Twitter API as a reading layer. When your goal is "get this thread into my notes", "feed these posts to a model" or "check what people replied", you want the content, not the whole social graph. The X to Markdown page does this job by hand in a browser; the Twitter API does it from code.
What can you read with the Twitter API?
Six endpoints cover reading, and all of them are read-only:
- Convert turns a post, a thread or a profile into Markdown, Obsidian, text, JSON or PDF. Use
scopeto choose one post, the author's thread, or the thread with the first page of replies. - Search runs X search operators such as
from:,since:andmin_faves:and returns public posts. Search is part of Pro and Business and needs a connected X account. The operators are the same as in Twitter Advanced Search, explained in the guide to X search operators. - Replies returns the public replies under a post, content that the Twitter Reply Viewer shows in a browser.
- Trends lists what is trending in a region such as worldwide, the United States, the United Kingdom, Japan, Saudi Arabia, India, Brazil or Germany.
- Credits returns your balance split by source and costs nothing.
- URL swap lets you replace
x.comwithtwitterviewer.appin a post address and get Markdown back when you send a key.
What the Twitter API cannot read is just as clear. Private accounts, protected posts, direct messages, deleted posts and suspended accounts are not available, because they are not public. Likes and bookmarks of other people are not available either.
Quick start: your first Twitter API call in three steps
- Create a free account and open the API page to create a key. It starts with
tv_live_and is shown once, so store it in an environment variable such asTWITTERVIEWER_API_KEY. - Call
convertwith a link. This example asks for a thread as Markdown:
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" }'
- Read the response headers.
x-credits-chargedtells you what the call cost,x-credits-remainingis what is left, andx-ratelimit-remainingis how many calls you have left this minute.
If you only want the document, add the header Accept: text/markdown and the body is the Markdown itself, ready to save to a file. The count of posts arrives in the x-posts-returned header.
The Twitter API convert endpoint in practice
convert has four options that matter. scope decides how much you get: post returns only the linked post, thread returns the author's connected posts in order, and conversation adds the first page of replies. format chooses the output: json is the default and returns everything, markdown and obsidian render the document, text strips formatting, and pdf returns a file.
stats controls the counts of likes, reposts and replies: all puts them on every post, root only on the first post, off drops them, which keeps the text lean for a model. For profile links, max sets how many recent posts to return, from 1 to 200, and replies and reposts decide whether those are included.
The JSON response uses fixed names in every call: kind, title, sourceUrl, author, markdown, text, posts, replies, postsReturned, wordCount and a credits object with what was charged and what remains. The title is the start of the first post, cut at a word boundary, so it is a usable file name or note title.
A few details save surprises. A quoted post counts as one more post. A key that asks again for one link with identical parameters within 10 minutes is not charged twice. And data is cached for a short time, around two minutes for a post and around ten minutes for a profile, so a call right after an edit may show the earlier text.
Twitter scraper API for AI agents and research
People search for a Twitter scraper when they need posts as data. A scraper you run yourself has to find a way past rate limits and layout changes, and it breaks when X changes a page. This Twitter API moves that work to a service: you call one endpoint and get public posts in a stable shape.
The most common uses are simple:
- Give a model a thread. Convert the link to Markdown and paste it into the context of ChatGPT, Claude or Gemini. Markdown keeps headings and links, uses fewer tokens than HTML and reads like the original.
- Build a notes archive. The
obsidianformat adds YAML frontmatter with the author, date and source, so a thread becomes a note in Obsidian or Notion. - Monitor a topic. Search with operators, convert the best hits and store the Markdown. Pair it with a schedule in your own tooling.
- Study replies. Pull the replies under a post and look for repeated questions or objections.
- Archive a thread as PDF.
format=pdfreturns a PDF on A4 or Letter for Pro and Business, with images and post links, a result matching Twitter Thread to PDF in the browser.
The Twitter API respects what is public: it returns what a visitor can see. The only features that use a signed-in X account are search and extra pages of replies, and those use an account you connect yourself. For reading a long thread by hand, the Twitter Thread Reader is the browser version.
Twitter API credits and pricing
Credits are the only unit. One credit is one post returned, whatever the endpoint. A thread of 31 posts costs 31 credits, a single post costs 1, a page of 20 replies costs 20, and a trends call costs 1. Author details are free, and calls that fail or return nothing are not charged.
| Source | Amount | Notes |
|---|---|---|
| Sign-up | 50 credits, once | Never expires |
| Plus | 3,000 credits a month | Resets each month |
| Pro | 8,000 credits a month | Resets each month, PDF and search included |
| Business | 25,000 credits a month | Resets each month, PDF and search included |
| Credit packs | 1,000 for $5, 6,000 for $20, 20,000 for $50 | One-time, never expire |
Credits are spent from the pool that expires first, so the monthly pool goes before purchased credits. At the lowest price the cost works out to about $0.002 a post on the Business plan and $0.005 a post on the smallest pack. Plans and prices are on the pricing page.
If a call would cost more than you have, it is refused with a 402 when the balance is zero, and when the balance is lower than the result you get as many posts as it covers. The balance endpoint shows how many credits you have left and when the monthly pool resets.
Twitter API rate limits, errors and caching
Twitter API requests are limited per account per minute: 10 on a free account, 30 on Plus, 60 on Pro and 300 on Business. Past the limit the API answers 429 with a retryAfterSec value and a Retry-After header. An account can hold 1 key if it is free, 2 on Plus, 5 on Pro and 20 on Business.
Errors always share one shape: an error object with a code, a message and sometimes details. A missing or wrong key returns 401 and nothing is fetched. A balance that is too low returns 402 with the reason INSUFFICIENT_CREDITS and how many credits were needed. A protected account returns 403, a deleted post 404, a suspended account 410, and a failure on the data side 502, which is not charged and can be retried. The full list is in the API docs.
Responses are never stored in shared caches, because they depend on your key. The service itself caches X data briefly so repeated reads are fast and consistent.
MCP server, CLI and Agent Skill
The Twitter API is one of four ways in, and they all draw on one credit balance.
- MCP server. A remote server at
https://twitterviewer.app/mcplets Claude, Cursor and Codex read X directly. It has five read-only tools. See the Twitter MCP Server page for setup. - Command-line tool.
npx twitterviewer <link>converts a link from a terminal and can save the result to a file.twitterviewer loginsigns you in through the browser andtwitterviewer creditsprints your balance. - Agent Skill. A skill file at
/.well-known/agent-skills/twitterviewer/SKILL.mdtells an agent what to do when it meets an X link. - Domain swap. The simplest option: change the domain of a link and send your key.
For agents the order of preference is usually the swap or the MCP tool, because they need no code. For pipelines, use the Twitter API directly.
Twitter API alternative: when does this fit?
Look at this service as a Twitter API alternative when your job is reading public content and you do not want to manage a developer account. It fits notes tools, research, summarising threads, feeding a language model and archiving posts. It fits less well when you need to publish, to act as a user, to read private content, or to stream every new post in real time. Those jobs need the official API and your own authorisation.
Some honest Twitter API limits to plan around. Data is public and slightly cached. Search needs Pro or Business plus a connected X account, because X only shows search to signed-in users. Some X features, such as X Articles, polls and link cards, are not converted yet; an article is returned as the post that shares it. TwitterViewer is an independent service, and X and Twitter are trademarks of their owners.
If you want to try the Twitter API first, create a free account, use the 50 credits on a few threads and look at the output. For one-off needs, the X to Markdown page needs no code, and the profile viewer shows an account before you convert it.
Twitter API FAQs
What is the Twitter API on TwitterViewer?
It is an independent, read-only API for public X content. You send a link to a post, thread or profile and receive Markdown, Obsidian, text, JSON or PDF. It is billed in credits, one credit per post returned, and it is not X's official API.
Is this the official X API?
No. The official X API is a separate product from X that needs a developer account and a plan. This API reads public posts only and has no connection to X Corp. It cannot post, like, follow or send messages.
Do I need an X developer account?
No. You need a TwitterViewer account and an API key. The core endpoints do not ask for your X login. Search is the one exception: X only serves search to signed-in users, so it is part of Pro and Business and uses an X account you connect yourself.
How much does the Twitter API cost?
One credit buys one post. A free account gets 50 credits once, Plus includes 3,000 credits a month, Pro 8,000 and Business 25,000. Credit packs cost $5 for 1,000, $20 for 6,000 and $50 for 20,000, and they never expire. The lowest price is about $0.002 a post.
Which formats does the Twitter API return?
json by default, plus markdown, obsidian, text and pdf. The JSON response always includes both the rendered Markdown and the structured posts. PDF output is part of Pro and Business and can be A4 or Letter.
Can it work as a Twitter scraper API?
Yes, for public posts. It returns posts anyone can see, in a stable format, so you do not run a scraper yourself. It does not return private accounts, protected posts, direct messages or anything X hides from logged-out visitors.
How do I convert a whole thread?
Send the link of any post in the thread to convert with scope set to thread. You get the author's connected posts in order. Use scope=conversation to add the first page of replies, or scope=post for the single post.
What happens when I run out of credits?
A call with a balance of zero is refused with a 402 and nothing is fetched from X. If you have some credits but fewer than the result needs, you get as many posts as your balance covers. Buy a credit pack or wait for your monthly pool to reset.
Are there rate limits?
Yes, per account per minute: 10 on a free account, 30 on Plus, 60 on Pro and 300 on Business. Each response shows how many calls remain in the header x-ratelimit-remaining.
Can I use it with Claude, Cursor or Codex?
Yes. The remote MCP server at https://twitterviewer.app/mcp works with Claude, Claude Code, Cursor and Codex, and credits apply as usual. The Twitter MCP Server page has the configuration for each client.