Sorsa API

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 ApiKey header. 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_KEY environment variable. Never hardcode it in committed code.

Minimal check:

bash

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):

bash

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:

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:

python

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 lookup
• examples/search_with_pagination.py: search and page through results
• examples/analyze_account.py: profile plus Sorsa Score plus top followers
• examples/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-7d and /new-following-7d read 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-tweets supports Twitter advanced-search operators (from:, to:, since:, until:, quoted phrases, hashtags). /mentions has the richest filter set (min_likes, min_replies, min_retweets, since_date, until_date).
• Rate limits. A 429 means rate-limited; back off and retry. Check remaining quota any time with GET /key-usage-info.
• Dates use ISO 8601 (2024-01-15T10:30:00Z), except since_date and until_date in /mentions, which use YYYY-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.