# Twitter API: 공개 X 게시물을 Markdown으로 읽기 공개 X 콘텐츠를 읽는 독립 Twitter API입니다. 게시물 링크를 보내고 스레드를 Markdown이나 JSON으로 받으세요. 무료 크레딧 50개 제공 후 게시물당 과금됩니다. Page: https://twitterviewer.app/ko/twitter-api 공개 X 게시물, 전체 스레드, 프로필을 깔끔한 Markdown이나 JSON으로 읽으세요. 공개 콘텐츠를 위한 독립 API로, X 개발자 계정이나 월 최소 이용 금액이 필요 없습니다. TwitterViewer는 독립 서비스입니다. X의 공식 API가 아니며 X Corp.와 제휴 관계가 없습니다. 공개 게시물만 읽을 수 있으며 게시, 좋아요, 팔로우, 메시지 전송, 비공개 계정 조회는 할 수 없습니다. ## Endpoints | Method | Path | What it does | | --- | --- | --- | | POST | /api/v1/convert | 게시물, 전체 스레드 또는 프로필의 최근 게시물을 Markdown, Obsidian, 텍스트, JSON 또는 PDF로 변환 | | GET | /api/v1/search | X 검색 연산자로 공개 게시물 검색(Pro 및 Business) | | GET | /api/v1/replies | 게시물에 달린 공개 답글 조회 | | GET | /api/v1/trends | 지역별 실시간 트렌드 조회 | | GET | /{handle}/status/{id} | URL 바꾸기: X 링크의 도메인을 바꾸고 키를 보내면 Markdown 반환 | | GET | /api/v1/credits | 요금제 크레딧과 구매 크레딧의 잔액을 각각 조회 | | MCP | /mcp | Claude, Cursor, Codex용 convert_x_url, search_x_posts, get_x_replies, get_x_trends, get_credits | ## Example ```bash curl 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" }' # or just swap the domain curl -H "Authorization: Bearer $TWITTERVIEWER_API_KEY" \ https://twitterviewer.app/username/status/1234567890123456789 ``` ```json { "kind": "thread", "title": "How we shipped the new release:", "sourceUrl": "https://x.com/username/status/1234567890123456789", "author": { "handle": "username", "name": "Example", "followers": 1204 }, "postsReturned": 31, "wordCount": 2214, "markdown": "# How we shipped the new release…\n\nThread by @username…", "text": "How we shipped the new release…", "posts": [ { "id": "1234567890123456789", "text": "…" }, … ], "replies": [], "credits": { "charged": 31, "remaining": 2969 } } ``` ## Pricing 가입 시 무료 크레딧 50개 · 이후 게시물당 $0.002부터. - Requests per minute: Free 10, Plus 30, Pro 60, Business 300. API keys per account: Free 1, Plus 2, Pro 5, Business 20. Monthly credits: Plus 3,000, Pro 8,000, Business 25,000 (yearly plans get 12 months of credits at once); every account also gets 50 credits once at sign-up. PDF output (format=pdf) is part of Pro and Business. - Credit packs: 1,000 credits for $5, 6,000 credits for $20, 20,000 credits for $50, one-time, never expire. 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](https://twitterviewer.app/docs/api). ## 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](https://twitterviewer.app/ko/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 `scope` to 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:` and `min_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](https://twitterviewer.app/ko/twitter-advanced-search), explained in the guide to [X search operators](https://twitterviewer.app/ko/blog/x-advanced-search-operators). - **Replies** returns the public replies under a post, content that the [Twitter Reply Viewer](https://twitterviewer.app/ko/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.com` with `twitterviewer.app` in 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 1. 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 as `TWITTERVIEWER_API_KEY`. 2. Call `convert` with a link. This example asks for a thread as Markdown: ```bash 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" }' ``` 3. Read the response headers. `x-credits-charged` tells you what the call cost, `x-credits-remaining` is what is left, and `x-ratelimit-remaining` is 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. > **Tip: Swap the domain** > Replace `x.com` with `twitterviewer.app` in a post address, add your key as a Bearer token, and that URL returns Markdown. A browser still opens the normal viewer page, so the link works for people and for agents. ## 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 `obsidian` format 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=pdf` returns a PDF on A4 or Letter for Pro and Business, with images and post links, a result matching [Twitter Thread to PDF](https://twitterviewer.app/ko/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](https://twitterviewer.app/ko/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](https://twitterviewer.app/ko/pricing). 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](https://twitterviewer.app/docs/api). 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/mcp` lets Claude, Cursor and Codex read X directly. It has five read-only tools. See the [Twitter MCP Server](https://twitterviewer.app/ko/twitter-mcp-server) page for setup. - **Command-line tool.** `npx twitterviewer ` converts a link from a terminal and can save the result to a file. `twitterviewer login` signs you in through the browser and `twitterviewer credits` prints your balance. - **Agent Skill.** A skill file at `/.well-known/agent-skills/twitterviewer/SKILL.md` tells 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](https://twitterviewer.app/ko/x-to-markdown) page needs no code, and the [profile viewer](https://twitterviewer.app/ko/twitter-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](https://twitterviewer.app/ko/twitter-mcp-server) page has the configuration for each client.