API reference
Every endpoint, request shape and response field, generated from the API's own OpenAPI document.
Current credit balance, and the plan it belongs to.
Every key on the account, revoked ones included. Returns the prefix, never the hash and never the key. The prefix identifies a key without being one.
Mint a new API key. **Authenticates with a session, not an API key.** The raw key is in this response and nowhere else, ever again.
Revoke one key. Scoped to the caller: a key belonging to someone else is a 404, not a 403, so the id cannot be used to probe for real keys. The key stops working immediately, but its history is kept: a revoked key still appears in this list and in your usage records.
A post and its reply thread, as TikHub returns it. **Not a bare list.** Despite the vendor calling this "comments", the payload is the post itself — `id`, `text`, `author`, counters — with the replies under `thread`. That is why this route's content key is `id`: the post is what proves the call answered. Returns third-party personal data in bulk — see `/legal/privacy`. Replies carry their authors' handles, display names and avatar URLs verbatim, and nothing is hashed.
The newest replies to a post, as TikHub returns it. A different shape from `/twitter/comments` despite the neighbouring name: this one answers with a `timeline` list and no parent post, ordered newest first. Returns third-party personal data in bulk — see `/legal/privacy`.
One page of the accounts following a user, as TikHub returns it. Returns third-party personal data in bulk — see `/legal/privacy`. A page is dozens of accounts none of whom is the subject the caller named. An unknown handle returns `{"followers": [], "status": "ok", "more_users": false}`, which reads as content to anything not keying on `followers`; it answers `502 extraction_empty` here and is not charged.
One page of the accounts a user follows, as TikHub returns it. Returns third-party personal data in bulk — see `/legal/privacy`. Unlike `/twitter/followers`, an unknown handle answers 400 upstream rather than an empty page.
One page of a user's posts that carry media, as TikHub returns it. Same timeline shape as `/twitter/tweets`, filtered upstream to posts with images or video. Media URLs point at X's own CDN; nothing here fetches them.
One X/Twitter user profile, as TikHub returns it. Carries `created_at`, `friends` and `sub_count` — account age and the following/follower ratio, which is what an authenticity signal is built from. A handle that does not exist answers `502 extraction_empty` and is not charged: the upstream returns `{"status": "notfound"}` with every other field null, which is why this route's content key is `rest_id` rather than "anything at all".
One page of a user's replies to other people, as TikHub returns it. The timeline routes exclude replies, so this is the other half of an account's output rather than a filter over the same data.
One page of the accounts that reposted a post, as TikHub returns it. Returns third-party personal data in bulk — see `/legal/privacy`.
One page of X/Twitter search results, as TikHub returns it. **Results are not stable between calls.** Two identical requests measured minutes apart returned the same posts in a different order, so a cached response is one arbitrary ordering rather than a snapshot anyone can reproduce. Treat the result as a sample of what matches, not as a ranking. There is no `search_type`: the vendor documents one, accepts any string including nonsense, and could not be shown to act on it.
Current X/Twitter trends for a country, as TikHub returns it. The country is a name rather than an ISO code — `UnitedStates` is the vendor's default and its spelling. An unrecognised value still answers 200 with trends rather than an error, so a typo here degrades silently to some default rather than failing loudly. Cache with care: this is the one route whose answer is meant to change hourly.
One X/Twitter post by id, as TikHub returns it. The id is the long number at the end of a post URL. **Old ids are not served**: the 2006 post `20` answers 400, while a 2022-era id answers 200 with the full object. Where the cutoff sits has not been measured, so treat a 400 here as "too old or not public" rather than as a malformed id.
One page of an X/Twitter user's posts, as TikHub returns it. Each item carries `favorites`, `retweets`, `replies`, `quotes`, `bookmarks` and `views`, plus `conversation_id` and `retweeted_tweet` — which is how replies and retweets are told apart from original posts. Page size is the vendor's to choose; there is no `count`. To page, pass the previous response's `next_cursor` as `cursor`.
Your own call history, newest first. Free — it reads our table, not the vendor. **`request` and `response` are null unless the deployment enables the call log** (`CALL_LOG_DAYS`, ADR-036), which is off by default. The rest of each row — endpoint, credits, cached, timestamp — has always been recorded and is what billing runs on. Bodies are opt-in per request rather than always included. A page of fifty payloads is megabytes, and a caller listing "what did I call yesterday" wants neither the bytes nor the wait; `include=response` is for the caller who is replaying one. Scoped to `ctx.key.user_id` in the query itself rather than filtered afterwards. That is the difference between a bug that leaks another customer's history and a query that cannot express it.
MCP server
The same endpoints are available to an AI agent over the Model Context Protocol, so a client can call SocialPipe itself instead of you writing glue around REST. There is nothing to install: point the client at one URL and give it your API key.
https://api.socialpipe.dev/mcpConnect
Your key goes in an Authorization header as a bearer token. It is the same sp_live_… key the REST API uses, from your dashboard.
Claude Code:
claude mcp add --transport http socialpipe https://api.socialpipe.dev/mcp \
--header "Authorization: Bearer sp_live_YOUR_KEY"Claude Desktop, Cursor and other config-file clients:
{
"mcpServers": {
"socialpipe": {
"type": "http",
"url": "https://api.socialpipe.dev/mcp",
"headers": {
"Authorization": "Bearer sp_live_YOUR_KEY"
}
}
}
}Restart the client afterwards. It should list two SocialPipe tools.
Your API key can spend credits. Treat the config file like any other file holding a credential. Do not commit it to a repository, and use a separate key per machine so you can revoke one without disturbing the others.
The tools
| Tool | What it does | Cost |
|---|---|---|
x_user_profile | One X profile record, as X returns it | 1 credit |
x_user_tweets | One page of an X user's timeline | 1 credit |
x_search | One page of X search results for a keyword | 1 credit |
Three tools rather than one per endpoint, on purpose: twelve near-identical tools returning twelve shapes of raw JSON is a harder choice for an agent than three. Each takes a plain input — a username or a keyword — and returns the platform's response untouched. Cached reads cost nothing, and a failed call is never charged.
The routes that return pages of other people — followers, following, reposted-by and the two reply paths — are deliberately not tools. An agent that can pull a follower graph in one call will; a bulk retrieval of third-party personal data should be something a developer chose to write. They are all available over REST.