Expansions da API do Twitter e autores de tweets

#O que são as expansions da API do Twitter e o que elas devolvem

Uma expansion é um parâmetro de requisição da API v2 oficial do X que acrescenta à resposta um objeto relacionado, como o autor, uma foto ou um post citado. Sem ela, a consulta de um post devolve três campos: id, text e edit_history_tweet_ids. O autor não está lá, nem sequer o ID do autor.

Com expansions=author_id, cada post ganha um author_id, e a resposta ganha uma lista includes.users com uma entrada por autor. Por padrão, essa entrada traz apenas id, name e username. Qualquer outra coisa, como a bio, as contagens de seguidores ou o avatar, precisa ser nomeada em user.fields.

A lista abaixo traz as expansions de post que os desenvolvedores mais usam e quanto cada uma custa nos preços da API do X em vigor a partir de 22 de novembro de 2026. Cada objeto de usuário custa o dobro do post que veio com ele.

• author_id

  Acrescenta a includes

  O autor do post

  API oficial do X, por objeto a partir de 22 de nov.

  US$ 0,010

• referenced_tweets.id

  Acrescenta a includes

  O post citado, respondido ou repostado

  API oficial do X, por objeto a partir de 22 de nov.

  US$ 0,005

• referenced_tweets.id.author_id

  Acrescenta a includes

  O autor desse post

  API oficial do X, por objeto a partir de 22 de nov.

  US$ 0,010

• in_reply_to_user_id

  Acrescenta a includes

  A conta que está sendo respondida

  API oficial do X, por objeto a partir de 22 de nov.

  US$ 0,010

• entities.mentions.username

  Acrescenta a includes

  Cada conta mencionada

  API oficial do X, por objeto a partir de 22 de nov.

  US$ 0,010

• attachments.media_keys

  Acrescenta a includes

  Cada foto, vídeo ou GIF

  API oficial do X, por objeto a partir de 22 de nov.

  US$ 0,005

• attachments.poll_ids

  Acrescenta a includes

  A enquete

  API oficial do X, por objeto a partir de 22 de nov.

  US$ 0,005

• geo.place_id

  Acrescenta a includes

  O local marcado

  API oficial do X, por objeto a partir de 22 de nov.

  US$ 0,005

As tarifas vêm do aviso do X sobre a cobrança de expansions, de 23 de outubro de 2026 (abre em uma nova aba), que diz que os objetos devolvidos por expansions serão cobrados "at the standard PPU rate for that resource, the same as direct lookups" (à tarifa padrão de pagamento por uso daquele recurso, igual às consultas diretas). Antes dessa data, elas não custavam nada além do post.

#Obtenha cada tweet com o seu autor em uma chamada na Sorsa API

A Sorsa API, uma API e scraper do Twitter (X), devolve todo tweet com um objeto user dentro: o perfil público completo do autor, 19 campos, sem custo extra. Não há expansion para acrescentar, nem segunda lista para cruzar, nem cobrança por autor. Uma requisição com a sua chave de API devolve os tweets, e cada um já sabe quem o escreveu.

1. Obtenha uma chave. Cadastre-se e copie a chave de API do painel. Não há conta de desenvolvedor do X nem OAuth no caminho.

2. Envie até 100 links ou IDs de tweets. O POST /tweet-info-bulk (abre em uma nova aba) recebe uma lista de URLs de tweets ou IDs puros e os devolve em uma única resposta, sem paginação.

   curl -X POST "https://api.sorsa.io/v3/tweet-info-bulk" \
     -H "ApiKey: YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{"tweet_links": ["1849212213712385091",
          "https://x.com/kai_builds_tools/status/1849212213712385092"]}'
   

   {
     "tweets": [
       {
         "id": "1849212213712385091",
         "full_text": "Shipped the new export queue today.",
         "created_at": "2026-10-24T09:12:44Z",
         "likes_count": 214,
         "retweet_count": 31,
         "view_count": 18402,
         "user": {
           "id": "1592041833471827968",
           "username": "kai_builds_tools",
           "display_name": "Kai Builds",
           "description": "Data tooling for small teams.",
           "followers_count": 1840,
           "followings_count": 312,
           "tweets_count": 2291,
           "verified": false,
           "created_at": "2022-11-14T08:03:10Z",
           "location": "Lisbon",
           "profile_image_url": "https://pbs.twimg.com/profile_images/1/kai.jpg"
         }
       }
     ]
   }
   

   Ver resposta completa

3. Leia o autor direto de cada tweet. O perfil fica em tweet["user"], então um laço sobre os tweets é todo o código necessário.

   import requests
   
   URL = "https://api.sorsa.io/v3/tweet-info-bulk"
   HEADERS = {"ApiKey": "YOUR_API_KEY"}
   
   
   def tweets_with_authors(ids):
       for start in range(0, len(ids), 100):
           batch = ids[start:start + 100]
           r = requests.post(URL, headers=HEADERS,
                             json={"tweet_links": batch})
           r.raise_for_status()
           for tweet in r.json()["tweets"]:
               author = tweet["user"]
               yield (tweet["id"], author["username"],
                      author["followers_count"], tweet["full_text"])
   

   const URL = "https://api.sorsa.io/v3/tweet-info-bulk";
   const headers = {
     ApiKey: "YOUR_API_KEY",
     "Content-Type": "application/json",
   };
   
   async function tweetsWithAuthors(ids) {
     const rows = [];
     for (let i = 0; i < ids.length; i += 100) {
       const body = JSON.stringify({ tweet_links: ids.slice(i, i + 100) });
       const res = await fetch(URL, { method: "POST", headers, body });
       if (!res.ok) throw new Error(`HTTP ${res.status}`);
       for (const t of (await res.json()).tweets) {
         rows.push([t.id, t.user.username, t.user.followers_count]);
       }
     }
     return rows;
   }
   

Um 403 significa que a chave está ausente ou ficou sem requisições; um 429 significa mais de 20 requisições em um segundo, então espere um instante e tente de novo. Requisições com falha nunca são cobradas.

O mesmo objeto user acompanha os tweets de busca, timelines, respostas e quotes. O POST /search-tweets (abre em uma nova aba) devolve cerca de 20 tweets por página com os seus autores, busca posts públicos desde 2006 com os operadores de busca do X e devolve um next_cursor para a página seguinte, até o cursor voltar vazio.

#Associe posts a autores na API oficial do X

Para associar posts a autores na API oficial do X, monte um dicionário de includes.users indexado pelo ID do usuário e depois consulte nele o author_id de cada post. O guia de expansions (abre em uma nova aba) do X observa que os objetos em includes não têm posição, então o ID é o único elo entre as duas listas.

curl -G "https://api.x.com/2/tweets" \
  -H "Authorization: Bearer YOUR_BEARER_TOKEN" \
  --data-urlencode "ids=1849212213712385091,1849212213712385092" \
  --data-urlencode "expansions=author_id" \
  --data-urlencode "user.fields=description,public_metrics,profile_image_url"

{
  "data": [
    {
      "id": "1849212213712385091",
      "text": "Shipped the new export queue today.",
      "author_id": "1592041833471827968",
      "edit_history_tweet_ids": ["1849212213712385091"]
    },
    {
      "id": "1849212213712385092",
      "text": "Next up: retries with backoff.",
      "author_id": "1592041833471827968",
      "edit_history_tweet_ids": ["1849212213712385092"]
    }
  ],
  "includes": {
    "users": [
      {
        "id": "1592041833471827968",
        "name": "Kai Builds",
        "username": "kai_builds_tools",
        "description": "Data tooling for small teams.",
        "public_metrics": {"followers_count": 1840, "following_count": 312}
      }
    ]
  }
}

Dois posts, um autor: includes.users lista cada autor uma vez por resposta, não uma vez por post. É por isso que a lista costuma ser mais curta que data, e por isso indexá-la por posição, ou ler includes["users"]["username"] como se fosse um único objeto, quebra. O laço abaixo percorre os resultados de uma busca recente e mantém um único dicionário de autores entre as páginas.

import requests

URL = "https://api.x.com/2/tweets/search/recent"
HEADERS = {"Authorization": "Bearer YOUR_BEARER_TOKEN"}
params = {
    "query": "from:kai_builds_tools",
    "max_results": 100,
    "expansions": "author_id",
    "user.fields": "description,public_metrics,profile_image_url",
}

authors, rows = {}, []
while True:
    page = requests.get(URL, headers=HEADERS, params=params).json()
    for user in page.get("includes", {}).get("users", []):
        authors[user["id"]] = user
    for post in page.get("data", []):
        author = authors.get(post["author_id"], {})
        rows.append((post["id"], author.get("username"), post["text"]))
    token = page.get("meta", {}).get("next_token")
    if not token:
        break
    params["next_token"] = token

Use .get() no autor: uma conta suspensa ou bloqueada pode faltar em includes enquanto o seu post continua em data, e a resposta então lista a lacuna em um array errors.

O autor de um retweet ou de um quote

Um repost ou um quote é um post que aponta para outro post, e o seu author_id é de quem repostou ou citou, não do autor original. Para obter também o autor original, peça três expansions: author_id, referenced_tweets.id e referenced_tweets.id.author_id. O post original cai em includes.tweets, o seu autor cai em includes.users ao lado de quem repostou, e você os associa por referenced_tweets[0].id e depois pelo author_id desse post. A partir de 22 de novembro, esse único repost cobra dois posts e dois usuários: US$ 0,030.

Na Sorsa API, o tweet repostado volta como retweeted_status e o citado como quoted_status, cada um um tweet completo com o seu próprio user dentro.

#O que as expansions custam a partir de 22 de novembro de 2026

A partir de 22 de novembro de 2026, todo objeto que uma expansion acrescenta é cobrado como uma leitura direta: US$ 0,010 por usuário e US$ 0,005 por post, foto, vídeo, enquete ou local. Um post lido com o seu autor passa a custar, portanto, até US$ 0,015, três vezes os US$ 0,005 que custava antes. Acrescente uma foto por post e o post custa até US$ 0,020; acrescente também o post citado e o seu autor, e chega a US$ 0,035.

O X deduplica dentro de um dia UTC de 24 horas: segundo a sua página de preços de pagamento por uso (abre em uma nova aba), um recurso buscado de novo no mesmo dia não é cobrado outra vez. Um usuário que escreveu 50 dos seus posts naquele dia é cobrado uma vez. Assim, 1.000 posts de 200 autores diferentes custam US$ 5,00 pelos posts e US$ 2,00 pelos autores, US$ 7,00 no total; 1.000 posts de 1.000 autores custam US$ 15,00. A deduplicação é zerada à meia-noite UTC, e o X a chama de garantia branda.

Na Sorsa API, o preço não muda com o que um tweet traz. Tweets por ID custam a partir de US$ 0,014 por 1.000 com seus autores, posts citados e links de mídia dentro; resultados de busca custam a partir de US$ 0,07 por 1.000. Contra os US$ 15,00 por 1.000 posts com autores na API oficial do X, isso é cerca de 1.000 vezes menos.

• Só os posts

  Sorsa API

  a partir de US$ 0,014

  API oficial do X a partir de 22 de nov.

  US$ 5,00

• Posts com seus autores

  Sorsa API

  a partir de US$ 0,014

  API oficial do X a partir de 22 de nov.

  até US$ 15,00

• Mais uma foto ou vídeo cada

  Sorsa API

  a partir de US$ 0,014

  API oficial do X a partir de 22 de nov.

  até US$ 20,00

• Mais o post citado e o seu autor

  Sorsa API

  a partir de US$ 0,014

  API oficial do X a partir de 22 de nov.

  até US$ 35,00

A calculadora precifica um mês de posts com as expansions que você usa. Ela conta todo autor como novo, o topo da faixa; escolha autores repetidos para ver o efeito da deduplicação.

Bom saber

O plano de pagamento por uso do X para em 3 milhões de leituras de posts por mês; além disso, a API oficial do X é um contrato Enterprise a partir de cerca de US$ 42.000 por mês. Na Sorsa API, o preço por 1.000 tweets cai à medida que o plano cresce, e o autor faz parte de todo tweet em todos os planos.

#Por que o autor deixou de ficar dentro do tweet

O autor já foi parte do tweet. No formato v1.1, todo objeto de tweet trazia um objeto user com o perfil do autor, de modo que um tweet era autossuficiente, como diz a documentação do twarc (abre em uma nova aba). A versão 2 da API, lançada em 2020, reduziu cada objeto a poucos campos padrão e moveu os objetos relacionados para includes, acessíveis apenas por expansions.

Até agora essa divisão custava código, mas não dinheiro: os objetos devolvidos por expansions não contavam no uso, então uma expansion apenas poupava uma segunda requisição. O aviso de outubro de 2026 mudou a parte do dinheiro. A partir de 22 de novembro, o autor que você associa de includes.users é cobrado como se você o tivesse consultado separadamente.

O tweet da Sorsa API se parece com o da v1.1 nesse ponto: o user fica dentro dele. O código escrito para a v1.1 que lê tweet["user"]["screen_name"] só precisa de um novo nome de chave, username; o guia para migrar da API do Twitter/X mapeia o restante de uma base de código da v2 endpoint por endpoint.

#Quais campos do autor vêm com cada tweet da Sorsa API

Cada tweet da Sorsa API traz 19 campos do autor em user, sem nada para solicitar. A tabela mapeia os que a maior parte do código precisa para os nomes da API oficial do X que você listaria em user.fields.

• username

  Nome em user.fields da API oficial do X

  username

• display_name

  Nome em user.fields da API oficial do X

  name

• description

  Nome em user.fields da API oficial do X

  description

• followers_count

  Nome em user.fields da API oficial do X

  public_metrics.followers_count

• followings_count

  Nome em user.fields da API oficial do X

  public_metrics.following_count

• tweets_count

  Nome em user.fields da API oficial do X

  public_metrics.tweet_count

• profile_image_url

  Nome em user.fields da API oficial do X

  profile_image_url

• created_at

  Nome em user.fields da API oficial do X

  created_at

• location

  Nome em user.fields da API oficial do X

  location

• verified

  Nome em user.fields da API oficial do X

  verified

• protected

  Nome em user.fields da API oficial do X

  protected

• pinned_tweet_ids

  Nome em user.fields da API oficial do X

  pinned_tweet_id

• bio_urls

  Nome em user.fields da API oficial do X

  entities.description.urls

Os outros seis são id, favourites_count, media_count, profile_background_image_url, can_dm e possibly_sensitive. Os IDs vêm como strings e as datas em ISO 8601. A lista completa do que tweets, perfis e outros objetos contêm está no guia sobre quais dados você obtém da API do Twitter.

Quando o seu ponto de partida é uma lista de IDs de tweets, o guia para reidratar IDs de tweets cobre listas de milhões, 100 IDs por requisição.

#Leia seus primeiros tweets com os autores

Na API oficial do X, o autor de um post é uma expansion: uma segunda lista para cruzar e, a partir de 22 de novembro de 2026, uma cobrança de US$ 0,010 por autor além dos US$ 0,005 do post. Para obter tweets com seus autores de uma vez, use a Sorsa API: o POST /tweet-info-bulk devolve 100 tweets por requisição, cada um com o perfil completo do autor dentro, a partir de US$ 0,014 por 1.000, a 20 requisições por segundo em todos os planos.

A Sorsa API nunca pede o seu login do X, então sua própria conta nunca corre risco, e é somente leitura por princípio: para postar, combine-a com a API oficial do X. Suas 100 requisições grátis leem os primeiros 10 mil tweets com os seus autores.

#Perguntas frequentes