Response Format

API Response Format: User and Tweet Object Schemas

Sorsa API returns all data as JSON. This page documents the response structure, core data objects, field types, and pagination model so you know exactly what to expect from every endpoint.

---

Conventions

Before diving into specific objects, here are the formatting rules that apply across the entire API.

IDs are strings. All X/Twitter IDs (id, conversation_id_str, in_reply_to_tweet_id, etc.) are returned as strings, not integers. X uses Snowflake IDs, which are 64-bit numbers that exceed JavaScript’s Number.MAX_SAFE_INTEGER. Returning them as strings prevents silent precision loss in browsers, Node.js, and any language that represents JSON numbers as floating-point.

Timestamps are ISO 8601 strings. All date fields use the format 2026-03-06T12:00:00Z. This is compatible with standard datetime parsers in every major language and database.

Booleans are strict. Status flags like verified, is_reply, protected, and can_dm are always true or false, never 0/1 or "true"/"false".

Null and missing fields. Optional fields that have no value are returned as null. Fields like bio_urls or pinned_tweet_ids return null rather than an empty array when there is no data.

---

Response wrappers

Endpoints that return a single object (like /info or /tweet-info) return the object directly at the top level. Endpoints that return lists use one of the following wrapper structures.

UsersResponse - used by /followers, /follows, /verified-followers, /retweets, /search-users, /list-members, /list-followers, /community-members

{
  "users": [ ... ],
  "next_cursor": "abc123"
}

TweetsResponse - used by /user-tweets, /comments, /quotes, /search-tweets, /mentions, /list-tweets, /community-tweets, /community-search-tweets

{
  "tweets": [ ... ],
  "next_cursor": "abc123"
}

FollowersResponse - used by /new-followers-7d, /new-following-7d, /top-followers, /top-following

{
  "users": [ ... ]
}

Note: FollowersResponse does not include next_cursor. It returns the full result set in a single response.

---

The User object

The User object represents an X/Twitter account profile. It is returned directly by /info, as an array element in list endpoints, and nested inside every Tweet object as the user field.

{
  "id": "44196397",
  "username": "elonmusk",
  "display_name": "Elon Musk",
  "description": "Mars & Cars, Chips & Dips",
  "location": "Earth",
  "created_at": "Tue Jun 02 20:12:29 +0000 2009",
  "followers_count": 236021252,
  "followings_count": 1292,
  "favourites_count": 214650,
  "tweets_count": 98479,
  "media_count": 4374,
  "profile_image_url": "https://pbs.twimg.com/profile_images/.../photo_normal.jpg",
  "profile_background_image_url": "https://pbs.twimg.com/profile_banners/44196397/...",
  "bio_urls": ["https://example.com"],
  "pinned_tweet_ids": ["2028500984977330453"],
  "verified": true,
  "can_dm": false,
  "protected": false,
  "possibly_sensitive": false
}

Field	Type	Description
id	string	Permanent numeric user ID (Snowflake)
username	string	Current handle / screen name (without @)
display_name	string	Public profile name
description	string	Account bio
location	string	User-specified location (free text)
created_at	string	Account creation timestamp
followers_count	integer	Number of followers
followings_count	integer	Number of accounts followed
favourites_count	integer	Total likes given by this account
tweets_count	integer	Total tweets posted
media_count	integer	Total media items posted
profile_image_url	string	Avatar image URL
profile_background_image_url	string	Banner image URL
bio_urls	array of strings or null	URLs from the bio section
pinned_tweet_ids	array of strings or null	IDs of pinned tweets
verified	boolean	Verification status (Blue, Gold, or Gray checkmark)
can_dm	boolean	Whether DMs are open
protected	boolean	Whether the account is private
possibly_sensitive	boolean	Whether the account is flagged as sensitive

---

The Follower object

The Follower object extends the User object with one additional field. It is returned by Sorsa Info endpoints like /new-followers-7d, /top-followers, etc.

Additional field	Type	Description
followerDate	string	Date when the follow relationship was recorded

---

The Tweet object

The Tweet object contains the full content, metadata, engagement metrics, and nested relationships for a single tweet. It is returned directly by /tweet-info and as array elements in tweet list endpoints.

{
  "id": "1234567890123456789",
  "full_text": "This is the complete tweet text including mentions and links",
  "created_at": "2026-03-06T12:00:00Z",
  "lang": "en",
  "bookmark_count": 42,
  "likes_count": 1500,
  "quote_count": 23,
  "reply_count": 89,
  "retweet_count": 312,
  "view_count": 250000,
  "conversation_id_str": "1234567890123456789",
  "in_reply_to_tweet_id": null,
  "in_reply_to_username": null,
  "is_reply": false,
  "is_quote_status": false,
  "is_replies_limited": false,
  "entities": [ ... ],
  "user": { ... },
  "quoted_status": null,
  "retweeted_status": null
}

Content fields

Field	Type	Description
id	string	Unique tweet ID (Snowflake)
full_text	string	Complete tweet text
created_at	string	Publication timestamp
lang	string	Detected language code (e.g., “en”, “ja”, “es”)

Engagement metrics

Field	Type	Description
likes_count	integer	Total likes
retweet_count	integer	Total retweets
reply_count	integer	Total replies
quote_count	integer	Total quote tweets
view_count	integer	Total impressions
bookmark_count	integer	Total bookmarks

Thread and reply context

Field	Type	Description
conversation_id_str	string	ID of the root tweet in the thread
in_reply_to_tweet_id	string or null	ID of the tweet this is replying to
in_reply_to_username	string or null	Username of the account being replied to
is_reply	boolean	Whether this tweet is a reply
is_quote_status	boolean	Whether this tweet quotes another tweet
is_replies_limited	boolean	Whether replies are restricted by the author

Nested objects

Field	Type	Description
user	User object	Full profile of the tweet author
entities	array of TweetEntity	Media and link attachments
quoted_status	Tweet object or null	The quoted tweet (full object, recursive)
retweeted_status	Tweet object or null	The original retweeted tweet (full object, recursive)

The quoted_status and retweeted_status fields contain complete Tweet objects, including their own user, entities, and engagement metrics. This means you get all related data in a single API call without needing to make follow-up requests.

---

The TweetEntity object

Each item in the entities array represents a media attachment or embedded link within a tweet.

{
  "type": "photo",
  "link": "https://pbs.twimg.com/media/..._large.jpg",
  "preview": "https://pbs.twimg.com/media/..._small.jpg"
}

Field	Type	Description
type	string	Entity type (e.g., photo, video, animated_gif)
link	string	Direct URL to the full-resolution asset
preview	string	Preview text or thumbnail URL

---

Cursor-based pagination

Endpoints that return lists use cursor-based pagination. This approach is more reliable than offset-based pagination for dynamic feeds where new content is constantly being added.

How it works:

1. Send your initial request without a cursor.
2. The response includes a next_cursor field along with the data.
3. To fetch the next page, include the next_cursor value in your next request.
4. When next_cursor is null or absent, you have reached the end of the data.

GET endpoints accept the cursor as a query parameter:

curl --request GET \
  --url 'https://api.sorsa.io/v3/followers?username=elonmusk&cursor=abc123' \
  --header 'ApiKey: YOUR_API_KEY'

POST endpoints accept the cursor in the JSON body:

curl --request POST \
  --url 'https://api.sorsa.io/v3/search-tweets' \
  --header 'ApiKey: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{"query": "bitcoin", "next_cursor": "abc123"}'

Python example: paginating through all followers

import time
import requests

API_KEY = "YOUR_API_KEY"
all_users = []
cursor = None

while True:
    params = {"username": "elonmusk"}
    if cursor:
        params["cursor"] = cursor

    response = requests.get(
        "https://api.sorsa.io/v3/followers",
        params=params,
        headers={"ApiKey": API_KEY}
    )
    data = response.json()

    all_users.extend(data["users"])
    cursor = data.get("next_cursor")

    if not cursor:
        break

    time.sleep(0.05)  # respect rate limit

print(f"Fetched {len(all_users)} followers")

For a deeper look at pagination strategies and performance tips, see Pagination.

---

Next steps

• Pagination - Advanced pagination patterns and best practices
• Error Codes - How error responses are structured
• API Reference - Full endpoint schemas with request and response examples