Documentation Index
Fetch the complete documentation index at: https://docs.sorsa.io/llms.txt
Use this file to discover all available pages before exploring further.
Migration Guide: Upgrading from Sorsa API v2 to v3
v2 deprecation notice: Support for API v2 will be discontinued on May 1, 2026. After this date, all v2 endpoints will stop responding. Please complete your migration to v3 before the deadline.
Quick summary: v3 unifies parameter naming, adds pagination to previously unpaginated endpoints, expands the data model, and introduces 14 new endpoints. Most changes are straightforward renames, but some response schemas have changed significantly.
1. Base URL
Update every request to use the new base URL:
| v2 (deprecated) | v3 (current) |
|---|
https://api.sorsa.io/v2 | https://api.sorsa.io/v3 |
ApiKey header. See Authentication for details.
2. Renamed & Restructured Endpoints
2.1 Path parameters to query parameters
Several v2 endpoints that accepted identifiers as path segments now use query parameters instead. This provides a unified interface where you can pass user_link, username, or user_id interchangeably.
| v2 endpoint | v3 endpoint | Notes |
|---|
GET /info/{user_handle} | GET /info?username={handle} | Also accepts user_link or user_id |
GET /info-id/{user_id} | GET /info?user_id={id} | Merged into /info |
GET /score/{user_handle} | GET /score?username={handle} | Also accepts link or user_id |
GET /score-id/{user_id} | GET /score?user_id={id} | Merged into /score |
GET /top-followers/{handle} | GET /top-followers?username={handle} | Now uses query params |
GET /top-following/{handle} | GET /top-following?username={handle} | Now uses query params |
2.2 Endpoint path renames
| v2 endpoint | v3 endpoint |
|---|
GET /handle-to-id/{handle} | GET /username-to-id/{handle} |
GET /id-to-handle/{user_id} | GET /id-to-username/{user_id} |
POST /check-member | POST /check-community-member |
2.3 Parameter name changes
Across most endpoints, parameter names have been unified:
| v2 param | v3 param | Context |
|---|
link | user_link | All user-related endpoints |
user_handle | username | In query and body params |
cursor | next_cursor | In /user-tweets, /list-tweets |
3. Response Schema Changes
Breaking changes ahead. These require updates to your response parsing logic.
3.1 User object field renames
| v2 field | v3 field | Notes |
|---|
screen_name / screeName | username | Unified across all objects |
id_str / id (varies) | id (string) | Consistently a string |
favorite_count | likes_count | On tweet objects |
friends_count | followings_count | On user objects |
statuses_count | tweets_count | On user objects |
register_date | created_at | On user objects |
avatar / banner | profile_image_url / profile_background_image_url | Renamed |
bio_urls (array of strings)location (string)media_count (integer)pinned_tweet_ids (array of strings)possibly_sensitive (boolean)
For the complete v3 User and Tweet object schemas, see Response Format.
3.2 Response wrappers
Several endpoints now return data inside a standardized wrapper object instead of a raw array:
| Endpoint | v2 response | v3 response |
|---|
/follows | Array of LookupRes | { users: [...], next_cursor } |
/list-members | Array of ListMember | { users: [...], next_cursor } |
/top-followers | Array of Account | { users: [...] } |
/top-following | Array of Account | { users: [...] } |
/comments | { comments: [...], next_cursor } | { tweets: [...], next_cursor } |
/tweet-info-bulk | Array of ListItem | { tweets: [...] } |
/follows, /list-members, /top-followers, or /top-following, you now need to access the .users property first. Similarly, /comments data is now under .tweets instead of .comments.
The following endpoints now support cursor-based pagination via next_cursor, which was not available in v2:
GET /follows - paginate through followed accountsGET /list-members - paginate through large listsGET /verified-followers (new) - cursor paginationGET /followers (new) - cursor pagination
For pagination patterns and code examples, see Pagination.
4. Removed Endpoints
| v2 Endpoint | Migration path |
|---|
POST /when-follow | No direct v3 equivalent. Use /new-followers-7d or /new-following-7d for recent activity, or contact support for alternatives. |
GET /handle-history | No direct v3 equivalent. The /about endpoint still returns username_change_count and last_username_change_at, but not the full history. |
5. New Endpoints in v3
5.1 User data
| Endpoint | Description |
|---|
GET /info-batch | Fetch profile data for multiple accounts in a single request (by usernames or user_ids). |
GET /followers | Paginated list of an account’s followers with full profile data. |
GET /verified-followers | Paginated list of verified followers only. |
GET /new-followers-7d | Accounts that started following a user in the past 7 days (tracked accounts only). |
| Endpoint | Description |
|---|
POST /mentions | Search for tweets mentioning a specific user. Supports date filters, engagement minimums, and pagination. |
POST /quotes | List all quote tweets for a specific tweet, with pagination. |
POST /retweets | List users who retweeted a specific tweet, with pagination. |
POST /article | Retrieve full content and metrics for an X Article by URL. |
5.3 Communities
| Endpoint | Description |
|---|
POST /community-members | Paginated member list for an X Community. |
POST /community-search-tweets | Keyword search within a specific community’s tweets. |
5.4 Lists
| Endpoint | Description |
|---|
GET /list-followers | Paginated list of users following a specific X List. |
5.5 Technical
| Endpoint | Description |
|---|
GET /key-usage-info | Check your API key quota: total requests, remaining, and expiration date. |
GET /link-to-id | Extract a stable user ID from a profile URL. |
6. Migration Checklist
- [ ] Update base URL from
api.sorsa.io/v2 to api.sorsa.io/v3 across all environments.
- [ ] Rename endpoint paths per the tables in Section 2 (
info, score, handle-to-id, etc.).
- [ ] Update parameter names:
link -> user_link, user_handle -> username, cursor -> next_cursor.
- [ ] Update response parsing: unwrap new wrapper objects (
.users, .tweets) and rename fields (screen_name -> username, friends_count -> followings_count, etc.).
- [ ] Handle removed endpoints: replace
/when-follow and /handle-history with the recommended alternatives.
- [ ] Test pagination: endpoints that previously returned flat arrays now support
next_cursor. Update your iteration logic.
- [ ] Explore new endpoints: consider adopting
/mentions, /quotes, /retweets, /info-batch, and /key-usage-info to enhance your integration.
