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. Core timestamps are ISO 8601 strings. User and Tweet created_at fields use values such as 2026-03-06T12:00:00Z. Consult the endpoint schema for other date fields; do not assume a verification result or relationship date has the same format. 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. Handle optional fields defensively: distinguish a missing value from a measured zero or false. For optional arrays such as bio_urls and pinned_tweet_ids, normalize null or missing values to an empty list when iterating (user.get("bio_urls") or [] in Python; user.bio_urls ?? [] in JavaScript). Compact response models omit fields present on a full User object.

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, /retweeters, /search-users, /list-members, and /list-followers. /community-members uses the same wrapper keys but returns compact CommunityUser objects.

{
  "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, and /top-following. /top-followers uses TopFollowersResponse, with compact profiles and a score field.

{
  "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": "2009-06-02T20:12:29Z",
  "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 /new-followers-7d, /new-following-7d, and /top-following. /top-followers returns a separate compact model with score.

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

Paginated list endpoints use cursor-based pagination. Batch lookups and the crypto analytics lists described above do not use a cursor. This approach is more reliable than offset-based pagination for dynamic feeds where new content is constantly being added. How it works:

Send your initial request without a cursor.
The response includes a next_cursor field along with the data.
To fetch the next page, include the next_cursor value in your next request.
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&next_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["next_cursor"] = cursor

    response = requests.get(
        "https://api.sorsa.io/v3/followers",
        params=params,
        headers={"ApiKey": API_KEY},
        timeout=30,
    )
    response.raise_for_status()
    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

Getting started

Core Mechanics

Solution Guides

Support & Resources

Response Format

API Response Format: User and Tweet Object Schemas

Conventions

Response wrappers

The User object

The Follower object

The Tweet object

The TweetEntity object

Next steps

​API Response Format: User and Tweet Object Schemas

​Conventions

​Response wrappers

​The User object

​The Follower object

​The Tweet object

​The TweetEntity object

​Cursor-based pagination

​Next steps

API Response Format: User and Tweet Object Schemas

Conventions

Response wrappers

The User object

The Follower object

The Tweet object

The TweetEntity object

Cursor-based pagination

Next steps