# Weir documentation

> Public Reddit and X data for developers and AI agents, over REST and MCP. Each platform returns its own fields under its own names. Paid per returned result, from prepaid credits.

Every page is also Markdown: append `.md` to its URL. The OpenAPI contract is at https://api.weirapp.io/openapi.json, and the remote MCP server at https://api.weirapp.io/mcp. These docs can be searched over MCP too, with no sign-in, at https://docs.weirapp.io/api/mcp.

## Get started

- [Overview](/index.md): Public Reddit and X data for developers and AI agents, over a REST API and a remote MCP server.
- [Quickstart](/quickstart.md): A working search in five minutes. No card.
- [Authentication](/authentication.md): Two ways in. The REST API takes an API key. The MCP server takes an API key too, or signs your client in with OAuth so you never handle a key.
- [Errors](/errors.md): Every failure has the same shape:
- [Pagination](/pagination.md): Cursors, not page numbers.

## Concepts

- [Response shapes](/response-shapes.md): Each platform returns its own fields, under its own names. Nothing is renamed, nothing is dropped to make the shapes match.
- [Billing and credits](/billing.md): Weir is prepaid. You hold a balance of credits, every successful call spends some, and there is no subscription and no invoice at the end of the month. When the balance runs out, calls stop: you can…
- [Monitors and webhooks](/monitors.md): A monitor watches something on a schedule and reports only what is new.

## Agents

- [Skill](/skill.md): Give your agent the ability to search public social data. One line, no integration code.
- [MCP](/mcp.md): Weir runs a remote MCP server. Point any MCP client at this URL:
- [Claude and ChatGPT](/mcp-chat-apps.md): Both add Weir as a connector and sign in with OAuth, so there is no key to create. (Claude's connector dialog can also send a key as a request header, but that option is a beta only some…
- [Meta Muse](/muse.md): Muse has no built-in X or Reddit connector, but it can build a custom connector from an API. This page is written for Muse to read while it builds one: give it this page's address and your Weir key.
- [Coding agents and IDEs](/mcp-coding-agents.md): Every client here speaks Streamable HTTP, so each one connects straight to the URL. Most sign in with OAuth on first use; the key alternative is for headless runs and CI. Keep a key in an environment…
- [APIs and frameworks](/mcp-frameworks.md): Model APIs and agent frameworks run without a person at a browser, so they connect with a Weir API key, sent as Authorization: Bearer <key>. Create one under API keys and keep it in WEIR_API_KEY.
- [Files for agents](/agent-setup.md): Machine-readable files, each for a different consumer.

## Examples

- [Search X posts with Python, Node.js and cURL](/examples/search-x-posts.md): Search public X (Twitter) posts by keyword and print who posted each one, its likes and its link. X search operators work in query: here, NASA's posts with media.
- [Get the replies to an X post with Python, Node.js and cURL](/examples/x-post-replies.md): Read the replies under one X post, most liked first. The id is the digits after /status/ in a post's link; this one is a NASA post with 374 replies.
- [Get a whole X thread with Python, Node.js and cURL](/examples/x-thread.md): Read a thread: the chain of posts an author wrote in reply to themselves, in order, from any post in it. This one is a NASA thread.
- [Get an X profile with Python, Node.js and cURL](/examples/x-profile.md): Look up one X account by username: its name, follower count and the day it joined.
- [Get an account's X posts with Python, Node.js and cURL](/examples/x-user-posts.md): Read an X account's latest posts, newest first, by username.
- [Get an X account's followers with Python, Node.js and cURL](/examples/x-followers.md): Read the accounts that follow an X account, in the order X lists them (mostly newest first), and count how many are verified and how many have 1,000 or more followers. Each page holds as many…
- [Search Reddit with Python, Node.js and cURL](/examples/search-reddit.md): Search public Reddit posts in one community: here, the year's top r/SaaS posts about usage-based pricing.
- [Check your Weir credits with Python, Node.js and cURL](/examples/check-usage.md): See how many credits your account has left before a large job. This call is free.

## Reddit

- [Search public Reddit posts](/reference/reddit/searchReddit.md): POST /v1/reddit/search
- [Get one public Reddit post](/reference/reddit/getRedditPost.md): GET /v1/reddit/posts/{id}
- [Get information about a public subreddit](/reference/reddit/getSubreddit.md): GET /v1/reddit/subreddits/{name}
- [Search posts within one subreddit](/reference/reddit/searchSubreddit.md): POST /v1/reddit/subreddits/{name}/search
- [Get a Reddit comment tree as a flat list, page by page](/reference/reddit/getRedditComments.md): GET /v1/reddit/posts/{id}/comments
- [List a community's posts: hot, new, rising, top, or controversial](/reference/reddit/getSubredditPosts.md): GET /v1/reddit/subreddits/{name}/posts
- [Read a community's newest comments, across every post](/reference/reddit/getSubredditComments.md): GET /v1/reddit/subreddits/{name}/comments
- [Find communities by name or topic](/reference/reddit/searchSubreddits.md): POST /v1/reddit/search/subreddits
- [Get a Reddit account's public profile](/reference/reddit/getRedditUser.md): GET /v1/reddit/users/{username}
- [List the posts an account has submitted](/reference/reddit/getRedditUserPosts.md): GET /v1/reddit/users/{username}/posts
- [List the comments an account has made](/reference/reddit/getRedditUserComments.md): GET /v1/reddit/users/{username}/comments
- [Fetch up to 100 posts and comments, and 100 communities, in one call](/reference/reddit/lookupReddit.md): POST /v1/reddit/lookup

## X

- [Search public X posts with composable filters](/reference/x/searchX.md): POST /v1/x/search
- [Get up to 100 public X posts by id](/reference/x/getXPosts.md): GET /v1/x/posts
- [Get one public X post](/reference/x/getXPost.md): GET /v1/x/posts/{id}
- [Get replies to an X post](/reference/x/getXReplies.md): GET /v1/x/posts/{id}/replies
- [Get the author's thread containing a post](/reference/x/getXThread.md): GET /v1/x/posts/{id}/thread
- [Get posts quoting an X post](/reference/x/getXQuotes.md): GET /v1/x/posts/{id}/quotes
- [Get accounts that reposted an X post](/reference/x/getXRetweeters.md): GET /v1/x/posts/{id}/retweeters
- [Get the edit history of an X post](/reference/x/getXPostEdits.md): GET /v1/x/posts/{id}/edits
- [Read an X Article](/reference/x/getXArticle.md): GET /v1/x/posts/{id}/article
- [Get up to 100 public X profiles by id](/reference/x/getXUsers.md): GET /v1/x/users
- [Search X accounts](/reference/x/searchXUsers.md): POST /v1/x/users/search
- [Get a public X profile](/reference/x/getXUser.md): GET /v1/x/users/{user}
- [Get an X account's "About this account" details](/reference/x/getXUserAbout.md): GET /v1/x/users/{user}/about
- [Get a public X user timeline](/reference/x/getXUserPosts.md): GET /v1/x/users/{user}/posts
- [Get an X account's posts and replies](/reference/x/getXUserReplies.md): GET /v1/x/users/{user}/replies
- [Get an X account's posts with media](/reference/x/getXUserMedia.md): GET /v1/x/users/{user}/media
- [Get the posts an X account highlights](/reference/x/getXUserHighlights.md): GET /v1/x/users/{user}/highlights
- [Get an X account's followers](/reference/x/getXUserFollowers.md): GET /v1/x/users/{user}/followers
- [Get the accounts an X account follows](/reference/x/getXUserFollowing.md): GET /v1/x/users/{user}/following
- [Get an organisation's affiliated X accounts](/reference/x/getXUserAffiliates.md): GET /v1/x/users/{user}/affiliates
- [Get the creators an X account subscribes to](/reference/x/getXUserSubscriptions.md): GET /v1/x/users/{user}/subscriptions
- [Get a public X List](/reference/x/getXList.md): GET /v1/x/lists/{id}
- [Get the members of a public X List](/reference/x/getXListMembers.md): GET /v1/x/lists/{id}/members
- [Get the timeline of a public X List](/reference/x/getXListPosts.md): GET /v1/x/lists/{id}/posts
- [Get an X Space](/reference/x/getXSpace.md): GET /v1/x/spaces/{id}

## Monitors

- [List monitors](/reference/monitors/listMonitors.md): GET /v1/monitors
- [Create a monitor](/reference/monitors/createMonitor.md): POST /v1/monitors
- [Get one monitor](/reference/monitors/getMonitor.md): GET /v1/monitors/{id}
- [Update a monitor](/reference/monitors/updateMonitor.md): PATCH /v1/monitors/{id}
- [Delete a monitor](/reference/monitors/deleteMonitor.md): DELETE /v1/monitors/{id}
- [List deduplicated results a monitor has found](/reference/monitors/listMonitorResults.md): GET /v1/monitors/{id}/results
- [List a monitor's execution history](/reference/monitors/listMonitorRuns.md): GET /v1/monitors/{id}/runs
- [Get one monitor run](/reference/monitors/getMonitorRun.md): GET /v1/monitors/{id}/runs/{runId}
- [Queue a monitor run immediately](/reference/monitors/runMonitor.md): POST /v1/monitors/{id}/run

## Webhooks

- [List webhooks](/reference/webhooks/listWebhooks.md): GET /v1/webhooks
- [Create a webhook](/reference/webhooks/createWebhook.md): POST /v1/webhooks
- [Update a webhook](/reference/webhooks/updateWebhook.md): PATCH /v1/webhooks/{id}
- [Delete a webhook](/reference/webhooks/deleteWebhook.md): DELETE /v1/webhooks/{id}
- [Queue a test delivery](/reference/webhooks/testWebhook.md): POST /v1/webhooks/{id}/test
- [List recent delivery attempts](/reference/webhooks/listWebhookDeliveries.md): GET /v1/webhook-deliveries
- [Get one delivery, with its body](/reference/webhooks/getWebhookDelivery.md): GET /v1/webhook-deliveries/{id}

## Account

- [Credit balance, holds, and this month's free grant](/reference/account/getUsage.md): GET /v1/usage
- [Ceilings imposed by the account's tier](/reference/account/getLimits.md): GET /v1/limits
- [Identify the account and scopes behind this key](/reference/account/getIdentity.md): GET /v1/whoami

## System

- [Liveness check](/reference/system/getHealth.md): GET /health
- [Readiness check](/reference/system/getReadiness.md): GET /ready