# SocialData API

> SocialData is a REST API and MCP server for X (formerly Twitter) data: tweets, search, user profiles, followers, lists, communities, Spaces, and webhook monitors. You need no X developer account, no proxies, and no HTML parsing. Billing is pay-as-you-go from a prepaid balance, at a flat rate per item returned. There are no subscription plans.

Base URL: `https://api.socialdata.tools`
Auth: `Authorization: Bearer YOUR_API_KEY` on every request. Get a key at https://socialdata.tools/app/api-keys
MCP endpoint: `https://api.socialdata.tools/mcp` (HTTP transport, same API key, read-only, 14 tools)
OpenAPI 3.0 spec: https://socialdata.tools/openapi.yaml (every endpoint, parameter, and response schema)

```bash
curl "https://api.socialdata.tools/twitter/search?query=from%3Aelonmusk&type=Latest" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Accept: application/json"
```

```bash
claude mcp add --transport http socialdata https://api.socialdata.tools/mcp \
    --header "Authorization: Bearer YOUR_API_KEY"
```

Price (charged per item returned, not per request):

| What you fetch | Price |
| --- | --- |
| Tweets, profiles, followers, list and community items | $0.0002 each ($0.20 per 1,000) |
| Single-object lookups (one tweet, one list, one community, one Space, one profile) | $0.0002 per request |
| Extended bio | $0.001 per request |
| Social Actions: verify following | $0.004 per request |
| Social Actions: verify retweeted, verify commented | $0.008 per request |

Notes that agents get wrong:

- Rate limit: 120 requests per minute, shared across all endpoints, per API key. Write to support@socialdata.tools for a higher limit at no extra charge.
- Balance: the account must hold a positive balance. An empty balance returns `HTTP 402`.
- Billing: only successful requests that return data are billed. A request that returns nothing is free, but only for the first 3 such requests per minute; after that each one costs $0.0002.
- Pagination: cursor based. A list response holds `next_cursor`; send it back as the `cursor` query parameter to get the next page. A page holds about 20 items. Nothing pages automatically, and each page is a separate billed request.
- Caching: none. Every request fetches live data from X.
- Errors: conventional HTTP codes with the body `{"status": "error", "message": "..."}`. 401 bad key, 402 empty balance, 404 not found, 422 validation failed, 429 rate limited, 5xx retry.
- Scope: read only. The API cannot post, follow, like, or change anything on X.

## Getting started

- [Overview](https://docs.socialdata.tools/getting-started/overview.md): what SocialData covers and the four ways to reach the data (REST, Monitoring, Social Actions, MCP).
- [Authentication](https://docs.socialdata.tools/getting-started/authentication.md): where to find your API key and how to send the `Authorization: Bearer` header.
- [Pricing](https://docs.socialdata.tools/getting-started/pricing.md): the full per-endpoint price table and the fair-use policy for empty responses.
- [Rate limits](https://docs.socialdata.tools/getting-started/rate-limits.md): the 120 requests per minute limit and how to raise it.
- [Errors](https://docs.socialdata.tools/getting-started/errors.md): every HTTP status the API returns and what causes it.
- [Getting help](https://docs.socialdata.tools/getting-started/getting-help.md): how to contact support and what to include.

## Data API: search

- [Get search results](https://docs.socialdata.tools/reference/get-search-results.md): `GET /twitter/search?query={query}`. Requires `query`; supports every X advanced search operator and `type=Latest|Top`. Returns `tweets[]` plus `next_cursor`.

## Data API: users

- [Get user profile](https://docs.socialdata.tools/reference/get-user-profile.md): `GET /twitter/user/{username_or_id}`. Returns one user object: id, name, description, counts, verification.
- [Get user profiles by IDs](https://docs.socialdata.tools/reference/get-multiple-user-profiles.md): `POST /twitter/users-by-ids`. Body holds up to 100 numeric user IDs. Returns an array of user objects.
- [Get user profiles by usernames](https://docs.socialdata.tools/reference/get-multiple-user-profiles-by-usernames.md): `POST /twitter/users-by-usernames`. Body holds up to 100 usernames. Returns an array of user objects.
- [Get user followers](https://docs.socialdata.tools/reference/get-user-followers.md): `GET /twitter/user/{user_id}/followers`. Requires the numeric `user_id`. Returns a page of user objects plus `next_cursor`.
- [Get user verified followers](https://docs.socialdata.tools/reference/get-user-verified-followers.md): `GET /twitter/user/{user_id}/verified-followers`. Same shape as followers, limited to verified accounts.
- [Get user following](https://docs.socialdata.tools/reference/get-user-followings.md): `GET /twitter/user/{user_id}/following`. Returns a page of the user objects that this account follows, plus `next_cursor`.
- [Get user tweets and replies](https://docs.socialdata.tools/reference/get-user-tweets-replies.md): `GET /twitter/user/{user_id}/tweets` for posts only, `GET /twitter/user/{user_id}/tweets-and-replies` for posts and replies. Returns `tweets[]` plus `next_cursor`.
- [Get user mentions](https://docs.socialdata.tools/reference/get-user-mentions.md): `GET /twitter/user/{username}/mentions`. Takes the username, not the ID. Returns `tweets[]` plus `next_cursor`.
- [Get user highlights](https://docs.socialdata.tools/reference/get-user-highlights.md): `GET /twitter/user/{user_id}/highlights`. Returns the tweets the user pinned to the Highlights tab, plus `next_cursor`.
- [Get user likes](https://docs.socialdata.tools/reference/get-user-likes.md): `GET /twitter/user/{user_id}/likes`. Returns the tweets the user liked, plus `next_cursor`. The account must have a public likes tab.
- [Get user affiliates](https://docs.socialdata.tools/reference/get-user-affiliates.md): `GET /twitter/user/{user_id}/affiliates`. Returns the profiles affiliated with an organization account, plus `next_cursor`.
- [Get user lists](https://docs.socialdata.tools/reference/get-user-lists.md): `GET /twitter/user/{user_id}/lists`. Returns a page of list objects, plus `next_cursor`. Billed $0.0002 per list.
- [Get user extended bio](https://docs.socialdata.tools/reference/get-user-extended-bio.md): `GET /twitter/user/{username}/extended-bio`. Returns the extended profile fields as one object. Billed $0.001 per request.
- [Get similar profiles](https://docs.socialdata.tools/reference/get-user-similar-profiles.md): `GET /twitter/user/{user_id}/similar`. Returns the accounts X suggests as similar.

## Data API: tweets

- [Get tweet](https://docs.socialdata.tools/reference/get-tweet.md): `GET /twitter/tweets/{id}`. Returns one tweet object with text, author, and reply, retweet, quote, and like counts.
- [Get multiple tweets by IDs](https://docs.socialdata.tools/reference/get-multiple-tweets.md): `POST /twitter/tweets-by-ids`. Body holds the tweet IDs. Returns an array of tweet objects; billed per tweet returned.
- [Get tweet comments](https://docs.socialdata.tools/reference/get-tweet-comments.md): `GET /twitter/tweets/{id}/comments`. Returns a page of reply tweets, plus `next_cursor`.
- [Get tweet quotes](https://docs.socialdata.tools/reference/get-tweet-quotes.md): `GET /twitter/tweets/{id}/quotes`. Returns a page of quote-tweets, plus `next_cursor`.
- [Get tweet retweeters](https://docs.socialdata.tools/reference/get-tweet-retweeters.md): `GET /twitter/tweets/{tweet_id}/retweeted_by`. Returns a page of user objects, plus `next_cursor`.
- [Get thread](https://docs.socialdata.tools/reference/get-tweet-thread.md): `GET /twitter/thread/{thread_id}`. Takes any tweet ID in the thread. Returns every tweet of the thread, plus `next_cursor`.
- [Get article details](https://docs.socialdata.tools/reference/get-tweet-article.md): `GET /twitter/article/{article_id}`. Returns the article as a raw Draft.js content tree.
- [Get article v2](https://docs.socialdata.tools/reference/get-article-v2.md): `GET /v2/twitter/article/{article_id}`. Returns the same article as ready-to-use Markdown. Prefer this one.

## Data API: lists, communities, and Spaces

- [Get list details](https://docs.socialdata.tools/reference/get-list-details.md): `GET /twitter/list/{list_id}`. Returns one list object: name, description, owner, member count.
- [Get list members](https://docs.socialdata.tools/reference/get-list-members.md): `GET /twitter/list/{list_id}/members`. Returns a page of user objects, plus `next_cursor`.
- [Get list tweets](https://docs.socialdata.tools/reference/get-list-tweets.md): `GET /twitter/list/{list_id}/tweets`. Returns the timeline of the list, plus `next_cursor`.
- [Get community details](https://docs.socialdata.tools/reference/get-community-details.md): `GET /twitter/community/{community_id}`. Returns one community object.
- [Get community tweets](https://docs.socialdata.tools/reference/get-community-tweets.md): `GET /twitter/community/{community_id}/tweets`. Returns a page of community tweets, plus `next_cursor`.
- [Get community members](https://docs.socialdata.tools/reference/get-community-members.md): `GET /twitter/community/{community_id}/members`. Returns a page of members and their roles, plus `next_cursor`.
- [Search community tweets](https://docs.socialdata.tools/reference/get-community-search-results.md): `GET /twitter/community/{community_id}/search?query={query}`. Searches inside one community. Returns `tweets[]` plus `next_cursor`.
- [Get Space details](https://docs.socialdata.tools/reference/get-space-details.md): `GET /twitter/space/{space_id}`. Returns one Space object: title, state, host, participant counts.

## Social Actions API

- [Verify user is following](https://docs.socialdata.tools/social-actions/verify-user-following.md): `GET /twitter/user/{source_user_id}/following/{target_user_id}`. One call answers whether one account follows another. $0.004 per request, and much cheaper than paging the full followers list.
- [Verify user retweeted](https://docs.socialdata.tools/social-actions/verify-user-retweeted.md): `GET /twitter/tweets/{tweet_id}/retweeted_by/{user_id}`. Confirms one retweet. $0.008 per request.
- [Verify user commented](https://docs.socialdata.tools/social-actions/verify-user-commented.md): `GET /twitter/tweets/{tweet_id}/commented_by/{user_id}`. Confirms one reply. $0.008 per request.

## Monitoring API

- [Introduction](https://docs.socialdata.tools/monitoring/introduction.md): create a monitor and receive a webhook when a user posts, follows an account, changes a profile, or a search query matches. Use it instead of polling.
- [Pricing](https://docs.socialdata.tools/monitoring/pricing.md): flat hourly rates for user monitors, per-execution billing for search monitors.
- [Create user tweets monitor](https://docs.socialdata.tools/monitoring/create-user-tweets-monitor.md): `POST /monitors/user-tweets`. Sends a webhook with the full tweet payload on every new post or retweet.
- [Create user following monitor](https://docs.socialdata.tools/monitoring/create-user-following-monitor.md): `POST /monitors/user-following`. Sends a webhook with the full profile of each newly followed account.
- [Create user profile monitor](https://docs.socialdata.tools/monitoring/create-user-profile-monitor.md): `POST /monitors/user-profile`. Sends a webhook when the bio, location, avatar, or display name changes.
- [Create search query monitor](https://docs.socialdata.tools/monitoring/create-search-query-monitor.md): `POST /monitors/search-query`. Sends a webhook when a new tweet matches your search query. $0.0002 per tweet found.
- [Get monitor details](https://docs.socialdata.tools/monitoring/get-monitor-details.md): `GET /monitors/{monitor_id}`. Returns the configuration and current status of one monitor.
- [List active monitors](https://docs.socialdata.tools/monitoring/list-active-monitors.md): `GET /monitors?page={page}`. Returns every active monitor on the account.
- [Monitor event history](https://docs.socialdata.tools/monitoring/monitor-event-history.md): `GET /monitors/{monitor_id}/events`. Lists delivered events; add `/{event_id}` for the exact payload and your server response.
- [Edit monitor webhook URL](https://docs.socialdata.tools/monitoring/edit-monitor-webhook.md): overrides the global webhook URL for one monitor.
- [Delete monitor](https://docs.socialdata.tools/monitoring/delete-monitor.md): `DELETE /monitors/{monitor_id}`. Stops all deliveries permanently.
- [Set global webhook URL](https://docs.socialdata.tools/monitoring/set-global-webhook-url.md): `POST /user/webhook`. Sets the URL used by every monitor without its own `webhook_url`.
- [Set webhook secret](https://docs.socialdata.tools/monitoring/set-webhook-secret.md): `POST /user/webhook/secret`. Sets or rotates the signing secret.
- [Processing webhooks](https://docs.socialdata.tools/monitoring/processing-webhooks.md): the payload shape of each event type and how to recover missed events.
- [Verifying webhooks](https://docs.socialdata.tools/monitoring/verifying-webhooks.md): verify the `X-Signature` header with HMAC-SHA256 and your webhook secret.

## MCP server

Endpoint `https://api.socialdata.tools/mcp`, HTTP (streamable) transport, header `Authorization: Bearer YOUR_API_KEY`. Read only, 14 tools, billed exactly like the equivalent REST call. Claude Code setup: `claude mcp add --transport http socialdata https://api.socialdata.tools/mcp --header "Authorization: Bearer YOUR_API_KEY"`. The claude.ai and ChatGPT web connectors cannot use it, because they require OAuth.

- [MCP introduction](https://docs.socialdata.tools/mcp/introduction.md): what the server does, the endpoint, authentication, and how tool calls are billed.
- [Connect your client](https://docs.socialdata.tools/mcp/connecting.md): configuration for Claude Code, Claude Desktop, Cursor, and Windsurf, plus troubleshooting.
- [Available MCP tools](https://docs.socialdata.tools/mcp/tools.md): all 14 tools, which ones paginate, and which two cost the most.

## Resources

- [OpenAPI 3.0 specification](https://socialdata.tools/openapi.yaml): the machine-readable spec for all 36 endpoints. Use it to generate a client or to import the API into a tool.
- [X (Twitter) advanced search operators](https://docs.socialdata.tools/resources/twitter-search-operators.md): every search operator the `query` parameter accepts, with an example for each.

## Product and account

- [Homepage](https://socialdata.tools/): product overview and use cases.
- [Pricing](https://socialdata.tools/#pricing): the price table on the marketing site.
- [Sign up](https://socialdata.tools/signup): create an account and receive an API key.
- [Log in](https://socialdata.tools/login): existing accounts.
- [API keys](https://socialdata.tools/app/api-keys): create, view, and rotate keys; check your balance.
- [Status page](https://status.socialdata.tools/): live availability and incident history.
- [Support](mailto:support@socialdata.tools): technical questions, higher rate limits, billing.
- [Terms and conditions](https://socialdata.tools/legal/terms-and-conditions): terms of service.
- [Privacy policy](https://socialdata.tools/legal/privacy-policy): how we handle your data.

## Optional

- [Complete documentation as one file](https://docs.socialdata.tools/llms-full.txt): every documentation page in full, about 520 KB. Read it only when you need the complete request and response examples.