# Grok 4.7

Use `grok-4.7` with one of the three formats below. Authentication uses your TokLab API key. Current token prices are on the [pricing page](https://toklab.ai/pricing).

## Quick start

```bash
curl https://api.toklab.ai/v1/responses \
  -H "Authorization: Bearer $TOKLAB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"grok-4.7","input":"What is 2 + 2?","reasoning":{"effort":"low"},"max_output_tokens":64,"store":false}'
```

The JSON response includes `output` items and `usage`. Retain all output items when building conversation history, including reasoning and tool items.

## Request formats

| Format           | Endpoint                    | Required fields                   |
| ---------------- | --------------------------- | --------------------------------- |
| Responses        | `POST /v1/responses`        | `model`, `input`                  |
| Chat Completions | `POST /v1/chat/completions` | `model`, `messages`               |
| Messages         | `POST /v1/messages`         | `model`, `messages`, `max_tokens` |

Use `Content-Type: application/json` and `Authorization: Bearer $TOKLAB_API_KEY`. Messages clients can also send `anthropic-version: 2023-06-01`.

## Parameters and constraints

The [OpenAPI specification](https://toklab.ai/docs/grok-4-7.openapi.json) contains the full nested request and response schemas. The tables below list every supported top-level request field. Unknown fields and parameters officially ignored by this model are discarded. A supported parameter with an invalid value remains invalid.

Optional nullable fields accept explicit `null`; leaving a field out uses its API default. API clients can still send `user`.

* Context: 500,000 tokens, including the conversation and output.
* Reasoning effort: `low`, `medium`, `high`, `xhigh`; default `high`.
* `max_completion_tokens` and `max_output_tokens` default to 128,000 **visible** output tokens. Reasoning and function-call tokens are outside that visible-output limit. This is a default, not a maximum output capability claim.
* Output limits must be positive integers. The API also enforces its existing integer safety ceiling of 1,073,741,823; context capacity still applies.
* `temperature`: 0 through 2, default 1. `top_p`: greater than 0 and at most 1, default 1. Responses `min_p`: 0 through 1; `top_k`: integer at least 1.
* Up to 350 tool definitions. `stream_options` requires `stream: true`.
* `instructions` and `previous_response_id` cannot be combined. Reasoning summaries are always detailed.

{/* grok-parameters:start */}

### Responses parameters

| Field                  | Type                  | Rule                                                                            |
| ---------------------- | --------------------- | ------------------------------------------------------------------------------- |
| `include`              | array or null         | Array of additional response fields to include.                                 |
| `input` (required)     | object or alternative | Text string or complete input-item array.                                       |
| `instructions`         | string or null        | System instructions; cannot be combined with `previous_response_id`.            |
| `max_output_tokens`    | integer or null       | Visible-output limit; default 128,000.                                          |
| `max_turns`            | integer or null       | Integer maximum number of agent turns.                                          |
| `min_p`                | number or null        | Number from 0 to 1.                                                             |
| `model` (required)     | string                | Fixed to `grok-4.7`.                                                            |
| `parallel_tool_calls`  | boolean or null       | Boolean; default true.                                                          |
| `previous_response_id` | string or null        | String response ID; continuation by ID is currently unavailable.                |
| `prompt_cache_key`     | string or null        | String cache key.                                                               |
| `reasoning`            | object                | Reasoning configuration; effort defaults to `high`.                             |
| `reasoning_effort`     | string or null        | `low`, `medium`, `high`, `xhigh`; default `high`.                               |
| `safety_identifier`    | string or null        | Optional caller-supplied safety identifier.                                     |
| `search_parameters`    | object                | Search configuration.                                                           |
| `service_tier`         | string                | `auto`, `default`, `priority`, `fast`; priority and fast double token rates.    |
| `store`                | boolean or null       | Boolean; default true. Stored-response operations are currently unavailable.    |
| `stream`               | boolean or null       | Boolean; default false.                                                         |
| `temperature`          | number or null        | Number from 0 to 2; default 1.                                                  |
| `text`                 | object                | Text response configuration, including `format`.                                |
| `tool_choice`          | object or alternative | Automatic, disabled, required or a selected tool; syntax depends on the format. |
| `tools`                | array or null         | Tool definitions; at most 350.                                                  |
| `top_k`                | integer or null       | Integer; Responses requires at least 1.                                         |
| `top_p`                | number or null        | Number greater than 0 and at most 1; default 1.                                 |
| `user`                 | string or null        | Optional caller-supplied identifier; hidden in the playground.                  |

### Chat Completions parameters

| Field                   | Type                  | Rule                                                                            |
| ----------------------- | --------------------- | ------------------------------------------------------------------------------- |
| `deferred`              | boolean or null       | Boolean; default false. Deferred completion is currently unavailable.           |
| `max_completion_tokens` | integer or null       | Visible-output limit; default 128,000.                                          |
| `max_tokens`            | integer or null       | Positive visible-output limit. Required for Messages.                           |
| `messages` (required)   | array                 | Conversation messages in this format.                                           |
| `model` (required)      | string                | Fixed to `grok-4.7`.                                                            |
| `n`                     | integer or null       | Integer at least 1; default 1.                                                  |
| `parallel_tool_calls`   | boolean or null       | Boolean; default true.                                                          |
| `prompt_cache_key`      | string or null        | String cache key.                                                               |
| `reasoning_effort`      | string or null        | `low`, `medium`, `high`, `xhigh`; default `high`.                               |
| `response_format`       | object or alternative | Text, JSON object or JSON schema output.                                        |
| `safety_identifier`     | string or null        | Optional caller-supplied safety identifier.                                     |
| `search_parameters`     | object                | Search configuration.                                                           |
| `seed`                  | integer or null       | Integer sampling seed.                                                          |
| `service_tier`          | string                | `auto`, `default`, `priority`, `fast`; priority and fast double token rates.    |
| `stream`                | boolean or null       | Boolean; default false.                                                         |
| `stream_options`        | object                | Options for streaming; requires `stream: true`.                                 |
| `temperature`           | number or null        | Number from 0 to 2; default 1.                                                  |
| `tool_choice`           | object or alternative | Automatic, disabled, required or a selected tool; syntax depends on the format. |
| `tools`                 | array or null         | Tool definitions; at most 350.                                                  |
| `top_p`                 | number or null        | Number greater than 0 and at most 1; default 1.                                 |
| `user`                  | string or null        | Optional caller-supplied identifier; hidden in the playground.                  |
| `web_search_options`    | object                | Compatibility search options.                                                   |

### Messages parameters

| Field                   | Type                  | Rule                                                                            |
| ----------------------- | --------------------- | ------------------------------------------------------------------------------- |
| `max_tokens` (required) | integer               | Positive visible-output limit. Required for Messages.                           |
| `messages` (required)   | array                 | Conversation messages in this format.                                           |
| `metadata`              | object                | Messages metadata object.                                                       |
| `model` (required)      | string                | Fixed to `grok-4.7`.                                                            |
| `stop_sequences`        | array or null         | Array of stop strings.                                                          |
| `stream`                | boolean or null       | Boolean; default false.                                                         |
| `system`                | object or alternative | System string or content blocks.                                                |
| `temperature`           | number or null        | Number from 0 to 2; default 1.                                                  |
| `tool_choice`           | object or alternative | Automatic, disabled, required or a selected tool; syntax depends on the format. |
| `tools`                 | array or null         | Tool definitions; at most 350.                                                  |
| `top_k`                 | integer or null       | Integer; Responses requires at least 1.                                         |
| `top_p`                 | number or null        | Number greater than 0 and at most 1; default 1.                                 |

{/* grok-parameters:end */}

## Streaming

Set `stream` to `true`. Chat emits completion chunks; Responses emits named response events; Messages emits message and content-block events. Read the final usage event as well as text deltas. Tool calls and reasoning can be separate output items; do not reduce the stream to visible text when retaining history.

```json
{
  "model": "grok-4.7",
  "input": "Explain a mutex in one sentence.",
  "reasoning": { "effort": "low" },
  "max_output_tokens": 128,
  "store": false,
  "stream": true
}
```

## Tools and structured output

Use the tool definition for your chosen format. Chat uses `response_format`; Responses uses `text.format`. Functions, web search, X search, code interpreter and MCP calls have been exercised with this model. Shell returns a client-executed call; it does not run a command on your computer automatically. The full schema also describes other tool types; a schema entry alone is not evidence that a particular external service is configured.

```json
{
  "model": "grok-4.7",
  "input": "Use the code interpreter once to compute 13*17. Return the number.",
  "tools": [{ "type": "code_interpreter" }],
  "tool_choice": "required",
  "max_turns": 1,
  "reasoning": { "effort": "low" },
  "max_output_tokens": 32,
  "store": false
}
```

Tool usage is charged separately from tokens. Web search and code interpreter use call counts. X search uses fetched post and profile counts, including repeated fetched items; the number of X search calls is not its billable unit. Inspect `usage.server_side_tool_usage_details` and your account usage records.

## Usage and pricing

Prices depend on total input length. Below 200,000 input tokens, use the standard tier. At 200,000 or more, use the long-context tier for the entire request; cached input is included when selecting the tier. `service_tier: "priority"` and `"fast"` double token rates in both tiers. `auto` and `default` select standard service. Tool charges are calculated separately and are not doubled by this token multiplier.

| Format    | Input accounting                                                                          | Output accounting                                                                                                                |
| --------- | ----------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| Responses | `input_tokens` includes `input_tokens_details.cached_tokens`                              | `output_tokens` includes reasoning; do not add the reasoning breakdown again                                                     |
| Chat      | `prompt_tokens` includes `prompt_tokens_details.cached_tokens`                            | xAI reports visible `completion_tokens` separately; total billable output is `total_tokens - prompt_tokens`, including reasoning |
| Messages  | `input_tokens` excludes `cache_read_input_tokens`; add cache fields to obtain total input | `output_tokens` is the output total                                                                                              |

Public responses include usage counters, not monetary cost fields. Your usage records show the final charge. Failed requests are not charged.

## Conversation history and current limits

For stateless continuation, send the previous input, every returned output item, and the next user message as the new `input`. With Chat or Messages, send the complete message history in that format. Preserve encrypted reasoning and tool items unchanged where returned.

The current service cannot continue using `previous_response_id`, retrieve or delete a stored response, list stored input items, or return deferred Chat completions. `store: true` may be accepted on creation, but that does not establish response storage or retrieval support.

File attachments have not worked with the tested inline-text and PDF URL inputs. Image-generation requests returned text without images, and tool search did not complete server-side discovery. These capabilities are not verified as available. Collections search also requires a valid collection resource and has not been verified.

Chat ignores `frequency_penalty`, `presence_penalty`, `logit_bias`, `stop`, `logprobs` and `top_logprobs`. Responses ignores `background`, `context_management`, `metadata`, `truncation`, `logprobs` and `top_logprobs`. They are not forwarded or offered as active controls.

## Errors

An invalid request returns an error instead of a completed answer. Check the field values and the [public error reference](https://toklab.ai/docs/api/errors). Requests that return an error are not charged.

## Optional LLM group

The groups you can use depend on your account permissions and the model. The [pricing page](https://toklab.ai/pricing) lists each group's prices.

API calls keep your API key and model ID. To select a group, send its exact name in the optional `X-SeedRouter-Group` request header, or append it to the model ID as `model:<group>` (see [Model tiers](https://toklab.ai/docs/api/model-tiers)). Replace `GROUP_NAME` below with one of your groups. Omit the header or use `auto` to keep the key's default behavior.

```http
X-SeedRouter-Group: GROUP_NAME
```

A restricted API key may have fewer group options than your account. Requests use the selected group's pricing and do not switch to another group if it is unavailable. This option supports HTTP LLM calls, including SSE; it does not apply to WebSocket, image or video calls.

To see the groups your key can use, call `GET /v1/models`: it lists `model:<group>` next to the model ID for every model your key can call in more than one group.

## Pricing

Every rate this model is billed at, read live from the price list billing uses. A tier applies when its condition matches, checked top to bottom.

### grok-4.7

| When | Input (per 1M tokens) | Output (per 1M tokens) | Cache read (per 1M tokens) |
| --- | --- | --- | --- |
| Context < 200K · Service tier: priority | $2.40 | $7.20 | $0.60 |
| Context < 200K · Service tier: fast | $2.40 | $7.20 | $0.60 |
| Context < 200K | $1.20 | $3.60 | $0.30 |
| Service tier: priority | $4.80 | $14.40 | $1.20 |
| Service tier: fast | $4.80 | $14.40 | $1.20 |
| Otherwise | $2.40 | $7.20 | $0.60 |