xAI Grok API

Grok-2 model with live access to X platform data, enabling generation of responses grounded in current events, trending topics, and real-time social discourse. The model integrates X data retrieval at inference time rather than relying on static training data cutoffs, allowing it to reference events happening within hours or minutes of the API call. Requests include optional context parameters to specify time windows, trending topics, or specific accounts to prioritize in the knowledge context.

Grok-Vision processes images alongside text prompts to generate descriptions, answer visual questions, extract structured data from images, and perform visual reasoning tasks. The model uses a vision encoder to convert images into embeddings that are fused with text embeddings in a unified transformer architecture, enabling joint reasoning over both modalities. Supports batch processing of multiple images per request and returns structured outputs including bounding boxes, object labels, and confidence scores.

Grok API implements the OpenAI API specification (chat completions, embeddings, streaming) as a drop-in replacement, allowing developers to swap Grok models into existing OpenAI-based codebases with minimal changes. The implementation maps Grok model identifiers (grok-2, grok-vision) to OpenAI's message format, supporting the same request/response schemas, streaming protocols, and error handling patterns. This compatibility layer abstracts away Grok-specific features (like X data integration) as optional parameters while maintaining full backward compatibility with standard OpenAI client libraries.

Grok API supports streaming text generation via HTTP Server-Sent Events (SSE), allowing clients to receive tokens incrementally as they are generated rather than waiting for the full response. The implementation uses chunked transfer encoding with JSON-formatted delta objects, compatible with OpenAI's streaming format. Clients can process tokens in real-time, enabling low-latency UI updates, early stopping, and progressive rendering of long-form content. Streaming is compatible with both text-only and multimodal requests.

Grok API supports structured function calling via OpenAI-compatible tool definitions, allowing the model to invoke external functions by returning structured JSON with function names and arguments. The implementation uses JSON schema to define tool signatures, and the model learns to call tools when appropriate based on the task. The API returns tool_calls in the response, which the client must execute and feed back to the model via tool_result messages. This enables agentic workflows where the model can decompose tasks into function calls, handle errors, and iterate.

Grok API returns detailed token usage information (prompt_tokens, completion_tokens, total_tokens) in every response, enabling developers to track costs and implement token budgets. The API uses a transparent pricing model where costs are calculated as (prompt_tokens * prompt_price + completion_tokens * completion_price). Clients can estimate costs before making requests by calculating token counts locally using the same tokenizer as the API, or by using the API's token counting endpoint. Usage data is aggregated in the xAI console for billing and analytics.

Grok API manages context windows (the maximum number of tokens the model can process in a single request) by accepting a messages array where each message contributes to the total token count. The API enforces a maximum context window (typically 128K tokens for Grok-2) and returns an error if the total exceeds the limit. Developers can implement automatic message truncation strategies (e.g., keep the most recent N messages, summarize old messages, or drop low-priority messages) to fit within the context window. The API provides token counts for each message to enable precise truncation.

Grok API enforces rate limits on a per-API-key basis, with separate limits for requests-per-minute (RPM) and tokens-per-minute (TPM). The API returns HTTP 429 (Too Many Requests) responses when limits are exceeded, along with Retry-After headers indicating when the client can retry. Developers can query their current usage and limits via the API or xAI console. Rate limits vary by plan (free tier, paid tiers, enterprise) and can be increased by contacting xAI support. The API does not provide built-in queuing or backoff logic; clients must implement their own retry strategies.

Grok API offers a batch processing endpoint that accepts multiple requests in a single JSONL file, processes them asynchronously, and returns results in bulk. Batch requests are charged at a 50% discount compared to real-time API calls, making them suitable for non-urgent, high-volume workloads. Clients submit a batch file, receive a batch ID, and poll for completion status. Results are returned as a JSONL file that can be downloaded or streamed. Batch processing typically completes within 1-24 hours depending on queue depth.

Grok API returns structured error responses with HTTP status codes, error codes (e.g., 'invalid_request_error', 'rate_limit_error', 'server_error'), human-readable error messages, and optional recovery suggestions. Common errors include invalid API keys (401), malformed requests (400), rate limit exceeded (429), and server errors (5xx). The API provides Retry-After headers for rate limit and server errors, enabling clients to implement intelligent retry logic. Error responses include a unique request ID for debugging and support inquiries.