Skip to main content

​
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/v2https://api.sorsa.io/v3
Authentication has not changed. Continue sending your API key in the 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 endpointv3 endpointNotes
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 endpointv3 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-memberPOST /check-community-member

​
2.3 Parameter name changes

Across most endpoints, parameter names have been unified:
v2 paramv3 paramContext
linkuser_linkAll user-related endpoints
user_handleusernameIn query and body params
cursornext_cursorIn /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 fieldv3 fieldNotes
screen_name / screeNameusernameUnified across all objects
id_str / id (varies)id (string)Consistently a string
favorite_countlikes_countOn tweet objects
friends_countfollowings_countOn user objects
statuses_counttweets_countOn user objects
register_datecreated_atOn user objects
avatar / bannerprofile_image_url / profile_background_image_urlRenamed
New fields added to the v3 User object:
  • 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:
Endpointv2 responsev3 response
/followsArray of LookupRes{ users: [...], next_cursor }
/list-membersArray of ListMember{ users: [...], next_cursor }
/top-followersArray of Account{ users: [...] }
/top-followingArray of Account{ users: [...] }
/comments{ comments: [...], next_cursor }{ tweets: [...], next_cursor }
/tweet-info-bulkArray of ListItem{ tweets: [...] }
If you were iterating over the raw array response from /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.

​
3.3 Pagination added

The following endpoints now support cursor-based pagination via next_cursor, which was not available in v2:
  • GET /follows - paginate through followed accounts
  • GET /list-members - paginate through large lists
  • GET /verified-followers (new) - cursor pagination
  • GET /followers (new) - cursor pagination
For pagination patterns and code examples, see Pagination.

​
4. Removed Endpoints

v2 EndpointMigration path
POST /when-followNo direct v3 equivalent. Use /new-followers-7d or /new-following-7d for recent activity, or contact support for alternatives.
GET /handle-historyNo 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

EndpointDescription
GET /info-batchFetch profile data for multiple accounts in a single request (by usernames or user_ids).
GET /followersPaginated list of an account’s followers with full profile data.
GET /verified-followersPaginated list of verified followers only.
GET /new-followers-7dAccounts that started following a user in the past 7 days (tracked accounts only).

​
5.2 Tweets

EndpointDescription
POST /mentionsSearch for tweets mentioning a specific user. Supports date filters, engagement minimums, and pagination.
POST /quotesList all quote tweets for a specific tweet, with pagination.
POST /retweetsList users who retweeted a specific tweet, with pagination.
POST /articleRetrieve full content and metrics for an X Article by URL.

​
5.3 Communities

EndpointDescription
POST /community-membersPaginated member list for an X Community.
POST /community-search-tweetsKeyword search within a specific community’s tweets.

​
5.4 Lists

EndpointDescription
GET /list-followersPaginated list of users following a specific X List.

​
5.5 Technical

EndpointDescription
GET /key-usage-infoCheck your API key quota: total requests, remaining, and expiration date.
GET /link-to-idExtract a stable user ID from a profile URL.
For the full specification of all v3 endpoints, see the API Reference.

​
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.