Grok API Build Guide: xAI for Production Agents

The Production Verdict

The Grok API is worth a production build when the agent's edge depends on live search, tool-heavy reasoning, or coding-specific work that benefits from a long context window. It is not the default choice for every agent, and it should not be wired straight into mutating tools without your own control plane.

The practical line is simple:

That puts xAI in the agents lane, not merely the stack lane. The model provider matters, but the shipped system is still an agent architecture: state, tools, retrieval, evals, approvals, fallback, and telemetry. If those pieces are missing, a stronger model only makes the failure mode more expensive.

For context design around the agent loop, pair this with context engineering for production agents. The provider is one layer. The operating boundary is the part your team has to own.

Use The Current Docs, Not Stale Build URLs

The current xAI build path is not https://docs.x.ai/build/: that URL returns 404 and points to the working docs entry points. Production teams should pin the active pages in their internal runbook instead of copying stale bookmarks into onboarding docs.

Use these current docs paths:

• Overview for the API surface.
• Quickstart for account setup, keys, SDK installs, and first requests.
• Models for model choice, realtime data caveats, aliases, and image input limits.
• API reference for route shape and auth.
• Pricing for model, tool, batch, priority, storage, download, and violation-fee costs.
• Console for keys, usage, billing, model availability, and rate-limit requests.

The stale route matters because API docs get pasted into repo READMEs, agent instructions, and internal wikis. If your coding agent is told to use a dead docs path, it may continue from a secondary blog or wrapper example instead of the vendor source. Treat the docs links as part of the agent context layer.

What xAI Gives A Production Agent

Grok 4.3 is the default production model to evaluate first, and Grok Build 0.1 is the model to test for coding-agent paths. The two models share the same high-level production shape, but their cost and context profiles are different enough that routing should be explicit.

Both model detail pages list 37 requests per second and 10,000,000 tokens per minute in us-east-1. Both also warn that requests exceeding the 200K context window are charged at different rates. That is the hidden production footnote: a large context window is useful, but it is not permission to keep stuffing full histories into every request.

The models page gives two rules worth copying into your routing code. Use Grok Build 0.1 for coding. For everything else outside dedicated audio, image, and video APIs, start with Grok 4.3. It also states that Grok has no access to realtime events or data beyond training data unless Web Search or X Search tools are enabled, and it lists the Grok 3 and Grok 4 knowledge cutoff as November, 2024.

For a production agent, that means current facts are not a model choice. They are a tool choice. If your agent answers market, news, social, vendor-doc, or support-policy questions, enable search deliberately and log the source behavior. If the answer must come only from your own docs, do not give the model open web access. Build retrieval or MCP around the approved source set.

Keep Agent State Outside The Provider Boundary

The Responses API is the right interface for most app agents, but its default state behavior deserves an explicit architecture decision. xAI says the Responses API can store previous input prompts, reasoning content, and model responses on xAI's servers by default, and those responses are stored for 30 days. Set store: false when the application must own the conversation history locally.

That choice changes the rest of the build. If you use provider-side state, your app can continue a conversation by response ID inside the retention window. If you use local state, your app must persist the conversation, tool outputs, encrypted reasoning content where applicable, retrieval references, and approval decisions in its own database.

The production default we prefer is local state for any agent that touches customer records, internal systems, or regulated workflows. Provider-side state is acceptable for low-risk experiences and prototypes, but it should be visible in the architecture review rather than inherited from a quickstart.

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.XAI_API_KEY,
  baseURL: "https://api.x.ai/v1",
});

const response = await client.responses.create({
  model: "grok-4.3",
  store: false,
  input: [
    {
      role: "system",
      content:
        "You are a support operations agent. Return only approved next actions.",
    },
    {
      role: "user",
      content: "Summarize the latest policy page and propose a response.",
    },
  ],
  tools: [
    {
      type: "web_search",
      filters: { allowed_domains: ["docs.example.com"] },
    },
  ],
  response_format: {
    type: "json_schema",
    json_schema: {
      name: "support_action",
      schema: {
        type: "object",
        additionalProperties: false,
        properties: {
          answer: { type: "string" },
          needs_human_approval: { type: "boolean" },
          cited_source: { type: "string", format: "uri" },
        },
        required: ["answer", "needs_human_approval", "cited_source"],
      },
    },
  },
});

console.log(response.output_text);

The code is intentionally narrow. It uses the OpenAI-compatible SDK surface with baseURL: "https://api.x.ai/v1", disables provider-side storage, restricts search to an approved domain, and forces a typed response. The application still has to validate the JSON, check the cited source, and decide what happens if needs_human_approval is true.

Structured outputs are strong enough to rely on for normal extraction and control-flow contracts, but not broad enough to replace validation. xAI guarantees supported schema features, while documenting constraint limits such as maxLength up to 2,048, maxItems up to 256, and maxProperties up to 64. Anything beyond the guaranteed subset should be treated as model behavior and rechecked in your app.

Tool Boundary: Server Tools For Search, Functions For Your Systems

Use xAI server-side tools for external information gathering and computation, and use function calling or MCP for your own systems. The distinction matters because it decides where execution happens, where credentials live, and where approval can be enforced.

xAI documents two tool categories. Built-in tools run on xAI's servers: Web Search, X Search, Code Interpreter, and Collections Search. Function calling lets you define a custom function schema, the model requests the function call, and your application executes it locally. In streaming mode, function calls are returned whole in a single chunk, so your tool runner should handle complete call objects rather than partial argument streaming.

Use built-in tools when the result is external and read-oriented:

• Web Search for current docs, pages, and public sources.
• X Search for posts, users, and thread fetches where social context is part of the product.
• Code Execution for calculations, data processing, and verification inside a sandbox.
• Collections Search or file search for uploaded document collections when xAI-hosted retrieval is acceptable.

Use your own function or MCP boundary when the result touches company state:

• Reading CRM, ticketing, billing, product, or warehouse data.
• Creating drafts, refunds, escalations, or account changes.
• Running internal search over private documents with custom permissions.
• Calling workflow systems where a tool mistake has business impact.

Remote MCP is useful here, but it is not a substitute for your own approval layer. xAI supports Remote MCP in the native SDK, the OpenAI-compatible Responses API, and the Voice Agent API. The MCP config requires server_url and server_label, supports Streaming HTTP and SSE transports, and can send authorization headers. It also supports allowed_tools, which should be mandatory in production.

The key limitation is explicit in the docs: require_approval and connector_id are not currently supported for Remote MCP in the OpenAI Responses API. If a tool can mutate state, do not rely on provider-side approval semantics that are not supported. Put the approval in your app.

The minimum log for any tool-using Grok agent should include:

• model, model_alias, and whether the alias resolved in a release-sensitive path.
• store decision and local conversation state ID.
• Input tokens, cached input tokens, reasoning tokens, output tokens, and image tokens when present.
• Built-in tool calls by type, including web_search, x_search, and code_interpreter.
• Function or MCP tool name, arguments hash, approval state, execution result status, and retry count.
• Source URLs and citation IDs for search-backed answers.
• Final answer schema validation result.
• User-visible action, suppressed action, or human handoff outcome.

If you cannot reconstruct why the agent called a tool, what data it saw, and who approved the action, the system is not production-ready.

Cost Model: Tokens Are Only Part Of The Bill

The token table is not the agent cost model. For Grok agents, tool invocations, search breadth, reasoning tokens, context size, batch mode, priority mode, storage, and downloads all affect the bill.

Start with the published prices. Grok 4.3 costs $1.25 / 1M input tokens, $0.20 / 1M cached input tokens, and $2.50 / 1M output tokens. Grok Build 0.1 costs $1.00 / 1M input tokens, $0.20 / 1M cached input tokens, and $2.00 / 1M output tokens. Server-side tools are charged separately: web_search, x_search, and code execution are $5 / 1k calls, file attachments are $10 / 1k calls, and collections search is $2.50 / 1k calls. Remote MCP tool invocation itself is token-based rather than a separate invocation charge.

Here is the production cost trap in plain math. An illustrative Grok 4.3 request with 10,000 input tokens and 1,000 output tokens costs $0.0125 for input and $0.0025 for output. Add 2 Web Search calls and the tool cost is $0.0100. The total is $0.0250, excluding reasoning and image tokens. In that example, search is a large share of the cost even though the prompt looks modest.

That is why tool budgets belong in the agent loop:

const budget = {
  maxToolCalls: "set per route",
  allowedSearchDomains: "set per route",
  priorityAllowed: "latency-sensitive routes only",
  batchAllowed: "offline eval and enrichment routes only",
  approvalRequired: "all mutating tools",
};

Prompt caching helps when consecutive requests share the same starting messages. xAI says caching is automatic and recommends the x-grok-conv-id header to improve cache hit rate. Design your prompts so the stable instruction, policy, and tool descriptions come first, while user-specific material comes later.

Batch API is the right path for evals, enrichment, moderation backlogs, and offline processing. It is asynchronous, most requests complete within 24 hours on a best-effort basis, requests do not count toward per-minute rate limits, and token pricing is 20%-50% off standard rates for text and language models. Image and video generation can run through batch, but they are billed at standard rates.

Priority Processing is the opposite tradeoff. It applies to Chat Completions and Responses, uses service_tier: "priority", and costs 2x standard token rates only when the response confirms "priority". Reserve it for user-facing paths where lower latency changes the product experience. Background jobs should go batch.

Launch Checklist

Ship the Grok agent only after the control layer can fail closed. The model can be strong and the product can still be unsafe if tool access, state, evals, and cost ceilings are vague.

The durable rule is that Grok should sit behind the same production shell as any other capable model. The shell owns state, permissioning, evals, logging, and approval. xAI gives you useful primitives, especially search, structured outputs, function calling, Remote MCP, long context, prompt caching, batch, and priority processing. The agent becomes production software only when those primitives are wrapped in controls your team can inspect.

When Not To Use The Grok API

Do not choose xAI only because the quickstart is easy. Choose it because the production job benefits from its specific primitives.

Skip or postpone the Grok API when:

• Your legal or security review requires compliance certifications, residency commitments, or contractual terms you have not verified in the console or sales process.
• The workflow is a cheap deterministic classifier and does not need long context, live search, or tool use.
• The agent will mutate internal state but your app has no approval queue.
• The product needs only your private corpus and you are not ready to design retrieval permissions.
• Your latency budget cannot tolerate reasoning, search, or tool loops, and you have not measured priority processing under your own traffic.
• Your cost model ignores server-side tool invocations and treats token price as the full bill.

The strongest use case is a bounded agent with a real need for fresh external context or coding-specialized work, plus a team willing to own the controls around it.

FAQ