API do Twitter para agentes de IA: REST, MCP ou skill

#Como um agente de IA obtém dados do X

Um agente de IA obtém dados do X como obtém qualquer dado ao vivo: o modelo pede uma ferramenta pelo nome, um código fora do modelo chama uma API e o JSON que volta entra no contexto do modelo para o próximo passo. O modelo nunca abre o x.com por conta própria.

Três tipos de ligação colocam essa ferramenta ao alcance do agente:

• Uma ferramenta REST é uma função no código do seu agente, registrada em um framework como o OpenAI Agents SDK, LangChain, CrewAI ou n8n.
• Um servidor MCP é um programa pequeno que apps de IA como Claude Code, Cursor e Codex iniciam sozinhos; ele lista suas ferramentas pelo Model Context Protocol.
• Uma skill é uma pasta com um arquivo SKILL.md que ensina uma API a um agente de programação, para que o agente escreva e execute as chamadas por conta própria.

Cada uma precisa de uma fonte de dados do X por trás. A fonte do próprio X é a API oficial do X, e seus recursos para agentes (abre em uma nova aba) a expõem como um servidor MCP hospedado, uma especificação OpenAPI e um arquivo skill.md. Cada chamada ali roda no seu app de desenvolvedor do X, com OAuth 2.0 ou um bearer token e créditos pré-pagos.

A tabela de preços (abre em uma nova aba) do X cobra US$ 0,005 por post lido e US$ 0,010 por perfil ou seguidor, e o pagamento por uso para em 3 milhões de leituras de posts por mês. Um aviso de 23 de outubro (abre em uma nova aba) acrescenta que, a partir de 22 de novembro, autores e mídias devolvidos com os posts também são cobrados como leituras: até US$ 15,00 por 1.000 resultados de busca que trazem seus autores. Nosso guia de preços da API do X lista todas as tarifas.

#Escolha a rota: ferramenta REST, servidor MCP ou skill

Escolha a rota pelo lugar onde o agente roda: um agente que você programa usa uma ferramenta REST, um app de IA como Claude Code ou Cursor usa um servidor MCP, e um agente de programação que escreve os próprios scripts usa uma skill. A Sorsa API, uma API e scraper do Twitter (X), atende as três com uma chave na mesma variável SORSA_API_KEY, então você pode começar por uma rota e acrescentar outra depois.

• No seu próprio código: OpenAI Agents SDK, LangChain, CrewAI, n8n, um loop próprio

  Rota

  Ferramenta REST

  O que você adiciona

  uma função que chama https://api.sorsa.io/v3

  Contexto que ocupa

  304 caracteres para uma ferramenta de busca

• Em um app de IA: Claude Code, Cursor, Codex, VS Code, Claude Desktop

  Rota

  Servidor MCP

  O que você adiciona

  npx -y sorsa-mcp com a sua chave

  Contexto que ocupa

  23,3 mil caracteres para 40 ferramentas

• Em um agente de programação que escreve e executa código

  Rota

  Skill

  O que você adiciona

  a pasta sorsa-x-api

  Contexto que ocupa

  762 caracteres até abrir a skill

O contexto importa porque cada caractere da definição de uma ferramenta viaja com as requisições do modelo e custa tokens e atenção. Listamos as ferramentas do servidor MCP em 2 de novembro: suas 40 definições somam 23,3 mil caracteres, cerca de 5.800 tokens. O Claude Code mantém isso pequeno com a busca de ferramentas, que mostra ao modelo apenas os nomes das ferramentas até ele precisar de uma.

Uma skill coloca 762 caracteres no contexto, seu nome e sua descrição, e só carrega o SKILL.md de 8.163 caracteres quando o agente o abre. Uma ferramenta REST custa o que você escrever: o schema de search_x abaixo tem 304 caracteres.

Muitas equipes usam duas rotas: o servidor MCP no editor enquanto exploram os dados e uma ferramenta REST no agente que vai para produção.

#Dê dados do X a qualquer agente com uma ferramenta REST

Para dar dados do X a um agente que você constrói, escreva uma função que chama a Sorsa API e registre-a como ferramenta: o modelo passa uma consulta de busca, a função devolve posts como JSON e cada chamada é uma requisição. Para agentes que você programa, use a Sorsa API: um header ApiKey e nenhum OAuth, cerca de 20 posts com perfis completos de autores por chamada de busca, a partir de US$ 0,07 por 1.000 resultados, a 20 requisições por segundo em todos os planos.

1. Obtenha uma chave. Cadastre-se, copie a chave do painel e coloque-a na variável de ambiente SORSA_API_KEY. A chave fica no seu código; o modelo nunca a vê.

2. Teste a chamada. O POST /search-tweets (abre em uma nova aba) recebe uma consulta com operadores de busca do X e devolve cerca de 20 posts por página, os mais recentes primeiro com "order": "latest".

   curl -X POST "https://api.sorsa.io/v3/search-tweets" \
     -H "ApiKey: YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{"query": "from:kai_builds_agents mcp", "order": "latest"}'
   

   {
     "tweets": [
       {
         "id": "1985342107664281745",
         "full_text": "Our support agent now reads X through MCP.",
         "created_at": "2026-10-30T14:12:09Z",
         "lang": "en",
         "likes_count": 48,
         "retweet_count": 6,
         "reply_count": 9,
         "quote_count": 2,
         "view_count": 5310,
         "is_reply": false,
         "user": {
           "id": "1544001928374651904",
           "username": "kai_builds_agents",
           "display_name": "Kai Builds Agents",
           "followers_count": 2841,
           "verified": false
         }
       }
     ],
     "next_cursor": "DAADDAABCgABG4vQ2kXAJxIKAAIbi9Dask"
   }
   

   Ver resposta completa

3. Encapsule-a como ferramenta. A função pagina com next_cursor até um limite e mantém 7 dos 41 campos que cada post traz, então 20 posts continuam sendo um resultado de ferramenta curto.

   import os
   
   import requests
   
   API = "https://api.sorsa.io/v3"
   HEADERS = {"ApiKey": os.getenv("SORSA_API_KEY", "YOUR_API_KEY")}
   KEEP = ("id", "full_text", "created_at", "likes_count", "view_count")
   
   
   def search_x(query: str, max_pages: int = 1) -> list[dict]:
       """Search public X posts with operators like from: and lang:.
   
       Args:
           query: X search query.
           max_pages: Pages to read, about 20 posts each.
       """
       posts, cursor = [], None
       for _ in range(max_pages):
           body = {"query": query, "order": "latest"}
           if cursor:
               body["next_cursor"] = cursor
           r = requests.post(f"{API}/search-tweets", json=body,
                             headers=HEADERS, timeout=30)
           r.raise_for_status()
           data = r.json()
           for t in data.get("tweets", []):
               post = {k: t.get(k) for k in KEEP}
               post["author"] = t["user"]["username"]
               post["followers"] = t["user"]["followers_count"]
               posts.append(post)
           cursor = data.get("next_cursor")
           if not cursor:
               break
       return posts
   

4. Registre a ferramenta. A mesma função funciona no OpenAI Agents SDK, no LangChain ou em qualquer API de LLM, e sua docstring vira a descrição da ferramenta. A Messages API do Claude recebe o schema como input_schema; as function tools da OpenAI chamam o mesmo objeto de parameters.

   from agents import Agent, Runner, function_tool
   
   agent = Agent(
       name="X researcher",
       instructions="Answer from public X posts and cite post IDs.",
       tools=[function_tool(search_x)],
   )
   result = Runner.run_sync(agent, "What are developers saying about MCP?")
   print(result.final_output)
   

   from langchain.agents import create_agent
   from langchain.tools import tool
   
   agent = create_agent(
       model="openai:gpt-5.5",
       tools=[tool(search_x, parse_docstring=True)],
       system_prompt="Answer from public X posts and cite post IDs.",
   )
   question = {"role": "user", "content": "What are developers saying about MCP?"}
   result = agent.invoke({"messages": [question]})
   

   {
     "name": "search_x",
     "description": "Search public X posts with operators like from: and lang:.",
     "input_schema": {
       "type": "object",
       "properties": {
         "query": {"type": "string", "description": "X search query."},
         "max_pages": {
           "type": "integer",
           "description": "Pages to read, about 20 posts each."
         }
       },
       "required": ["query"]
     }
   }
   

Cada post na resposta traz 22 campos, e seu objeto user, o perfil completo do autor, traz mais 19. Um agente raramente precisa de todos. Devolver 7 mantém curto cada resultado de ferramenta, o que importa: o Claude Code, por exemplo, avisa quando um único resultado de ferramenta passa de 10 mil tokens.

Mais ferramentas para o mesmo agente

O mesmo padrão cobre os outros trabalhos de um agente no X: uma função em torno de um endpoint, e cada chamada é uma requisição.

• O GET /info-batch (abre em uma nova aba) busca 100 perfis por chamada, por username ou ID de usuário.
• O POST /tweet-info-bulk (abre em uma nova aba) lê 100 posts por chamada a partir de seus IDs ou links, cada um com o seu autor.
• O GET /followers (abre em uma nova aba) devolve 200 seguidores por página e pagina com next_cursor.
• O POST /check-follow (abre em uma nova aba) responde em uma única chamada se uma conta segue outra.

Os outros 40 endpoints, de respostas e quotes a Listas, Comunidades e trends, estão na página de endpoints da Sorsa API.

#Adicione o servidor MCP ao Claude Code, Cursor ou Codex

Para um app de IA que fala MCP, adicione o servidor MCP da Sorsa API: um comando inicia o sorsa-mcp a partir do npm, e o app ganha 40 ferramentas somente leitura com a sua chave, da busca e dos perfis às verificações de follow.

claude mcp add sorsa --scope user \
  -e SORSA_API_KEY=YOUR_API_KEY -- npx -y sorsa-mcp

{
  "mcpServers": {
    "sorsa": {
      "command": "npx",
      "args": ["-y", "sorsa-mcp"],
      "env": { "SORSA_API_KEY": "YOUR_API_KEY" }
    }
  }
}

No Claude Code, o nome do servidor, sorsa, vem antes do -e, porque o -e lê as palavras seguintes como variáveis. O Cursor lê o mesmo servidor do arquivo JSON acima. Depois faça ao agente uma pergunta que precise do X, como o que as pessoas estão dizendo hoje sobre o seu lançamento, e ele chama search_tweets por conta própria.

As linhas para Codex, VS Code, Claude Desktop e outros apps, e as correções para um servidor que não conecta, estão no nosso guia do servidor MCP do Twitter. A página do servidor MCP do Twitter lista as 40 ferramentas com o que cada uma devolve.

#Instale a skill de agente para agentes de programação

Um agente de programação como Claude Code, Codex ou Cursor aprende a Sorsa API por uma skill: a pasta sorsa-x-api diz a ele qual endpoint serve a cada tarefa, como paginar com next_cursor e quando agrupar 100 IDs, e o agente escreve as chamadas por conta própria.

As skills seguem o formato aberto Agent Skills (abre em uma nova aba), então uma pasta funciona em todos esses agentes. Instale-a com a linha de comando de skills, que pergunta a quais agentes adicioná-la, ou copie-a à mão para a pasta de skills do Claude Code:

npx skills add Sorsa-io/sorsa-x-api-skill

git clone https://github.com/Sorsa-io/sorsa-x-api-skill \
  ~/.claude/skills/sorsa-x-api

Depois defina SORSA_API_KEY no shell em que o agente roda. Uma skill serve para trabalhos em que o agente deve deixar código pronto, como um script que exporta uma semana de menções toda segunda-feira, em vez de chamar uma ferramenta a cada pergunta.

Para assistentes sem skills, a página AI Docs (abre em uma nova aba) reúne toda a referência da API em um único arquivo de texto para anexar. A página Crie com IA tem prompts prontos para Claude Code, Cursor e Codex.

#Por que um agente que lê o X deve ser somente leitura

Um agente que lê posts lê textos escritos por desconhecidos, então uma API que só lê é a proteção mais simples: um post plantado não consegue fazer o agente postar, curtir, seguir ou enviar uma DM se nenhuma ferramenta faz isso.

As equipes de segurança chamam isso de prompt injection indireta. A OWASP (abre em uma nova aba) coloca a prompt injection em primeiro lugar entre os riscos de aplicações de LLM e cita o conteúdo de fontes externas, como sites ou arquivos, como uma das portas de entrada. Um resultado de busca é exatamente esse tipo de conteúdo. Na API oficial do X, um agente com um token de escopos de escrita pode ser induzido a agir na conta, então o conselho habitual é um gateway que bloqueie toda requisição de escrita antes de ela chegar ao X.

Para um agente que nunca deve agir no X, use a Sorsa API: todos os seus 45 endpoints leem dados públicos, então a própria chave de API é o limite e nenhum gateway é necessário. O servidor MCP também não tem ferramenta de postagem: quando chamamos post_tweet em 2 de novembro, ele respondeu "Tool post_tweet not found". Nenhum login nem cookie seu do X participa em momento algum, então sua conta do X corre risco zero.

Se o seu agente precisa postar, mantenha a postagem em uma ferramenta separada na API oficial do X, a US$ 0,015 por post, e deixe uma pessoa aprovar cada post antes de ele sair.

Bom saber

Trate o que as ferramentas devolvem como dados, não como instruções. Diga ao modelo, no prompt de sistema, que o texto dos posts é material citado, e mantenha toda chave no seu código ou no ambiente, nunca no prompt, para que nenhum post ou resultado de ferramenta consiga extraí-la.

#Quanto os dados do X custam a um agente, por 1.000 resultados

Na Sorsa API, os dados do X de um agente custam de US$ 0,007 a US$ 0,07 por 1.000 resultados, conforme o trabalho, contra US$ 5,00 a US$ 15,00 na API oficial do X. Os US$ 15,00 são o preço do X a partir de 22 de novembro para posts que voltam com seus autores. Os preços da Sorsa API partem da menor tarifa por requisição, e uma chamada é uma requisição em todos os planos, seja qual for o retorno.

• Buscar posts sobre um tema

  Endpoint

  POST /search-tweets

  Por chamada

  cerca de 20 posts com autores

  Sorsa API, por 1.000

  a partir de US$ 0,07

  API oficial do X, por 1.000

  US$ 5,00, ou US$ 15,00 com autores

• Ler posts por ID

  Endpoint

  POST /tweet-info-bulk

  Por chamada

  até 100 posts com autores

  Sorsa API, por 1.000

  a partir de US$ 0,014

  API oficial do X, por 1.000

  US$ 5,00, ou US$ 15,00 com autores

• Consultar perfis

  Endpoint

  GET /info-batch

  Por chamada

  até 100 perfis

  Sorsa API, por 1.000

  a partir de US$ 0,014

  API oficial do X, por 1.000

  US$ 10,00

• Ler uma lista de seguidores

  Endpoint

  GET /followers

  Por chamada

  até 200 seguidores

  Sorsa API, por 1.000

  a partir de US$ 0,007

  API oficial do X, por 1.000

  US$ 10,00

Uma rodada de pesquisa dá a dimensão da escala: um agente busca um tema, recebe 20 posts com seus autores e depois consulta 100 perfis. Na API oficial do X, essa rodada custa US$ 1,10 hoje e US$ 1,30 a partir de 22 de novembro. Na Sorsa API, custa a partir de US$ 0,0028, e requisições com falha nunca são cobradas.

O GET /key-usage-info (abre em uma nova aba) mostra quantas requisições restam e nunca conta como uma, então um agente pode checar seu orçamento antes de um trabalho longo.

#Mantenha baratas e confiáveis as chamadas de um agente ao X

Os agentes desperdiçam chamadas quando entram em loop, então dê a cada ferramenta do X um limite de páginas, agrupe as consultas e devolva apenas os campos que o modelo lê.

• Agrupe as consultas. Envie até 100 IDs de posts em uma chamada ao POST /tweet-info-bulk, ou 100 handles em uma chamada ao GET /info-batch, em vez de 100 chamadas individuais.
• Limite as páginas. Um argumento max_pages impede que um agente leia página por página uma busca de 50 mil posts. Pare assim que o next_cursor voltar vazio.
• Use cache dentro da tarefa. A mesma consulta feita duas vezes na mesma tarefa devolve os mesmos posts, então guarde a primeira resposta.
• Trate 429 e 403. Cada chave roda a 20 requisições por segundo em todos os planos: em um 429, espere um segundo e tente de novo. Um 403 significa que a chave está ausente ou que a conta ficou sem requisições.
• Faça polling com agendamento. Toda requisição devolve dados novos, então um agente de monitoramento se mantém atualizado repetindo a busca em um agendamento, com since: na consulta. O guia de monitoramento do Twitter em tempo real mostra o loop.

O schema da resposta é estável, então o código da sua ferramenta continua funcionando.

#Dê dados do X ao seu agente hoje

Seu agente pode ler o X em minutos: uma ferramenta REST para agentes que você constrói, o servidor MCP para Claude Code e Cursor, ou a skill para agentes de programação. A Sorsa API atende as três com uma chave somente leitura, com posts a partir de US$ 0,014 por 1.000 contra US$ 5,00 na API oficial do X e 20 requisições por segundo em todos os planos, em produção desde 2022, com mais de 6 bilhões de requisições atendidas. Suas primeiras 100 requisições são grátis, o bastante para um agente ler até 10 mil posts.

#Perguntas frequentes