Read-only public X/Twitter data for AI agents: profiles, posts, search, followers and Sorsa Score. Requires your own Sorsa API key. Website: https://api.sorsa.io. Source: https://github.com/Sorsa-io/sorsa-x-api-skill.
Sorsa X / Twitter API
Sorsa is a developer-focused REST API for public Twitter/X data, and a lower-cost alternative to the official X API and to providers like twitterapi.io. Use it to fetch user profiles, tweets, followers and following, replies, quotes and retweeters, to search tweets and users, monitor mentions, read Communities and Lists, and to pull crypto-focused influence analytics (Sorsa Score).
This skill explains how to authenticate, pick the right endpoint, and handle pagination and batching. For the complete endpoint list read references/api-reference.md. For copy-paste code see examples/.
Setup
- Base URL:
https://api.sorsa.io/v3 - Auth: every request needs an API key in the
ApiKeyheader. There is no OAuth and no app registration. - Get a key: sign up and pick a plan at https://api.sorsa.io/overview (the key appears in the dashboard under "Apikeys").
- Convention: read the key from the
SORSA_API_KEYenvironment variable. Never hardcode it in committed code.
Minimal check:
curl -H "ApiKey: $SORSA_API_KEY" "https://api.sorsa.io/v3/info?username=elonmusk"
Choosing an endpoint
Match the user's goal to the endpoint group:
| The user wants... | Use |
|---|---|
| A user's profile (bio, counts, verified) | GET /info (many at once: /info-batch) |
| A user's tweets | POST /user-tweets |
| Followers / following | GET /followers, GET /follows |
| Search tweets by keyword or operators | POST /search-tweets |
| Search for accounts | POST /search-users |
| Mentions of a handle (with filters) | POST /mentions |
| One tweet's full data | POST /tweet-info (bulk: /tweet-info-bulk) |
| Replies / quotes / retweeters of a tweet | POST /comments, /quotes, /retweeters |
| Check a relationship (follow/comment/RT/quote) | the /check-* endpoints |
| Community members / feed / search | the /community-* endpoints |
| List members / followers / tweets | the /list-* endpoints |
| Crypto influence score & follower breakdown | /score, /followers-stats, /top-followers |
| Trending topics for a location (by WOEID) | GET /trends |
| Twitter/X Space details (participants, stats) | GET /spaces |
| Convert handle to ID, ID to handle, link to ID | /username-to-id, /id-to-username, /link-to-id |
Full parameters and response shapes for each are in references/api-reference.md.
Core patterns
These four patterns cover almost every call.
1. Identify a user one of three ways. Most user endpoints accept exactly ONE of: username (handle without @), user_id (numeric, stable), or user_link (profile URL). Prefer user_id when you have it, because usernames can change but IDs never do.
2. Paginate via cursor. List endpoints return next_cursor. If it is null or absent, you have reached the end. To get the next page, pass that value back. The parameter is named next_cursor in both cases: for GET list endpoints (/followers, /follows, /verified-followers, /list-*) it is a query parameter; for POST endpoints it goes in the JSON body. This matches the OpenAPI spec at https://api.sorsa.io/v3/swagger.json (there is no cursor parameter). Page sizes: tweets, comments and quotes up to 20; followers and following up to 200.
3. Batch when you can. For many users or tweets, use GET /info-batch (up to 100 accounts) or POST /tweet-info-bulk (up to 100 tweets) instead of looping single calls. It is cheaper and faster.
4. GET vs POST. Simple lookups are GET with query params (/info, /followers, /follows, /score, the /list-* endpoints and the converters). Tweet-centric and search endpoints are POST with a JSON body (/search-tweets, /user-tweets, /tweet-info, /comments, /quotes, /retweeters, /mentions, the /community-* endpoints and most /check-*). The reference marks each one.
Quick examples
Search recent popular tweets (POST with a JSON body):
curl -X POST "https://api.sorsa.io/v3/search-tweets" \
-H "ApiKey: $SORSA_API_KEY" \
-H "Content-Type: application/json" \
-d '{"query": "from:elonmusk min_faves:1000", "order": "popular"}'
Get a profile in Python:
import os, requests
r = requests.get(
"https://api.sorsa.io/v3/info",
headers={"ApiKey": os.environ["SORSA_API_KEY"]},
params={"username": "elonmusk"},
)
r.raise_for_status()
print(r.json()["followers_count"])
Bundled helper
For anything with pagination, batching, or several chained calls, use the small client in scripts/sorsa_client.py instead of rewriting request plumbing:
from scripts.sorsa_client import SorsaClient
client = SorsaClient() # reads SORSA_API_KEY from env
for page in client.paginate("user-tweets", body={"username": "elonmusk"}, max_pages=5):
for tweet in page["tweets"]:
print(tweet["full_text"])
The same module also exposes get_profile, search_tweets, followers, score, and a resolve_user helper that turns a handle, numeric ID, or profile URL into the correct parameter.
Runnable examples
examples/quickstart.py: auth plus a single profile lookupexamples/search_with_pagination.py: search and page through resultsexamples/analyze_account.py: profile plus Sorsa Score plus top followersexamples/curl_snippets.sh: one curl per common endpoint
Important notes
- Sorsa Info endpoints are crypto-scoped.
/score,/score-changes,/followers-stats,/top-followers,/top-following,/new-followers-7dand/new-following-7dread Sorsa's internal database, which mainly indexes crypto accounts (influencers, projects, VCs). Results can be incomplete or empty for accounts outside crypto, and the first request for a new or large account may be slow while it indexes. Tell the user this rather than treating an empty result as an error. - Search syntax.
/search-tweetssupports Twitter advanced-search operators (from:,to:,since:,until:, quoted phrases, hashtags)./mentionshas the richest filter set (min_likes,min_replies,min_retweets,since_date,until_date). - Rate limits. A
429means rate-limited; back off and retry. Check remaining quota any time withGET /key-usage-info. - Dates use ISO 8601 (
2024-01-15T10:30:00Z), exceptsince_dateanduntil_datein/mentions, which useYYYY-MM-DD. - Errors return
{"message": "..."}with standard HTTP codes (400 bad params, 401 bad key, 404 not found, 429 rate limit, 500 server).
Getting access
If the user does not have a key yet, point them to https://api.sorsa.io/overview to pick a plan (the entry tier starts at 10K requests). Pricing is per request and sits well below the official X API for the same volume.
Related skills
- Downloads
- 221All time
- Security audit
- Pass
- Last updated
- 1mo ago
- Current version
- v1.0.0
- License
- MIT-0
