> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.beatapi.io/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.beatapi.io/_mcp/server. # Grok Responses POST https://direct.beatapi.io/v1/responses Content-Type: application/json Call Grok 4.7 through the OpenAI Responses API with a BeatAPI key.- One endpoint, `POST /v1/responses`, for the current Grok model, `grok-4.7`. - Streaming and function calling. Grok reasons before it answers. - Works with the OpenAI SDK: change the base URL and use a BeatAPI key. For an existing Chat Completions integration, see [Chat Completions](/text-api/grok/chat-completions). - Conversation state is not stored on the server: send the whole history in `input` on every turn.Use `https://direct.beatapi.io` as the base URL for text requests: it is not subject to Cloudflare's 100-second limit, so a long non-streaming request is not cut off. `https://api.beatapi.io` also works and is the fallback if `direct.beatapi.io` is unreachable from your network. The key, models and prices are the same on both. Image and video APIs use `https://api.beatapi.io` only.POST/v1/responsesTry itOpens this endpoint in the API Explorer. Enter your BeatAPI API key and send: the call is real and is billed to your own balance.## ModelsSend one of these IDs as `model`. Each is a separate model; do not treat them as aliases of each other.| Model ID | Context (tokens) | Max output (tokens) | Positioning | Input, USD per 1M tokens | Output, USD per 1M tokens | Notes | | ---------- | ---------------- | ------------------- | ------------------------------------------------------------------------------------------------------------------ | ------------------------ | ------------------------- | ------------------------------------------------------------------------------------------------------------------ | | `grok-4.7` | 500,000 | — | xAI's most capable Grok for coding, agents, and knowledge work; works longer on hard tasks and checks its own work | \$0.70 | \$2.10 | The current flagship for coding, agents and knowledge work. It works longer on hard tasks and checks its own work. |- Prices are the base tier, discount already applied. A long-context tier, cached-input rates and cache writes are not in this table; see the [price table](https://beatapi.io/pricing). - `—` means the catalogue does not publish the number.Older IDs of this family still work and are listed on [Legacy models](/text-api/legacy-models).## Quick startInstall the `openai` package on your server, keep the key in `BEATAPI_API_KEY`, and never put it in browser code. `output_text` is the SDK's shortcut for the answer text. These are request examples, not recorded model outputs.Read the answer from `output_text` (or from the `output_text` parts of `output`), then check `status` and `usage`. An HTTP 200 alone does not prove the answer satisfies your task: validate it in your application. Text requests return directly; do not poll `/v1/tasks` for them.```bash title="cURL" curl --request POST \ --url https://direct.beatapi.io/v1/responses \ --header "Authorization: Bearer $BEATAPI_API_KEY" \ --header 'Content-Type: application/json' \ --data '{ "model": "grok-4.7", "max_output_tokens": 2000, "input": "Design a resilient webhook retry strategy for a payments API." }' ``````python title="Python" import os from openai import OpenAI client = OpenAI(api_key=os.environ["BEATAPI_API_KEY"], base_url="https://direct.beatapi.io/v1") response = client.responses.create( model="grok-4.7", max_output_tokens=2000, input="Design a resilient webhook retry strategy for a payments API.", ) print(response.output_text) ``````javascript title="JavaScript" import OpenAI from "openai"; const client = new OpenAI({ apiKey: process.env.BEATAPI_API_KEY, baseURL: "https://direct.beatapi.io/v1" }); const response = await client.responses.create({ "model": "grok-4.7", "max_output_tokens": 2000, "input": "Design a resilient webhook retry strategy for a payments API." }); console.log(response.output_text); ```## Endpoint and authentication`POST https://direct.beatapi.io/v1/responses`Authorization string Required`Bearer `. The key works with or without the `sk-` prefix.## Request parametersStandard OpenAI Responses fields are accepted. Request-format compatibility does not mean every model-specific option or hosted tool is supported, so test the options you rely on.model string RequiredThe exact model ID.**Allowed values**: `grok-4.7`- Each ID is a separate model, not an alias of another. - Call `GET /v1/models` with your key to confirm which models are enabled for it. - The older IDs `grok-4.5` and `grok-4.6` still work and are listed on [Legacy models](/text-api/legacy-models).input string | object[] RequiredThe prompt: a string, or an array of input items such as messages, function calls and their outputs.Conversation state is not stored on the server. `previous_response_id`, `conversation`, `prompt` and `context_management` are not supported: send the whole history in `input` on every turn.instructions string OptionalA system-level instruction placed before `input`.max_output_tokens integer OptionalUpper bound on the generated tokens, reasoning included.- The gateway does not compare your value with the model's max output from the table above. Keep it at or below that number. - The value is also used to estimate how much balance a request needs. A very large value can be refused with `402 insufficient_credits` even when the real output would be small. Set it to what you need.A reasoning model writes its reasoning first. If `max_output_tokens` is too small, the reasoning can use all of it and the answer text comes back empty or cut off. Leave room for both, and raise the value when that happens.stream boolean OptionalDefault: falseReturn the answer as server-sent events. See the Streaming section below.**Default**: `false`temperature number OptionalSampling temperature. Change this or `top_p`, not both.top_p number OptionalNucleus sampling threshold.tools object[] OptionalFunction tools the model may call. The model answers with a `function_call` output item; return the result as a `function_call_output` input item with the same `call_id`. Hosted tools (web search, file search and the like) are not part of this list.tool_choice string | object OptionalWhether the model may, must or must not call a tool. Test the value you rely on with your model.## Prompts over 200,000 tokensOnce a prompt reaches 200,000 tokens, a higher rate applies to every token of that request: input, cached input and output all double. Below the threshold the standard rate applies to the whole request. Size long prompts against 200,000 tokens, not against the context window.## ResponseA non-streaming call returns one JSON object. This is an abbreviated example.```json { "id": "resp_example", "object": "response", "model": "grok-4.7", "status": "completed", "output": [ { "type": "message", "role": "assistant", "content": [ { "type": "output_text", "text": "Retry with exponential backoff and jitter, and make every handler idempotent." } ] } ], "usage": { "input_tokens": 19, "output_tokens": 16, "total_tokens": 35 } } ```### Response fields| Field | Type | Description | | ------------------------- | ---------- | --------------------------------------------------------------------------------------------------------------- | | `id` | `string` | The response ID. Log it, together with the request ID, for support and billing audits. | | `model` | `string` | The model that answered. | | `status` | `string` | `completed` for a finished answer. | | `output[]` | `object[]` | Output items: `message`, `reasoning` and `function_call`. The SDK's `output_text` joins the text parts for you. | | `output[].content[].text` | `string` | The answer text of a `message` item, in a part of type `output_text`. | | `usage` | `object` | Token counts. Calls are metered from actual token usage. |## StreamingSet `"stream": true`. The stream starts with `response.created`, carries the answer in `response.output_text.delta` events and ends with `response.completed`.- The response is `text/event-stream`; without streaming it is `application/json`. - A function call arrives as its own output item, and its arguments stream in `response.function_call_arguments.delta` events. - A failure before the model is called is returned as a normal JSON error with an HTTP status, not as a stream event. - Set explicit timeouts and reconnect a streamed response safely.```text event: response.created data: {"type":"response.created","response":{"id":"resp_example","status":"in_progress"}} event: response.output_text.delta data: {"type":"response.output_text.delta","delta":"Retry"} event: response.output_text.delta data: {"type":"response.output_text.delta","delta":" with backoff"} event: response.completed data: {"type":"response.completed","response":{"id":"resp_example","status":"completed"}} ```## Errors| Error or symptom | Cause | Fix | | -------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- | | The answer text is empty or cut off | A reasoning model used the whole `max_output_tokens` budget on reasoning. | Raise `max_output_tokens`, within the model max output. | | An error mentioning `previous_response_id`, `conversation`, `prompt` or `context_management` | These stateful fields are not supported. | Remove them and send the whole history in `input`. | | `402 insufficient_credits` | Balance below the price of the request, often because `max_output_tokens` is very large. | Top up, or lower `max_output_tokens`. | | `403 forbidden` | The account is on free credit and the model is not on the free list, or the model is outside the key's group. | Top up, use a free model, or use a key whose group can reach the model. | | `404 not_found` | Unknown model ID, or not enabled for this key. | List the enabled models with `GET /v1/models`. | | `429 rate_limit_exceeded` | Account or free-model limit reached. | Wait `Retry-After`, then retry. |### HTTP errors at a glanceAuthentication, routing, rate-limit and unknown-model failures are answered before the model is called, in the BeatAPI envelope: `error.code`, `error.message`, `retryable`, `request_id`. Every other failure keeps the OpenAI SDK shape `{"error": {"message", "type", "code"}}`: the code is in `error.code` and the request id ends `message`. See [Errors](/errors#text-endpoints).| HTTP status | Code | What to do | | ----------- | ---------------------------------------------------------- | -------------------------------------------------------------------------------------------- | | 400 | `bad_request`, `content_policy_violation` | Fix the request or the input; do not resend it unchanged. | | 401 | `missing_api_key`, `invalid_api_key` | Check the key. Do not retry. | | 402 | `insufficient_credits` | Top up, or raise the key's limit. A very large `max_tokens` can trigger it. | | 403 | `forbidden` | The model is outside the key's group or IP allowlist, or free credit cannot call this model. | | 404 | `not_found` | Unknown model: list the enabled ones with `GET /v1/models`. | | 429 | `rate_limit_exceeded` | Wait `Retry-After` or `retry_after_seconds`, then retry with backoff. | | 500 | `internal_error`, `temporary_error` | Retry once or twice with backoff. | | 503 | `model_unavailable`, `upstream_timeout`, `temporary_error` | Retry with backoff, or use another model. |Full code table and retry policy: [Errors](/errors#text-endpoints).## Notes- Grok models also answer on [Chat Completions](/text-api/grok/chat-completions) and [Anthropic Messages](/text-api/grok/messages). - Grok reasons by default. Reasoning tokens are counted in the output tokens and billed as output, so budget `max_output_tokens` for the reasoning as well as the answer. - Keep API keys on trusted servers, log the response request ID, and retry only `429`, `500` and `503`. Reference: https://docs.beatapi.io/api-reference/text-api/grok-responses ## Authentication - `Authorization` header (bearer token, required) — Send your API key as `Authorization: Bearer `. ## Servers - `https://direct.beatapi.io` (Direct, default) - `https://api.beatapi.io` (API) ## Request ### Body (application/json) This endpoint expects an object. - `model` (enum, required) — The exact model ID. Each ID is a separate model, not an alias of another. Call `GET /v1/models` with your key to confirm which models are enabled for it. The older IDs `grok-4.5` and `grok-4.6` still work and are listed on [Legacy models](/text-api/legacy-models). `grok-4.7` - Allowed values: `grok-4.7` - `input` (V1ResponsesPostRequestBodyContentApplicationJsonSchemaInput, required) — The prompt: a string, or an array of input items such as messages, function calls and their outputs. Conversation state is not stored on the server. `previous_response_id`, `conversation`, `prompt` and `context_management` are not supported: send the whole history in `input` on every turn. - `instructions` (string, optional) — A system-level instruction placed before `input`. - `max_output_tokens` (integer, optional) — Upper bound on the generated tokens, reasoning included. The gateway does not compare your value with the model's max output from the table above. Keep it at or below that number. The value is also used to estimate how much balance a request needs. A very large value can be refused with `402 insufficient_credits` even when the real output would be small. Set it to what you need. A reasoning model writes its reasoning first. If `max_output_tokens` is too small, the reasoning can use all of it and the answer text comes back empty or cut off. Leave room for both, and raise the value when that happens. - `stream` (boolean, optional, default: false) — Return the answer as server-sent events. See the Streaming section below. - `temperature` (double, optional) — Sampling temperature. Change this or `top_p`, not both. - `top_p` (double, optional) — Nucleus sampling threshold. - `tools` (list of V1ResponsesPostRequestBodyContentApplicationJsonSchemaToolsItems, optional) — Function tools the model may call. The model answers with a `function_call` output item; return the result as a `function_call_output` input item with the same `call_id`. Hosted tools (web search, file search and the like) are not part of this list. - `tool_choice` (V1ResponsesPostRequestBodyContentApplicationJsonSchemaToolChoice, optional) — Whether the model may, must or must not call a tool. Test the value you rely on with your model. ## Response ### 200 A non-streaming call returns one JSON object. This is an abbreviated example. - `id` (string, optional) — The response ID. Log it, together with the request ID, for support and billing audits. - `model` (string, optional) — The model that answered. - `status` (string, optional) — `completed` for a finished answer. - `output` (list of V1ResponsesPostResponsesContentApplicationJsonSchemaOutputItems, optional) — Output items: `message`, `reasoning` and `function_call`. The SDK's `output_text` joins the text parts for you. - `usage` (V1ResponsesPostResponsesContentApplicationJsonSchemaUsage, optional) — Token counts. Calls are metered from actual token usage. ## Errors ### 400 Bad Request Error `bad_request`, `content_policy_violation` Fix the request or the input; do not resend it unchanged. Authentication, routing, rate-limit and unknown-model failures are answered before the model is called, in the BeatAPI envelope: `error.code`, `error.message`, `retryable`, `request_id`. Every other failure keeps the OpenAI SDK shape `{"error": {"message", "type", "code"}}`: the code is in `error.code` and the request id ends `message`. See [Errors](/errors#text-endpoints). - `map from string to any` ### 401 Unauthorized Error `missing_api_key`, `invalid_api_key` Check the key. Do not retry. Authentication, routing, rate-limit and unknown-model failures are answered before the model is called, in the BeatAPI envelope: `error.code`, `error.message`, `retryable`, `request_id`. Every other failure keeps the OpenAI SDK shape `{"error": {"message", "type", "code"}}`: the code is in `error.code` and the request id ends `message`. See [Errors](/errors#text-endpoints). - `map from string to any` ### 402 Payment Required Error `insufficient_credits` Top up, or raise the key's limit. A very large `max_tokens` can trigger it. Authentication, routing, rate-limit and unknown-model failures are answered before the model is called, in the BeatAPI envelope: `error.code`, `error.message`, `retryable`, `request_id`. Every other failure keeps the OpenAI SDK shape `{"error": {"message", "type", "code"}}`: the code is in `error.code` and the request id ends `message`. See [Errors](/errors#text-endpoints). - `map from string to any` ### 403 Forbidden Error `forbidden` The model is outside the key's group or IP allowlist, or free credit cannot call this model. Authentication, routing, rate-limit and unknown-model failures are answered before the model is called, in the BeatAPI envelope: `error.code`, `error.message`, `retryable`, `request_id`. Every other failure keeps the OpenAI SDK shape `{"error": {"message", "type", "code"}}`: the code is in `error.code` and the request id ends `message`. See [Errors](/errors#text-endpoints). - `map from string to any` ### 404 Not Found Error `not_found` Unknown model: list the enabled ones with `GET /v1/models`. Authentication, routing, rate-limit and unknown-model failures are answered before the model is called, in the BeatAPI envelope: `error.code`, `error.message`, `retryable`, `request_id`. Every other failure keeps the OpenAI SDK shape `{"error": {"message", "type", "code"}}`: the code is in `error.code` and the request id ends `message`. See [Errors](/errors#text-endpoints). - `map from string to any` ### 429 Too Many Requests Error `rate_limit_exceeded` Wait `Retry-After` or `retry_after_seconds`, then retry with backoff. Authentication, routing, rate-limit and unknown-model failures are answered before the model is called, in the BeatAPI envelope: `error.code`, `error.message`, `retryable`, `request_id`. Every other failure keeps the OpenAI SDK shape `{"error": {"message", "type", "code"}}`: the code is in `error.code` and the request id ends `message`. See [Errors](/errors#text-endpoints). - `map from string to any` ### 500 Internal Server Error `internal_error`, `temporary_error` Retry once or twice with backoff. Authentication, routing, rate-limit and unknown-model failures are answered before the model is called, in the BeatAPI envelope: `error.code`, `error.message`, `retryable`, `request_id`. Every other failure keeps the OpenAI SDK shape `{"error": {"message", "type", "code"}}`: the code is in `error.code` and the request id ends `message`. See [Errors](/errors#text-endpoints). - `map from string to any` ### 503 Service Unavailable Error `model_unavailable`, `upstream_timeout`, `temporary_error` Retry with backoff, or use another model. Authentication, routing, rate-limit and unknown-model failures are answered before the model is called, in the BeatAPI envelope: `error.code`, `error.message`, `retryable`, `request_id`. Every other failure keeps the OpenAI SDK shape `{"error": {"message", "type", "code"}}`: the code is in `error.code` and the request id ends `message`. See [Errors](/errors#text-endpoints). - `map from string to any` ## Types ### V1ResponsesPostRequestBodyContentApplicationJsonSchemaInput The prompt: a string, or an array of input items such as messages, function calls and their outputs. Conversation state is not stored on the server. `previous_response_id`, `conversation`, `prompt` and `context_management` are not supported: send the whole history in `input` on every turn. ### V1ResponsesPostRequestBodyContentApplicationJsonSchemaToolsItems ### V1ResponsesPostRequestBodyContentApplicationJsonSchemaToolChoice Whether the model may, must or must not call a tool. Test the value you rely on with your model. ### V1ResponsesPostResponsesContentApplicationJsonSchemaOutputItems - `content` (list of V1ResponsesPostResponsesContentApplicationJsonSchemaOutputItemsContentItems, optional) ### V1ResponsesPostResponsesContentApplicationJsonSchemaUsage Token counts. Calls are metered from actual token usage. ### V1ResponsesPostResponsesContentApplicationJsonSchemaOutputItemsContentItems - `text` (string, optional) — The answer text of a `message` item, in a part of type `output_text`. ## Examples **Request** ```json { "model": "grok-4.7", "input": "Design a resilient webhook retry strategy for a payments API.", "max_output_tokens": 2000 } ``` **Response** ```json { "id": "resp_example", "model": "grok-4.7", "status": "completed", "output": [ { "content": [ { "text": "Retry with exponential backoff and jitter, and make every handler idempotent.", "type": "output_text" } ], "role": "assistant", "type": "message" } ], "usage": { "input_tokens": 19, "output_tokens": 16, "total_tokens": 35 }, "object": "response" } ``` **SDK Code** ```python Quick start import requests url = "https://direct.beatapi.io/v1/responses" payload = { "model": "grok-4.7", "input": "Design a resilient webhook retry strategy for a payments API.", "max_output_tokens": 2000 } headers = { "Authorization": "Bearer ", "Content-Type": "application/json" } response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` ```javascript Quick start const url = 'https://direct.beatapi.io/v1/responses'; const options = { method: 'POST', headers: {Authorization: 'Bearer ', 'Content-Type': 'application/json'}, body: '{"model":"grok-4.7","input":"Design a resilient webhook retry strategy for a payments API.","max_output_tokens":2000}' }; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go Quick start package main import ( "fmt" "strings" "net/http" "io" ) func main() { url := "https://direct.beatapi.io/v1/responses" payload := strings.NewReader("{\n \"model\": \"grok-4.7\",\n \"input\": \"Design a resilient webhook retry strategy for a payments API.\",\n \"max_output_tokens\": 2000\n}") req, _ := http.NewRequest("POST", url, payload) req.Header.Add("Authorization", "Bearer ") req.Header.Add("Content-Type", "application/json") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby Quick start require 'uri' require 'net/http' url = URI("https://direct.beatapi.io/v1/responses") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Post.new(url) request["Authorization"] = 'Bearer ' request["Content-Type"] = 'application/json' request.body = "{\n \"model\": \"grok-4.7\",\n \"input\": \"Design a resilient webhook retry strategy for a payments API.\",\n \"max_output_tokens\": 2000\n}" response = http.request(request) puts response.read_body ``` ```java Quick start import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.post("https://direct.beatapi.io/v1/responses") .header("Authorization", "Bearer ") .header("Content-Type", "application/json") .body("{\n \"model\": \"grok-4.7\",\n \"input\": \"Design a resilient webhook retry strategy for a payments API.\",\n \"max_output_tokens\": 2000\n}") .asString(); ``` ```php Quick start request('POST', 'https://direct.beatapi.io/v1/responses', [ 'body' => '{ "model": "grok-4.7", "input": "Design a resilient webhook retry strategy for a payments API.", "max_output_tokens": 2000 }', 'headers' => [ 'Authorization' => 'Bearer ', 'Content-Type' => 'application/json', ], ]); echo $response->getBody(); ``` ```csharp Quick start using RestSharp; var client = new RestClient("https://direct.beatapi.io/v1/responses"); var request = new RestRequest(Method.POST); request.AddHeader("Authorization", "Bearer "); request.AddHeader("Content-Type", "application/json"); request.AddParameter("application/json", "{\n \"model\": \"grok-4.7\",\n \"input\": \"Design a resilient webhook retry strategy for a payments API.\",\n \"max_output_tokens\": 2000\n}", ParameterType.RequestBody); IRestResponse response = client.Execute(request); ``` ```swift Quick start import Foundation let headers = [ "Authorization": "Bearer ", "Content-Type": "application/json" ] let parameters = [ "model": "grok-4.7", "input": "Design a resilient webhook retry strategy for a payments API.", "max_output_tokens": 2000 ] as [String : Any] let postData = JSONSerialization.data(withJSONObject: parameters, options: []) let request = NSMutableURLRequest(url: NSURL(string: "https://direct.beatapi.io/v1/responses")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "POST" request.allHTTPHeaderFields = headers request.httpBody = postData as Data let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ```