Grok Agent: How to Build an Agent with Grok on Live Twitter (X) Data

Agents inside Grok: the multi-agent model. xAI's docs describe "Realtime Multi-agent Research" as a model variant, grok-4.20-multi-agent, that launches several agents to discuss a query while a leader agent synthesizes the final answer. Two setups exist, 4 agents and 16 agents, selected through the reasoning-effort parameter (low or medium effort runs 4, high or xhigh runs 16). All tokens used by the leader and the sub-agents are billed. The limitation that matters for builders is stated plainly in the same doc: client-side tools (function calling) and custom tools are not supported by the multi-agent variant; it works with the built-in tools (web_search, x_search) and remote MCP tools. So if you want your own tools, this is not the model to pick.

Agents inside Grok: Grok Build. Grok Build is xAI's coding agent, installed with a one-line script and started by typing grok in a project directory; it runs as an interactive terminal UI, headlessly (grok -p "...") or through the Agent Client Protocol inside other editors. It authenticates through the browser or an XAI_API_KEY, defaults to grok-4.7, and supports MCP servers. Press coverage of its launch in May 2026 called it xAI's first coding agent. It is an agent you use, not one you build.

"Grok Bot" and the agent-platform pages. Several high-ranking results for this keyword describe a hosted product where a user runs several specialized agents, each with its own cloud computer and memory, that log into services such as email or a CRM and act on the user's behalf. We could not verify its feature list on an xAI primary source this session, so we describe it only as what those pages claim. It is a product category, not an API.

Your own agent on the xAI API. This is what the rest of the page is about: a program that sends grok-4.7 a question plus a list of tools, executes the tool calls the model asks for, feeds the results back, and returns the model's answer. The tools can be functions you implement (this page), xAI's built-in server-side tools (web_search, x_search, code execution, collections search), or any remote MCP server reachable over Streamable HTTP or SSE. The table summarizes the four meanings.

Everything below was read from docs.x.ai/developers/tools/function-calling this session; the raw text is kept with the study. The API is OpenAI-compatible: you create an OpenAI client with base_url="https://api.x.ai/v1" and your XAI_API_KEY, and call client.responses.create(...), the Responses API endpoint on api.x.ai. Chat Completions also works, but the Grok 4.7 page lists the Responses API as the model's API and the examples use it, so this tutorial does too.

Tool definitions. Each tool is {"type": "function", "name": ..., "description": ..., "parameters": {...}}. name and parameters are required; description is optional but the doc notes a clear one helps the model decide when to call it. The parameters root must be a JSON Schema object (or a oneOf / anyOf whose branches are all objects); a scalar or array root is rejected with a 400 that names the tool. Up to 350 tools per request.

The round trip. When the model wants data it returns an output item with type: "function_call", a name, an arguments string (JSON) and a call_id. You run the function and send a new request whose input is a list of {"type": "function_call_output", "call_id": ..., "output": "<string>"} items, with previous_response_id set to the previous response's id and the same tools list. The model either calls more tools or returns a message item whose content[0].text is the answer. With streaming, a function call arrives whole in a single chunk.

Parallel calls and tool choice. Parallel function calling is on by default, so one response may contain several function_call items; the doc says to process all of them before continuing, which is why the loop on this page collects every call in a response and sends all outputs back in one request. parallel_tool_calls: false disables it. tool_choice accepts "auto" (default), "required", "none", or a specific function.

Mixing with built-in tools. The same tools array can hold {"type": "web_search"}, {"type": "x_search"} and your functions; built-in tools run on xAI's servers automatically, custom functions pause and return to you. That is the choice the next section is about.

Two Grok 4.7 details for agent loops. The model page recommends setting prompt_cache_key on the Responses API so a conversation's requests land on the same server and cache hits are reliable, and notes that grok-4.7 responses include reasoning.encrypted_content which you pass back unchanged in multi-turn flows; with previous_response_id the server keeps that state for you. grok-4.7 has a 500,000-token context window and is priced at $2.00 per million input tokens and $6.00 per million output tokens below 200,000 prompt tokens ($0.50 cached), per docs.x.ai/developers/pricing.

Built-in x_search. Add {"type": "x_search"} to tools and Grok searches X itself, reads the posts it fetches and answers with citations; each call shows up in the output as a custom_tool_call item. The doc lists six options: allowed_x_handles and excluded_x_handles (arrays of up to 20 handles without the @, not combinable), from_date and to_date (YYYY-MM-DD, from 00:00 UTC on the start date up to but not including the end date), and enable_image_understanding / enable_video_understanding. Pricing on docs.x.ai/developers/pricing: $5 per 1,000 posts fetched and $10 per 1,000 user profiles fetched, billed per item rather than per call, including parent and quoted posts; the response reports x_posts_fetched and x_users_fetched in usage.server_side_tool_usage_details. The doc's own cost advice is to narrow handles and dates and cap search turns with max_turns. You get an answer and citations; you do not get the post objects, so you cannot apply your own filters, store the data, or compute anything the model did not.

Your own function tools (this page). The model asks, your code calls twitterapi.io, you return exactly the fields you want the model to see. Reads cost 15 credits per tweet returned ($0.15 per 1,000; a full 20-post page is $0.003; the minimum per request is 15 credits, so an empty search is $0.00015) and 18 credits per profile ($0.18 per 1,000). You can drop reposts before the model sees them, cap the window at 7 days, keep the raw JSON for a database, and run the same tools from any other model or framework. The trade-off is that you host the loop.

A remote MCP server. xAI's Responses API also accepts {"type": "mcp", "server_url": ..., "server_label": ..., "allowed_tools": [...], "authorization": ...}; xAI connects to the server and calls its tools for the model, with no per-invocation fee (tokens only). Only Streamable HTTP and SSE transports are supported, and the require_approval and connector_id parameters are not. Without allowed_tools, every tool the server exposes is injected into the model's context, so the doc recommends listing the ones you need. The twitterapi.io MCP server on our MCP server page ships as an npm package that runs over stdio (npx -y @twitterapi_io/mcp-server). Grok Build accepts exactly that shape: its docs register a local stdio server with grok mcp add <name> -- npx -y <package> and an HTTP one with grok mcp add --transport http <name> <url>, and expose the tools as <server>__<tool>. To use the same server as a remote MCP tool from the xAI API you would put it behind an HTTP transport you host.

For the question this page uses as its example, the difference is concrete: "what did @github post this week" fetched 14 posts in our sample, which is $0.07 through x_search and $0.003 as one twitterapi.io page. The next section measures why the raw fields matter as much as the price.

A tool that returns "recent posts" has to decide how far back to page and what to drop. To ground both decisions we pulled up to 5 pages of /twitter/user/last_tweets (20 posts each, replies excluded by the default call) for 8 public organization accounts in 2026: 39 requests, 760 posts, $0.114 in reads. Recency windows were measured backwards from each account's newest post.

How many pages a "this week" answer needs. Across the 8 accounts, the last 7 days held 154 posts, between 10 (@vercel) and 43 (@OpenAIDevs). Five accounts fit in a single 20-post page; @NASA (24) and @nvidia (22) need 2; @OpenAIDevs needs 3. All 8 together: 12 pages, $0.036. The last 24 hours held 33 posts across all 8, never more than 9 for one account, so a "today" question is always one page. A 30-day question is where paging starts to matter: 500 posts, 27 pages, and for 3 of the 8 accounts (@github, @OpenAIDevs, @Cloudflare) 100 posts did not reach back 30 days. The tool on this page therefore pages until it passes the requested age or runs out of pages, with a hard cap of 5 pages.

How much of a timeline is noise. 63.7% of the 760 posts were the account's own original posts, 27.1% were reposts of other accounts and 9.2% were quotes; replies were 0% because the default call excludes them. The spread is wide: @Docker (98% original), @vercel (93%) and @Cloudflare (86%) are almost all their own words, while @OpenAIDevs was 76% reposts and @stripe 41% reposts plus 31% quotes. An agent that returns a repost's text as what @OpenAIDevs "posted" is wrong three times out of four. The tool labels each item original, repost or quote, drops reposts by default, and for quotes includes the quoted author so the model can attribute correctly.

How much text that is. Median post length was 202 characters (per account 140 to 298; the longest 1,197). 51.3% of posts carried at least one link and 42.9% had media. Feeding the full 7-day text of all 8 accounts to the model is roughly 7,900 tokens at four characters per token; originals only, about 5,700. At grok-4.7's $2.00 per million input tokens that is under two cents either way, which is the point: with your own tools the X data, not the model, is the cost you control, and both are small.

Posts a day is the sample size divided by the days it spans, so it is a long-run average for the quieter accounts (@vercel's 100 posts span 282 days, yet 9 of its 10 posts in the last 7 days landed in the last 24 hours, a launch-day burst). Pages = ceil(posts / 20), minimum 1.

The three rate cards price different units, so the fair comparison is per answer. twitterapi.io bills 15 credits per tweet returned ($1 = 100,000 credits), so a full 20-post page is $0.003 and the minimum for any request is 15 credits ($0.00015). xAI's built-in x_search bills $5 per 1,000 posts fetched ($0.005 a post) plus the model's tokens. The official X API pay-per-usage rate card at docs.x.com/x-api/getting-started/pricing is $0.005 per post read and $0.010 per user read, capped at 3 million post reads a month with Enterprise above that; new accounts get $20 in credits and a match of the first auto-recharge up to $50. Per 1,000 posts that is $5 against $0.15, about 33x.

Add the model on top of any row: the 7-day text of all 8 accounts is roughly 7,900 input tokens, about $0.016 at grok-4.7's $2.00 per million, plus the output. The x_search column assumes it fetched the same posts; in practice the model decides how many posts to fetch and may read more (quoted and parent posts count too, per the pricing page) or fewer. The official-API column also needs a developer account before the first call. twitterapi.io reads need no X account. Subscription plans with bonus credits are on /pricing; new accounts that pass the automatic bot check get up to $1 of free credits (one per person or network, expiring after 31 days), enough for about 330 full pages.

Each tool is a small function that calls one twitterapi.io endpoint with the X-API-Key header, trims the response to what the model needs, and returns a JSON-serializable dict. Trimming matters twice: fewer tokens, and fewer irrelevant fields for the model to misread. Field names below are the API's own.

get_user -> /twitter/user/info?userName=<handle>. The body is {status, msg, data}; an unknown handle comes back as HTTP 200 with status: "error", msg: "user not found" and data: null, never a 404, so the tool checks status and returns an error object the model can read and explain. From data it keeps name, userName, description, followers, following, statusesCount, createdAt, isBlueVerified, isVerified and isAutomated.

get_recent_posts -> /twitter/user/last_tweets?userName=<handle>. Returns data.tweets[] (20 per page, newest first), has_next_page and next_cursor. The tool pages while the oldest post on the page is newer than the requested days and has_next_page is true, capped at 5 pages (100 posts, $0.015). Each post is classified: retweeted_tweet present means repost (the tool keeps the original author's handle in reposted_from and uses the original's text, since a repost's own text is cut short), quoted_tweet present means quote (the quoted author goes in quoting), isReply would mean reply but the default call excludes them. Reposts are dropped unless include_reposts is true. createdAt is "Sat Oct 17 17:50:19 +0000 2026"-style and is converted to ISO for the model.

search_posts -> /twitter/tweet/advanced_search?query=<q>&queryType=Latest|Top. Top-level tweets[], same tweet shape, with author.userName. The tool passes the query through unchanged and keeps one page (20 posts, $0.003; an empty result costs the 15-credit minimum). The description teaches the model the operators it needs (from:, since_time:, lang:, min_faves:, -filter:replies); that description is doing real work, because the model writes the query.

get_mentions -> /twitter/user/mentions?userName=<handle>. Top-level tweets[], newest first. One page, same trimming. This is the tool that answers "what are people saying to @X", which a timeline tool cannot.

Errors as data. Every tool catches HTTP errors and returns {"error": "..."} instead of raising; the model will tell the user the account was not found or the search returned nothing. twitterapi.io returns 429 when you exceed your rate tier (0.2 requests per second before the first payment, 20 once paid), so a backoff on 429 is in the client. All four paths exist in the public OpenAPI spec at docs.twitterapi.io.

The loop in the full script at the end of the page is about 40 lines and follows the documented round trip exactly. First request: client.responses.create(model="grok-4.7", instructions=SYSTEM, input=[{"role": "user", "content": question}], tools=TOOLS). Then, while the response contains function_call items: run every one of them (parallel calls are on by default, so there may be several), build an input list of {"type": "function_call_output", "call_id", "output"} items, and call responses.create again with previous_response_id=response.id and the same tools. When a response contains no function calls, the message item's content[0].text (or the convenience response.output_text) is the answer.

A turn cap. MAX_TURNS = 6 stops a model that keeps calling tools; six round trips is more than any question on this page needs (profile, timeline, mentions, done). Without a cap, a tool that returns an error the model does not understand can loop.

The system prompt does the attribution work. It tells the model that kind: repost items are other accounts' words, that quotes should be attributed to both accounts, to prefer get_recent_posts with days=7 for "this week" and days=1 for "today", to call get_user first when a handle is given so a typo is caught before paging, and to cite post URLs. That is where the measurements above turn into behavior: the model is told what the data looks like.

prompt_cache_key. The Grok 4.7 page recommends setting it so a conversation's requests hit the same cache; the script sets one per conversation. It is an optimization, not a requirement.

What we did and did not run. We ran all four tool functions against twitterapi.io in 2026 (that is the study), and we ran the loop's control flow against the documented response shapes. We did not have an xAI API key for this article, so the transcript below is not a recorded Grok run; it is what the loop prints when the tool side returns the data above. Treat it as a format illustration.

Swapping the model. Because the tool contract is OpenAI-style JSON Schema, the same four tools run unchanged in our OpenAI Agents SDK guide, the Claude MCP guide and the LangChain guide. Only the loop differs.

400 that names a tool. The parameters root is not an object (for example you passed an array schema). Wrap it: {"type": "object", "properties": {...}}.

The model answers without calling any tool. tool_choice is "auto" by default; for a data question set tool_choice="required" on the first turn, or sharpen the descriptions. The multi-agent model (grok-4.20-multi-agent) ignores function tools entirely; use grok-4.7.

Several function_call items in one response. That is parallel calling. Run all of them and send all function_call_output items in one request; sending one at a time with the same previous_response_id leaves calls unanswered.

user not found for a real account. /twitter/user/info returns HTTP 200 with status: "error" for unknown handles; check the handle without the @, and remember handles change. The tool returns the message so the model can ask the user.

The answer quotes posts the account did not write. Reposts were 27.1% of the sample and 76% for one account. Make sure include_reposts defaults to false and that the system prompt explains kind.

"This week" is incomplete for a busy account. One page is 20 posts; @OpenAIDevs needed 3 pages for 7 days. The tool pages until it passes the requested age; check that has_next_page and next_cursor are being followed and that the 5-page cap is not too low for your accounts.

429 from twitterapi.io. Accounts that have never paid are limited to 0.2 requests per second; a parallel call to get_user and get_recent_posts at once can trip it. The client retries with a backoff; once a payment is made the limit is 20 requests per second.

Costs higher than expected with x_search. It bills per post fetched, including parent and quoted posts, and the model decides how many to fetch. Narrow allowed_x_handles and the date range, cap max_turns, and read x_posts_fetched in the usage block; or move the fetch into your own tool where a page is a fixed $0.003.

Question: what does an agent whose tools are X timeline endpoints actually have to read to answer a typical question: how many 20-post pages a 24-hour, 7-day and 30-day window needs per account, what share of a timeline is reposts, quotes or replies, how long the texts are, how many carry links or media, and what one answer costs on twitterapi.io, on xAI's built-in x_search and on the official X API rate card.

Accounts: 8 public organization accounts: @github, @vercel, @OpenAIDevs, @nvidia, @NASA, @stripe, @Cloudflare and @Docker.

Method: /twitter/user/last_tweets with the default includeReplies (replies excluded), up to 5 pages of 20 per account, newest first, through a rate-limited read-only client: 39 requests (one account ran out of pages at 4), 760 posts, collected in 2026. Recency windows were measured backwards from each account's newest post. A post with retweeted_tweet is a repost, with quoted_tweet a quote, with isReply a reply, otherwise original. Pages needed = ceil(posts in window / 20), minimum 1. Token estimates use four characters per token. Prices: twitterapi.io 15 credits per tweet and 18 per profile; xAI x_search $5 per 1,000 posts fetched; official X API $0.005 per post read, all read from the respective pricing pages this session.

What the sample cannot show: 100 posts per account is a snapshot taken at one moment, so posts per day is a long-run average for the quieter accounts and the 30-day window was only partly covered for three accounts. Organization accounts repost and quote differently from individuals or news accounts; a personal timeline will usually have a higher reply share, which the default call hides. We did not run Grok itself, so nothing here measures how often the model chooses each tool or how many x_search fetches it would make; the x_search cost column assumes it fetched the same posts the function tool did.

Aggregates only. The accounts named are organizations; no individual's posts were analyzed. The analysis script, results and the gzip-compressed raw pages for these organization accounts are kept with the study.