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.

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

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

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

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

{
  "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.

{
  "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.

{
  "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.

{
  "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.

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

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

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.

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

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.

Próximos passos

Paginação: padrões avançados e boas práticas.
Códigos de erro: estrutura dos erros.
Referência da API: esquemas e exemplos.

Primeiros passos

Conceitos básicos

Guias práticos

Suporte e recursos

Formato de resposta

Formato de resposta: esquemas de User e Tweet

Convenções

Estruturas de resposta

Objeto User

Objeto Follower

Objeto Tweet

Objeto TweetEntity

Paginação por cursor

Próximos passos

​Formato de resposta: esquemas de User e Tweet

​Convenções

​Estruturas de resposta

​Objeto User

​Objeto Follower

​Objeto Tweet

​Objeto TweetEntity

​Paginação por cursor

​Próximos passos

Formato de resposta: esquemas de User e Tweet

Convenções

Estruturas de resposta

Objeto User

Objeto Follower

Objeto Tweet

Objeto TweetEntity

Paginação por cursor

Próximos passos