Twitter API for AI agents: REST, MCP or a skill

#How an AI agent gets X data

An AI agent gets X data the way it gets any live data: the model asks for a tool by name, code outside the model calls an API, and the JSON that comes back goes into the model's context for its next step. The model never opens x.com itself.

Three kinds of wiring put that tool within the agent's reach:

• A REST tool is a function in your agent's code, registered with a framework such as the OpenAI Agents SDK, LangChain, CrewAI or n8n.
• An MCP server is a small program that AI apps such as Claude Code, Cursor and Codex start on their own; it lists its tools over the Model Context Protocol.
• A skill is a folder with a SKILL.md file that teaches a coding agent an API, so the agent writes and runs the calls itself.

Each of them needs a source of X data behind it. X's own source is the official X API, and its agent resources (opens in a new tab) expose it as a hosted MCP server, an OpenAPI spec and a skill.md file. Every call there runs on your X developer app, with OAuth 2.0 or a bearer token and prepaid credits.

X's price list (opens in a new tab) charges $0.005 per post read and $0.010 per profile or follower, and pay-per-use stops at 3 million post reads a month. A notice of October 23 (opens in a new tab) adds that from November 22, authors and media returned with posts are billed as reads too: up to $15.00 per 1,000 search results that carry their authors. Our X API pricing guide lists every rate.

#Pick the route: a REST tool, an MCP server or a skill

Pick the route by where the agent runs: an agent you code takes a REST tool, an AI app such as Claude Code or Cursor takes an MCP server, and a coding agent that writes its own scripts takes a skill. Sorsa API, a Twitter (X) API and scraper, serves all three with one key in the same SORSA_API_KEY variable, so you can start with one route and add another later.

• Your own code: OpenAI Agents SDK, LangChain, CrewAI, n8n, a custom loop

  Route

  REST tool

  What you add

  a function that calls https://api.sorsa.io/v3

  Context it takes

  304 characters for a search tool

• An AI app: Claude Code, Cursor, Codex, VS Code, Claude Desktop

  Route

  MCP server

  What you add

  npx -y sorsa-mcp with your key

  Context it takes

  23.3K characters for 40 tools

• A coding agent that writes and runs code

  Route

  Skill

  What you add

  the sorsa-x-api folder

  Context it takes

  762 characters until it opens the skill

Context matters because every character of a tool's definition travels with the model's requests, and it costs tokens and attention. We listed the MCP server's tools on November 2: its 40 definitions come to 23.3K characters, about 5,800 tokens. Claude Code keeps that small with tool search, which shows the model only tool names until it needs one.

A skill puts 762 characters into context, its name and description, and loads the 8,163-character SKILL.md only when the agent opens it. A REST tool costs what you write: the search_x schema below is 304 characters.

Many teams run two routes: the MCP server in the editor while they explore the data, and a REST tool in the agent that ships.

#Give any agent X data with a REST tool

To give an agent you build X data, write one function that calls Sorsa API and register it as a tool: the model passes a search query, the function returns posts as JSON, and each call is one request. For agents you code, use Sorsa API: one ApiKey header and no OAuth, about 20 posts with full author profiles per search call, from $0.07 per 1,000 results, at 20 requests per second on every plan.

1. Get a key. Sign up, copy the key from the dashboard and put it in the SORSA_API_KEY environment variable. The key stays in your code; the model never sees it.

2. Try the call. POST /search-tweets (opens in a new tab) takes a query with X search operators and returns about 20 posts per page, newest first with "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"
   }
   

   Show full response

3. Wrap it as a tool. The function pages with next_cursor up to a budget and keeps 7 of the 41 fields each post carries, so 20 posts stay a short tool result.

   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. Register the tool. The same function works in the OpenAI Agents SDK, LangChain or any LLM API, and its docstring becomes the tool's description. Claude's Messages API takes the schema as input_schema; OpenAI's function tools call the same object 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"]
     }
   }
   

Each post in the response carries 22 fields, and its user object, the author's full profile, carries 19 more. An agent rarely needs them all. Returning 7 keeps every tool result short, which matters: Claude Code, for one, warns when a single tool result passes 10K tokens.

More tools for the same agent

The same pattern covers the other jobs an agent does on X: one function around one endpoint, each call one request.

• GET /info-batch (opens in a new tab) looks up 100 profiles per call, by username or user ID.
• POST /tweet-info-bulk (opens in a new tab) reads 100 posts per call from their IDs or links, each with its author.
• GET /followers (opens in a new tab) returns 200 followers per page and pages with next_cursor.
• POST /check-follow (opens in a new tab) answers whether one account follows another in a single call.

The other 40 endpoints, from replies and quotes to Lists, Communities and trends, are on the Sorsa API endpoints page.

#Add the MCP server to Claude Code, Cursor or Codex

For an AI app that speaks MCP, add Sorsa API's MCP server: one command starts sorsa-mcp from npm, and the app gets 40 read-only tools on your key, from search and profiles to follow checks.

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

In Claude Code the server's name, sorsa, goes before -e, because -e reads the words after it as variables. Cursor reads the same server from the JSON file above. Then ask the agent a question that needs X, such as what people are saying about your launch today, and it calls search_tweets on its own.

Lines for Codex, VS Code, Claude Desktop and other apps, and fixes for a server that won't connect, are in our Twitter MCP server guide. The Twitter MCP server page lists all 40 tools with what each one returns.

#Install the agent skill for coding agents

A coding agent such as Claude Code, Codex or Cursor learns Sorsa API from a skill: the sorsa-x-api folder tells it which endpoint fits a task, how to page with next_cursor and when to batch 100 IDs, and the agent writes the calls itself.

Skills follow the open Agent Skills (opens in a new tab) format, so one folder works across these agents. Install it with the skills command line, which asks which agents to add it to, or copy it into Claude Code's skills folder by hand:

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

Then set SORSA_API_KEY in the shell the agent runs in. A skill suits jobs where the agent should leave code behind, such as a script that exports a week of mentions every Monday, rather than call a tool for every question.

For assistants without skills, the AI Docs (opens in a new tab) page holds the whole API reference in one text file to attach. The build with AI page has ready prompts for Claude Code, Cursor and Codex.

#Why an agent that reads X should be read-only

An agent that reads posts reads text written by strangers, so an API that can only read is the simplest safeguard: a planted post can't make the agent post, like, follow or send a DM when no tool can do it.

Security teams call this indirect prompt injection. OWASP (opens in a new tab) ranks prompt injection first among the risks of LLM applications and names content from outside sources, such as websites or files, as one way in. A search result is exactly that kind of content. On the official X API, an agent holding a token with write scopes can be steered into acting on the account, so the usual advice is a gateway that blocks every write request before it reaches X.

For an agent that must never act on X, use Sorsa API: all 45 of its endpoints read public data, so the API key itself is the boundary and no gateway is needed. The MCP server has no posting tool either: when we called post_tweet on November 2, it answered "Tool post_tweet not found". No X login or cookie of yours takes part at any point, so your X account carries zero risk.

If your agent must post, keep posting in a separate tool on the official X API, at $0.015 per post, and let a person approve each post before it goes out.

Good to know

Treat what the tools return as data, not instructions. Tell the model in its system prompt that post text is quoted material, and keep every key in your code or environment, never in the prompt, so no post or tool result can draw it out.

#What X data costs an agent, per 1,000 results

On Sorsa API an agent's X data costs from $0.007 to $0.07 per 1,000 results, depending on the job, against $5.00 to $15.00 on the official X API. The $15.00 is X's price from November 22 for posts that come back with their authors. Sorsa API's prices start at the lowest per-request rate, and one call is one request on every plan, whatever it returns.

• Search posts on a topic

  Endpoint

  POST /search-tweets

  Per call

  about 20 posts with authors

  Sorsa API, per 1,000

  from $0.07

  Official X API, per 1,000

  $5.00, or $15.00 with authors

• Read posts by ID

  Endpoint

  POST /tweet-info-bulk

  Per call

  up to 100 posts with authors

  Sorsa API, per 1,000

  from $0.014

  Official X API, per 1,000

  $5.00, or $15.00 with authors

• Look up profiles

  Endpoint

  GET /info-batch

  Per call

  up to 100 profiles

  Sorsa API, per 1,000

  from $0.014

  Official X API, per 1,000

  $10.00

• Read a follower list

  Endpoint

  GET /followers

  Per call

  up to 200 followers

  Sorsa API, per 1,000

  from $0.007

  Official X API, per 1,000

  $10.00

One research run makes the scale concrete: an agent searches a topic, gets 20 posts with their authors, then looks up 100 profiles. On the official X API that run costs $1.10 today and $1.30 from November 22. On Sorsa API it costs from $0.0028, and failed requests are never charged.

GET /key-usage-info (opens in a new tab) shows how many requests remain and never counts as one, so an agent can check its budget before a long job.

#Keep an agent's X calls cheap and reliable

Agents waste calls when they loop, so give every X tool a page budget, batch the lookups and return only the fields the model reads.

• Batch lookups. Send up to 100 post IDs in one POST /tweet-info-bulk call, or 100 handles in one GET /info-batch call, instead of 100 single calls.
• Budget the pages. A max_pages argument stops an agent from reading a 50K-post search page by page. Stop as soon as next_cursor comes back empty.
• Cache within a task. The same query asked twice in one task returns the same posts, so keep the first answer.
• Handle 429 and 403. Each key runs at 20 requests per second on every plan: on a 429, wait a second and retry. A 403 means the key is missing or the account is out of requests.
• Poll on a schedule. Every request returns fresh data, so a monitoring agent stays current by rerunning its search on a schedule with since: in the query. The guide to real-time Twitter monitoring shows the loop.

The response schema stays stable, so your tool code keeps working.

#Give your agent X data today

Your agent can read X within minutes: a REST tool for agents you build, the MCP server for Claude Code and Cursor, or the skill for coding agents. Sorsa API serves all three on one read-only key, with posts from $0.014 per 1,000 against $5.00 on the official X API and 20 requests per second on every plan, in production since 2022 with 6B+ requests served. Your first 100 requests are free, enough for an agent to read up to 10K posts.

#FAQ