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

# 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`

```text theme={null}
{
  "users": [ ... ],
  "next_cursor": "abc123"
}
```

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

```text theme={null}
{
  "tweets": [ ... ],
  "next_cursor": "abc123"
}
```

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

```text theme={null}
{
  "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.

```text theme={null}
{
  "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.

```text theme={null}
{
  "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.

```text theme={null}
{
  "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:

```text theme={null}
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:

```text theme={null}
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**

```text theme={null}
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](https://docs.sorsa.io/pagination).

***

## Next steps

* [Pagination](https://docs.sorsa.io/pagination) - Advanced pagination patterns and best practices
* [Error Codes](https://docs.sorsa.io/error-codes) - How error responses are structured
* [API Reference](https://docs.sorsa.io/api-reference-guide) - Full endpoint schemas with request and response examples