How to Use CrewAI with the Twitter (X) API

You need Python 3.10 or newer (the package requires it), a TwitterAPI.io API key and a key for the LLM your crew uses. crewAI 1.15.28 defaults to gpt-4.1-mini through OPENAI_API_KEY when an Agent has no llm=; pass llm="anthropic/..." or any other provider string supported by crewAI to change it.

crewai-twitterapi-io 0.1.0 depends on crewai>=0.100.0 and requests>=2.31 and nothing else, so it drops into an existing crew project. It reads the key from TWITTERAPI_IO_API_KEY, or you pass api_key="..." to each tool. If neither is set, the tool raises ValueError when you construct it, before any agent runs, which is the behavior you want in CI.

To get a key, sign in at the TwitterAPI.io dashboard with Google. Up to $1 in free credits for new accounts that pass the bot check; expires after 31 days; see /pricing. That is about 6,600 posts, enough to run the crew on this page many times.

The package exports exactly two classes. Both subclass crewAI's BaseTool, declare TWITTERAPI_IO_API_KEY as a required EnvVar, send the key as an X-API-Key header to https://api.twitterapi.io, and time out after 30 seconds.

Compact output. Each post comes back as 11 fields: id, url, text, created_at, lang, the four counts (like_count, retweet_count, reply_count, quote_count), view_count and an author object with username, name, followers and is_blue_verified. On our sample that averaged 230.7 tokens per post against 1,547.7 tokens for the full API object, 85.1% fewer tokens in the agent's context. The trade-off: there is no isReply flag, no quoted or reposted post and no media list, so the agent cannot tell a reply from an original post except by a leading @-mention. Push that filtering into the query instead (next sections).

Paging. The search tool follows next_cursor until it has max_results posts or the API says there is no next page, then truncates to max_results. A page can hold fewer than 20 posts (a Top page in our sample held 18), and then a max_results=20 call makes a second request. You pay for every post returned, including the extra ones the tool trims.

Errors. Network and HTTP errors do not raise. The tool returns {"success": false, "error": "..."} so the agent can decide what to do. If a later page fails, the posts from earlier pages are discarded, not returned. The user tool returns {"success": false, "error": "user not found"} for an unknown handle (the API answers HTTP 200 with status: "error").

Read only. Both tools only read. Posting, liking and following are separate TwitterAPI.io REST endpoints that you would call from your own code: one /twitter/user_login_v2 login ($0.10, through a proxy you supply) returns login_cookies, then each action is $0.002. Those calls act as that account, so X can rate-limit, lock or suspend it; keep a human pace, expect to log in again when the session ends, and note that each HTTP 200 call is billed. We do not recommend giving an autonomous crew write access to an account.

Here is the real output of TwitterApiIoSearchTool().run(query="from:github -filter:replies", max_results=2) on a response recorded for our study (the package code produced it; only the HTTP call was replayed, and we shortened the created_at timestamps):

The crew below has two agents in a sequential process. The researcher holds both X tools and returns a JSON list of 10 to 15 informative posts. The analyst has no tools at all: it receives the researcher's list through context=[collect] and writes brief.md. Splitting the work this way keeps raw post text away from the agent that writes, which matters for prompt injection (see below).

Three details do most of the work. First, the research task tells the model which queries to run, and those queries carry the filters that our study found most effective: lang:en -filter:replies min_faves:10 on Latest, plus one Top search. Second, two crewAI hooks wrap every call to the X tools: @before_tool_call clamps max_results to 20 (one request, $0.003, about 4,800 to 7,100 tokens of context), and @after_tool_call fences the output as untrusted data. Third, a guardrail on the brief task rejects any post URL the researcher never returned, which catches invented citations.

max_iter=6 caps the researcher's reasoning loop; crewAI's default is 25, and every extra iteration resends the growing conversation, including all tool output, to the LLM. {topic} placeholders in roles, goals and task descriptions are filled from crew.kickoff(inputs={...}).

We ran this file end to end with a scripted LLM and recorded API responses: the model asked for max_results: 100, the hook cut it to one request, the fence wrapped both search results, the analyst's first draft cited a URL that was not in the research list, the guardrail rejected it, and the retry passed with a real URL. With a real model the result object also reports token usage, which is where most of the cost of a run sits.

A search tool is only as useful as the posts it returns, and an agent cannot see what it did not ask for. So we ran 8 research queries the way a crew would, through /twitter/tweet/advanced_search, in five variants each, and labeled every post. Six queries are topics (crewai, "claude code", "ai agents", "mcp server", openai, "product hunt"); two are organization accounts (from:OpenAI, from:github). The pooled figures below are for the six topic queries.

We call a post brief-ready when an English-language research brief could quote it: not a repost, not a duplicate of a post already in the result, at least 8 words of its own text after links and @-mentions are removed, written in English and not a reply. Substantive replies and non-English posts are counted separately because some crews want them.

Replies are the noise, not reposts. In a plain Latest search, 45.0% of posts were replies. Not one of the 2,069 posts in any variant was a repost, and the -filter:retweets result overlapped the plain result by 99.15% (median per query). Search already leaves reposts out unless you ask for them, so the filter agents reach for first does nothing. -filter:replies is the one that moves the number, from 43.5% to 77.5% brief-ready.

Most of what Latest returns has no engagement. 67.0% of plain Latest posts had zero likes. min_faves:10 removed all of them, nearly removed replies (2.5%) and pushed the first page back from 11 minutes to a median of 2.7 hours of conversation. Top went furthest, 88.9% brief-ready, but its posts had a median age of 3.8 days, so it answers "what mattered this week", not "what is happening now".

Filters cut cost per useful post, not price. Every post returned costs the same $0.00015, so the cost per 100 brief-ready posts falls only because fewer posts are wasted: $0.0345 for the plain query against $0.0189 with min_faves:10 and $0.0169 with Top. The larger saving is in LLM tokens. A plain 100-post search put about 24,110 tokens of compact JSON into the researcher's context (241.1 tokens a post), and more than half of it was not brief-ready.

Language leaks in. 14.0% of plain Latest posts were not in English (28% for "claude code"). Removing replies raised the non-English share to 22.5%, because English replies were removed and other-language originals stayed. Add lang:en when the brief is in English.

You hear from many voices, briefly. The first 40 posts of a plain topic search came from a median of 33 distinct accounts, and the most frequent account supplied 1.8% of the pooled posts (at most 11% within one query). That is good for breadth, but on a busy term those voices cover a few minutes: the 100 newest posts for openai spanned 6.7 minutes.

The researcher's task description is where you control quality, because the model copies the query patterns you give it. The per-query numbers show why one recipe does not fit every topic.

Busy brand or model names (openai, "claude code", "ai agents"): use lang:en -filter:replies min_faves:10 or Top. A plain Latest search returns a few minutes of mostly zero-like replies; on openai only 27% was brief-ready.

Niche terms (crewai): plain Latest already reaches back about 6 days, and Top reaches further. Spend on Top plus a since: date rather than many Latest pages.

Organization accounts (from:OpenAI): an account's own replies are a large share (54% for OpenAI), and min_faves:10 does not remove them because those replies get likes. Use -filter:replies, which raised brief-ready to 90% for from:OpenAI and 95% for from:github, or give the agent TwitterApiIoUserTool for the timeline.

Launches and events: pin the window with since: and until: (since:YYYY-MM-DD) so that Latest and Top answer the same question. The full operator list is in Twitter search operators for the API.

Write these into the task description as literal queries, as in the crew above. Telling a model "find high-quality posts" without operators gets you the plain Latest column.

Anyone can post on X, and a search result puts their text straight into your agent's prompt. A post that says "ignore your instructions and ..." is indirect prompt injection, the first risk in the OWASP Top 10 for LLM applications. No prompt fully prevents it, so the crew on this page stacks four measures, all from crewAI's own API.

1. Fence tool output with a hook. crewAI 1.15 runs functions registered with @after_tool_call on every tool result and replaces the result with what they return. The fence_untrusted_posts hook wraps the JSON in <untrusted_x_data> tags, removes any copy of those tags from the post text so a post cannot close the fence early, and appends a reminder that the content is evidence, not instructions. The tools= filter takes the tool names (crewAI sanitizes them to search_tweets_on_x_twitter and get_an_x_twitter_users_profile_and_recent_tweets); you can filter by agent role with agents=["X research analyst"] instead, which also covers MCP tools.

2. Least privilege. The researcher has read tools only, and the analyst, the agent that produces the output, has none. A post cannot talk the analyst into calling a tool it does not have. Do not give the agent that reads raw posts any tool that sends email, writes files outside the crew or posts to X.

3. A guardrail on the output. urls_come_from_research compares the post URLs in the brief with the ones the researcher actually returned and fails the task if any are new, which catches injected links and invented citations. One crewAI detail we hit while testing: on a guardrail retry, crewAI 1.15 keeps the task description but replaces the context from earlier tasks with the error message and the rejected draft, so the analyst no longer sees the research list. The error must repeat what the agent needs (here, the allowed URLs). Our first version did not, and the retry failed three times.

4. Small inputs. The @before_tool_call hook caps max_results at 20. Fewer posts per call means less attacker-controlled text per prompt and lower cost.

Fencing lowers the risk; it does not remove it. Treat the brief as a draft for a human, and never let a crew act on X content (reply, follow, buy, merge) without review. For the MCP route, the same hooks apply: register them with agents=[...] because MCP tool names carry a server prefix.

crewAI 1.15 has a native MCP client: an Agent takes mcps=[...] with MCPServerHTTP, MCPServerSSE or MCPServerStdio configs from crewai.mcp, discovers the server's tools when the crew starts and exposes them like any other tool. We connected both TwitterAPI.io servers this way.

Hosted server. https://mcp.twitterapi.io/mcp over streamable HTTP, key in the X-API-Key header. crewAI listed all 12 read tools under prefixed names such as mcp_twitterapi_io_mcp_search_tweets. Local server. The npm package @twitterapi_io/mcp-server (0.2.0) runs over stdio with npx and reads TWITTERAPI_IO_API_KEY from its environment; crewAI merges the env you pass with the default environment, so PATH is kept.

Give a research agent only the tools it needs. create_static_tool_filter(allowed_tool_names=[...]) matches the server's own tool names (search_tweets, not the prefixed crewAI name); with the filter below, crewAI loaded exactly three tools from the local server.

Both routes read the same data at the same price. Pick the package when you want small, predictable tool calls, and the MCP server when the crew needs the wider tool set.

TwitterAPI.io charges 15 credits per post returned, which is $0.15 per 1,000 posts, with a minimum of 15 credits ($0.00015) per request; profiles are $0.18 per 1,000. The official X API pay-per-use plan charges $0.005 per post read and $0.010 per user read, capped at 3 million post reads a month before Enterprise. The rows below are arithmetic on those published rates, not a benchmark.

Per 1,000 posts that is $0.15 against $5.00, about 33x cheaper per read than the official X API pay-per-use rate. Because you pay per post returned, the filters in the study change the price of useful posts, not of posts: $0.0345 per 100 brief-ready posts for a plain Latest search, $0.0169 with Top.

The LLM usually costs more than the X data. Each 20-post search adds about 4,800 to 7,100 tokens of tool output (241.1 tokens a post for plain Latest results, 357.1 with min_faves:10, because liked posts are longer), and a ReAct-style agent resends the conversation on every iteration. Read result.token_usage after a run and multiply by your model's price. Capping max_results and max_iter lowers both bills at once.

For the full official price list see how much the X API costs in 2026; for plans and credits see TwitterAPI.io pricing.

TwitterAPI.io allows 0.2 requests/s before the first payment, 20 once paid (50 on Scale, 500 on Business). At 0.2 requests/s, one request every 5 seconds, two things in a crew can trip the limit.

Multi-page searches. TwitterApiIoSearchTool requests pages back to back with no pause. With max_results=100 it sends up to five requests in a row; on a never-paid account the second one can arrive inside 5 seconds and get HTTP 429. The tool then returns success: false and throws away the page it already paid for. Keep max_results at 20 or less until the account is paid; the cap_search_size hook enforces that.

Parallel agents. Several agents, or several crews in one process, share the key's limit. Keep X research in one agent, or run crews one after another.

With the MCP route the npm server retries 429 responses three times with 1, 2 and 4 seconds of backoff; each tool call is one page, so it is less likely to burst. After the first payment, 20 requests/s is far above what an LLM-paced crew sends. More on limits and error codes: Twitter rate limit exceeded.

You can also give a crew X data through the official X API v2: write a BaseTool subclass that calls the v2 recent-search endpoint with a bearer token, or wrap tweepy. crewai-tools has no X tool, so either way the tool code is yours. Here is how that route compares with the package on this page.

The official API is the right choice when you need X's own contractual terms or write access under your app's OAuth. For a research crew that reads public posts, it costs about 33 times more per post and adds an account, an app and a tool to maintain. X's pricing is on docs.x.com.

ValueError: TWITTERAPI_IO_API_KEY environment variable or api_key argument is required for TwitterApiIoSearchTool. The key is not in the environment of the process that builds the tools. Export it in the same shell, load it from .env before the import, or pass api_key=.

{"success": false, "error": "401 Client Error: Unauthorized ..."}. The key is wrong or revoked. Copy it again from the dashboard.

{"success": false, "error": "429 Client Error: Too Many Requests ..."}. You are over 0.2 requests/s on a never-paid account. Lower max_results to 20 and avoid parallel agents (see the rate-limit section).

{"success": false, "error": "user not found"} from the user tool. The handle is wrong or the account was renamed. Search for the name first, then use the current handle.

The hook never runs. The tools= filter compares sanitized names. Pass the tool's name attribute (crewAI sanitizes it for you) or filter with agents=[role]. MCP tools have server-prefixed names.

Task failed guardrail validation after 3 retries. On a retry the earlier tasks' output is replaced by your error message and the rejected draft. Put everything the agent needs to fix the output into the error string.

MCP: no tools, or the wrong tools. tool_filter takes the server's own names (search_tweets). crewAI shows them prefixed (mcp_twitterapi_io_mcp_search_tweets). For the stdio server, Node.js and npx must be on PATH.

The brief is full of replies or other languages. The model is sending plain queries. Put lang:en -filter:replies min_faves:10 into the task description as a literal query.

The researcher keeps searching. Lower max_iter, state the number of searches in the task, and make expected_output concrete ("10 to 15 posts"), so the model knows when it is done.

Question. When a crewAI research agent searches X with a typical research query, how much of the result is usable, how many accounts does it hear from, how much time does it cover, how many tokens does it add to the context, and how much do -filter:retweets, -filter:replies, min_faves:10 and Top change the useful yield and the cost per useful post?

Queries. 8 queries written down before collection: crewai, "claude code", "ai agents", "mcp server", openai, "product hunt", from:OpenAI and from:github. Each ran as a plain Latest search (5 pages, matching the tool's max_results=100), with -filter:retweets (3 pages), with -filter:retweets min_faves:10 (2 pages) and as a plain Top search (2 pages). After the first pass showed no reposts at all, we added one page per query with -filter:replies.

Method. /twitter/tweet/advanced_search, the endpoint TwitterApiIoSearchTool calls, through a rate-limited read-only client. 104 requests, 2,069 posts (1,281 unique; the variants overlap by design). Collected in 2026.

Labels. Repost: a reposted post is attached or the text starts with "RT @". Reply: X's reply flag. Duplicate: the same text, after removing links, @-mentions and spacing, as an earlier post in the same result. Near-empty: fewer than 8 words of the author's own text after removing links and @-mentions. Brief-ready: none of those, English and not a reply. Tokens: tiktoken o200k_base on the exact compact JSON the package produces per post. Cost: 15 credits per post returned, at least 15 per request.

What this sample cannot show. It is one moment in 2026: Latest results change by the minute, and a launch day would look different. The topics lean to AI and developer tools; consumer, sports or political topics will have different reply and language mixes. "Brief-ready" is a mechanical label, not a judgment of accuracy or relevance, and an 8-word floor keeps some low-value posts. The -filter:replies variant is one page per query (120 topic posts), so treat its numbers as indicative. We report aggregates only: no private individual is named or quoted, and the only posts shown are from an organization account.

The protocol, the raw responses, the analysis script and every number on this page are kept with the study (data/studies/how-to-use-crewai-with-twitter-api/: protocol.json, analyze.py, results.json).