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

# Formato de resposta

# Formato de resposta: esquemas de User e Tweet

A Sorsa retorna dados em JSON. Esta página descreve estruturas de resposta, objetos, tipos e paginação.

## Convenções

**IDs são strings.** IDs do X, como `id`, `conversation_id_str` e `in_reply_to_tweet_id`, são strings, não inteiros. IDs Snowflake de 64 bits ultrapassam `Number.MAX_SAFE_INTEGER` do JavaScript. Strings evitam perda silenciosa de precisão no navegador, Node.js e linguagens que tratam números JSON como ponto flutuante.

**Datas principais usam ISO 8601.** `created_at` em User e Tweet usa valores como `2026-03-06T12:00:00Z`. Consulte o esquema de cada endpoint para outras datas; resultados de verificação e datas de relacionamento podem ter formatos diferentes.

**Booleanos são estritos.** `verified`, `is_reply`, `protected` e `can_dm` são `true` ou `false`, nunca `0`/`1` nem strings.

**Campos nulos e ausentes.** Diferencie ausência de zero medido ou `false`. Para iterar sobre arrays opcionais como `bio_urls` e `pinned_tweet_ids`, normalize valores nulos ou ausentes para lista vazia: `user.get("bio_urls") or []` no Python e `user.bio_urls ?? []` no JavaScript. Modelos compactos omitem campos do User completo.

## Estruturas de resposta

Endpoints de um objeto, como `/info` e `/tweet-info`, retornam o objeto diretamente. Listas usam as estruturas abaixo.

**UsersResponse:** `/followers`, `/follows`, `/verified-followers`, `/retweeters`, `/search-users`, `/list-members` e `/list-followers`. `/community-members` usa as mesmas chaves, com objetos compactos `CommunityUser`.

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

**TweetsResponse:** `/user-tweets`, `/comments`, `/quotes`, `/search-tweets`, `/mentions`, `/list-tweets`, `/community-tweets` e `/community-search-tweets`.

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

**FollowersResponse:** `/new-followers-7d`, `/new-following-7d` e `/top-following`. `/top-followers` usa `TopFollowersResponse`, com perfis compactos e `score`.

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

FollowersResponse não inclui `next_cursor`: retorna todo o resultado em uma resposta.

## Objeto User

Representa o perfil de uma conta do X. É retornado diretamente por `/info`, como item de listas e no campo `user` de cada Tweet.

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

| Campo                          | Tipo                     | Descrição                                           |
| :----------------------------- | :----------------------- | :-------------------------------------------------- |
| `id`                           | string                   | ID permanente (Snowflake)                           |
| `username`                     | string                   | Nome de usuário atual, sem @                        |
| `display_name`                 | string                   | Nome público do perfil                              |
| `description`                  | string                   | Bio da conta                                        |
| `location`                     | string                   | Localização informada pelo usuário (texto livre)    |
| `created_at`                   | string                   | Data e hora de criação                              |
| `followers_count`              | integer                  | Quantidade de seguidores                            |
| `followings_count`             | integer                  | Quantidade de contas seguidas                       |
| `favourites_count`             | integer                  | Total de curtidas dadas pela conta                  |
| `tweets_count`                 | integer                  | Total de publicações                                |
| `media_count`                  | integer                  | Total de itens de mídia publicados                  |
| `profile_image_url`            | string                   | URL do avatar                                       |
| `profile_background_image_url` | string                   | URL do banner                                       |
| `bio_urls`                     | array de strings ou null | URLs da bio                                         |
| `pinned_tweet_ids`             | array de strings ou null | IDs de publicações fixadas                          |
| `verified`                     | boolean                  | Status de verificação (selo azul, dourado ou cinza) |
| `can_dm`                       | boolean                  | Se mensagens diretas estão abertas                  |
| `protected`                    | boolean                  | Se a conta é privada                                |
| `possibly_sensitive`           | boolean                  | Se a conta tem marcação de conteúdo sensível        |

## Objeto Follower

Estende User com um campo adicional. É usado por `/new-followers-7d`, `/new-following-7d` e `/top-following`. `/top-followers` retorna outro modelo compacto com `score`.

| Campo adicional | Tipo   | Descrição                                      |
| :-------------- | :----- | :--------------------------------------------- |
| `followerDate`  | string | Data em que a relação de seguir foi registrada |

## Objeto Tweet

Contém conteúdo, metadados, métricas e relações de uma publicação. É retornado por `/tweet-info` e nas listas de publicações.

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

**Conteúdo**

| Campo        | Tipo   | Descrição                                     |
| :----------- | :----- | :-------------------------------------------- |
| `id`         | string | ID permanente (Snowflake)                     |
| `full_text`  | string | Texto completo da publicação                  |
| `created_at` | string | Data e hora de criação                        |
| `lang`       | string | Código do idioma detectado, como en, ja ou es |

**Métricas de engajamento**

| Campo            | Tipo    | Descrição              |
| :--------------- | :------ | :--------------------- |
| `likes_count`    | integer | Total de curtidas      |
| `retweet_count`  | integer | Total de repostagens   |
| `reply_count`    | integer | Total de respostas     |
| `quote_count`    | integer | Total de citações      |
| `view_count`     | integer | Total de visualizações |
| `bookmark_count` | integer | Total de salvamentos   |

**Contexto de conversa e resposta**

| Campo                  | Tipo           | Descrição                            |
| :--------------------- | :------------- | :----------------------------------- |
| `conversation_id_str`  | string         | ID da publicação inicial da conversa |
| `in_reply_to_tweet_id` | string ou null | ID da publicação respondida          |
| `in_reply_to_username` | string ou null | Nome de usuário da conta respondida  |
| `is_reply`             | boolean        | Se a publicação é uma resposta       |
| `is_quote_status`      | boolean        | Se a publicação cita outra           |
| `is_replies_limited`   | boolean        | Se o autor restringiu as respostas   |

**Objetos aninhados**

| Campo              | Tipo                 | Descrição                                                   |
| :----------------- | :------------------- | :---------------------------------------------------------- |
| `user`             | objeto User          | Perfil completo do autor                                    |
| `entities`         | array de TweetEntity | Mídias e links anexados                                     |
| `quoted_status`    | objeto Tweet ou null | Publicação citada (objeto completo e recursivo)             |
| `retweeted_status` | objeto Tweet ou null | Publicação original repostada (objeto completo e recursivo) |

`quoted_status` e `retweeted_status` contêm objetos Tweet completos, com `user`, `entities` e métricas próprios. Você recebe os dados relacionados na mesma chamada.

## Objeto TweetEntity

Cada item de `entities` representa uma mídia ou um link incorporado.

```text theme={null}
{
  "type": "photo",
  "link": "https://pbs.twimg.com/media/..._large.jpg",
  "preview": "https://pbs.twimg.com/media/..._small.jpg"
}
```

| Campo     | Tipo   | Descrição                                                 |
| :-------- | :----- | :-------------------------------------------------------- |
| `type`    | string | Tipo de entidade, como `photo`, `video` ou `animated_gif` |
| `link`    | string | URL direta do arquivo em resolução completa               |
| `preview` | string | Texto de prévia ou URL da miniatura                       |

## Paginação por cursor

Listas paginadas usam cursores. Consultas em lote e as listas de análise cripto acima não usam cursor. Essa abordagem é mais confiável que offsets em feeds que recebem conteúdo continuamente.

1. Envie a primeira requisição sem cursor.
2. A resposta inclui `next_cursor` junto aos dados.
3. Envie esse valor na próxima chamada.
4. Quando `next_cursor` for nulo ou ausente, os dados terminaram.

**GET:** envie o cursor como parâmetro de consulta.

```text theme={null}
curl --request GET \
  --url 'https://api.sorsa.io/v3/followers?username=elonmusk&next_cursor=abc123' \
  --header 'ApiKey: YOUR_API_KEY'
```

**POST:** envie no corpo JSON.

```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: percorrendo os seguidores**

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

Veja estratégias e desempenho em [paginação](https://docs.sorsa.io/pt-BR/pagination).

## Próximos passos

* [Paginação](https://docs.sorsa.io/pt-BR/pagination): padrões avançados e boas práticas.
* [Códigos de erro](https://docs.sorsa.io/pt-BR/error-codes): estrutura dos erros.
* [Referência da API](https://docs.sorsa.io/pt-BR/api-reference-guide): esquemas e exemplos.