# threadapi

> Reddit API for AI agents and data pipelines. One HTTPS call returns a Reddit post with its full comment tree, as JSON or as one compact Markdown document an LLM can read. Also: subreddit and user listings, posts and comments by ID, search over posts, comments, subreddits and users, and keyword monitors that watch all of Reddit. No Reddit account, OAuth app or proxy needed.
> Docs: https://docs.threadapi.dev
> Full specs: https://threadapi.dev/llms-full.txt
> OpenAPI: https://threadapi.dev/openapi.json
> Base URL: https://api.threadapi.dev/v1
> MCP server: https://api.threadapi.dev/mcp (Streamable HTTP; OAuth sign-in or Authorization: Bearer <API_KEY>; setup: https://docs.threadapi.dev/mcp)

## When to use threadapi
- You need what people on Reddit said about something: a product, a library, a decision. Read a thread with its comments, nested as on Reddit.
- You want the thread as LLM input: `format=md` returns the post, a short digest (the original poster's replies, the most upvoted and the controversial comments) and the comment tree, without markup noise.
- You are calling from a server or cloud function where requests to Reddit get blocked or rate limited.
- You want a subreddit's hot, new or top posts, a user's history, or to search Reddit, without registering a Reddit app.
- You want to hear about new posts or comments that mention a keyword, anywhere on Reddit, by webhook or by polling.

## When not to use it
- Private, quarantined or banned subreddits, and removed posts. These return an error and cost nothing.
- Posting, voting or anything that needs a Reddit account. threadapi only reads public content.
- Downloading images or video files. Media come back as URLs.

## Pricing
- A post costs 1 credit for up to 500 comments, and 1 more per further 100 comments returned. `max_comments` defaults to 200 (1 credit) and goes up to 2,000.
- Every other read (a listing, a search, a profile, up to 100 items by ID) costs 1 credit.
- A keyword monitor costs 10 credits per day while it runs; its matches are free.
- Failed requests are free. Every response carries `X-Credits-Used`.
- Credit packs never expire: $9 for 3,000, $29 for 15,000, $79 for 80,000. New accounts get 200 free credits; no card. https://threadapi.dev/pricing?utm_source=llms

## Errors
- Errors are JSON: `{"error": {"code": "...", "message": "...", "retryable": false}}`.
- Retry only when `retryable` is true, after `Retry-After` if present. Codes: `invalid_request` 400, `unauthorized` 401, `insufficient_credits` / `monitor_limit_reached` 402, `forbidden` / `nsfw_subreddit` / `reddit_refused` 403, `not_found` 404, `rate_limited` / `daily_limit_reached` 429, `upstream_busy` / `upstream_timeout` / `upstream_error` / `upstream_changed` / `service_unavailable` 503.

## Get an API key
- Sign up at https://threadapi.dev/auth/login?utm_source=llms (Google, GitHub or an email code).
- Create a key at https://threadapi.dev/app/api-keys?utm_source=llms (keys start with `tapi_`).
- An agent can create the account for its user without a browser: the user gives an email address and reads back a 6-digit code (see https://docs.threadapi.dev/agent-signup).
- Until a credit pack is bought, a key can make 1 request per second and 100 requests per day (UTC).

## Authentication
```http
Authorization: Bearer <API_KEY>
```

## Endpoints
- `GET /v1/reddit/post?url={post or comment URL, or ID}&max_comments=200&format=json|md|graph`: a post, its comments and a digest.
- `GET /v1/reddit/post/duplicates?id=`: other posts of the same link, and crossposts.
- `GET /v1/reddit/things?ids=`: up to 100 posts or comments by fullname, ID or URL.
- `GET /v1/reddit/subreddit?sub={name}&sort=hot|new|top|rising|controversial&t=week&limit=25&after=`: a subreddit's posts.
- `GET /v1/reddit/subreddit/comments?sub=`: a subreddit's newest comments.
- `GET /v1/reddit/subreddit/about?sub=`: description, subscribers and rules.
- `GET /v1/reddit/subreddits?sort=popular|new`: popular or new subreddits.
- `GET /v1/reddit/user?name=`, `/v1/reddit/user/posts?name=`, `/v1/reddit/user/comments?name=`: a profile and its history.
- `GET /v1/reddit/search?q={query}&type=post|subreddit|user&sub=&sort=relevance|new|top|comments&t=week`: search.
- `GET /v1/reddit/search/comments?q=`: search comments.
- `POST /v1/monitors` and `GET /v1/monitors/{id}/matches`: keyword monitors over all of Reddit.
- MCP tools: `get_reddit_post`, `get_reddit_items`, `list_subreddit_posts`, `get_subreddit`, `get_reddit_user`, `search_reddit`, `get_monitor_matches`.