---
title: Chat Completions API
description: Create OpenAI-compatible chat completions with SubQ.
---

> Status: Early access

Use the Chat Completions API to generate a response from [SubQ Savant](/using-the-api/models/#subq-savant-14) (`subq-savant-1.4`) for a list of conversation messages. Savant is early access, enabled per organization. [Request access](https://subq.ai/small#waitlist). For server-managed multi-turn conversations with system instructions and built-in web search, see [Responses API](/endpoints/responses-api/).

```text
POST /v1/chat/completions
```

## Request body

Send a JSON object with the required `model` and `messages` fields. Omit optional fields unless you need to change generation behavior.

| Field               | Type                | Required | Description                                                                                                                                                    |
| ------------------- | ------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `model`             | string              | Yes      | Model ID to use, such as `subq-savant-1.4`. See [Models](/using-the-api/models/).                                                                              |
| `messages`          | array               | Yes      | Conversation messages in order. Must contain at least one message.                                                                                             |
| `stream`            | boolean             | No       | When `false` or omitted, returns one JSON response. When `true`, returns server-sent events.                                                                   |
| `temperature`       | number              | No       | Fixed at `1`. Omit it or send `1`. Any other value returns `400` `unsupported_value`. See [Restricted parameters](#restricted-parameters).                     |
| `max_tokens`        | integer             | No       | Caps generated tokens. Must be at least `1`. See [Token limits](#token-limits).                                                                                |
| `top_p`             | number              | No       | Nucleus sampling value from `0` to `1`.                                                                                                                        |
| `stop`              | string or string\[] | No       | Up to 4 sequences where generation stops. Each sequence is at most 256 characters.                                                                             |
| `n`                 | integer             | No       | Number of choices to generate, from `1` to `8`. Each comes back as its own entry in `choices`.                                                                 |
| `seed`              | integer             | No       | Sampling seed. Repeating a request with the same seed and parameters aims for the same output; determinism is best-effort.                                     |
| `presence_penalty`  | number              | No       | From `-2` to `2`. Positive values penalize tokens that have already appeared, nudging the model toward new topics.                                             |
| `frequency_penalty` | number              | No       | From `-2` to `2`. Positive values penalize tokens in proportion to how often they have appeared, reducing repetition.                                          |
| `reasoning_effort`  | string              | No       | How much the model reasons before answering: `low`, `high` (the default), or `max`. Reasoning cannot be turned off. See [Reasoning effort](#reasoning-effort). |
| `response_format`   | object              | No       | Constrain the assistant reply to a JSON Schema. See [Structured outputs](/using-the-api/structured-outputs/).                                                  |
| `tools`             | array               | No       | Function tools the model may call. See [Function calling](/using-the-api/function-calling/).                                                                   |
| `tool_choice`       | string              | No       | Whether the model may call tools: `"auto"` (the default) or `"none"`. See [Tool choice](/using-the-api/function-calling/#tool-choice).                         |
| `store`             | boolean or null     | No       | Set `false` to keep this request and response out of storage. Defaults to `true`. See [Storage](#storage).                                                     |
| `metadata`          | object or null      | No       | Up to 16 key-value string pairs attached to the request, for your own tracking. Echoed back on the response. See [Metadata](#metadata).                        |

This page documents the non-streaming response. For a non-streaming request, omit `stream` or set it to `false`.

### Restricted parameters

A request that breaks one of these rules returns `400`, and nothing is generated.

| Parameter                    | Rule                                                                                                                                                                     | `code`                  |
| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------- |
| `temperature`                | Fixed at `1`. Omit it or send `1`.                                                                                                                                       | `unsupported_value`     |
| `reasoning_effort`           | `none` is rejected. Reasoning cannot be turned off, including through a `reasoning` object with `effort: "none"` or `enabled: false`. Use `low` for the least reasoning. | `unsupported_value`     |
| `logprobs`                   | `true` is rejected.                                                                                                                                                      | `unsupported_parameter` |
| `top_logprobs`               | Any value from `1` to `20` is rejected.                                                                                                                                  | `unsupported_parameter` |
| `logit_bias`                 | A map with any entries is rejected.                                                                                                                                      | `unsupported_parameter` |
| `audio`, `modalities`        | `audio`, or `modalities` that includes `"audio"`, is rejected. Audio output is not supported; `modalities: ["text"]` is accepted.                                        | `unsupported_parameter` |
| `web_search_options`         | Rejected. Use [web search](/endpoints/responses-api/#web-search) on the Responses API.                                                                                   | `unsupported_parameter` |
| `functions`, `function_call` | Deprecated and rejected. Use `tools` and `tool_choice`.                                                                                                                  | `unsupported_parameter` |

For `unsupported_parameter`, `param` names the field. The empty forms are accepted: `null` for any of them, `logprobs: false`, `top_logprobs: 0`, and `logit_bias: {}`.

## Token limits

`max_tokens` caps the tokens generated in the completion, reasoning included. It does not count the prompt.

- **Budget for the reasoning and the answer together.** The model [reasons before answering](#reasoning-effort) from the same allowance, so a request can return `200` with `content` set to `null` and `finish_reason` of `"length"`: billed, with nothing visible.
- Input and output share the 4M-token [context window](/using-the-api/models/#subq-savant-14). If the input plus `max_tokens` cannot fit, the API returns `400` `context_length_exceeded`.
- Send `max_tokens`, not `max_completion_tokens`.
- The minimum is `1`. If omitted, the response can use all remaining context.
- If generation hits the cap, `choices[0].finish_reason` is `"length"`.

```json
{
  "model": "subq-savant-1.4",
  "messages": [
    {
      "role": "user",
      "content": "In three bullets, explain the difference between indemnification, limitation of liability, and insurance requirements in a software contract."
    }
  ],
  "max_tokens": 500
}
```

```bash title="cURL"
curl --request POST \
  --url https://api.subq.ai/v1/chat/completions \
  --header "Authorization: Bearer $SUBQ_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '
{
  "model": "subq-savant-1.4",
  "messages": [
    {
      "role": "user",
      "content": "In three bullets, explain the difference between indemnification, limitation of liability, and insurance requirements in a software contract."
    }
  ],
  "max_tokens": 500
}
'
```

```ts title="TypeScript"
import OpenAI from "openai";

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

const completion = await client.chat.completions.create({
  model: "subq-savant-1.4",
  messages: [
    {
      role: "user",
      content: "In three bullets, explain the difference between indemnification, limitation of liability, and insurance requirements in a software contract."
    }
  ],
  max_tokens: 500
});

console.log(completion.choices[0]?.message?.content);
```

```py title="Python"
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["SUBQ_API_KEY"],
    base_url="https://api.subq.ai/v1",
)

completion = client.chat.completions.create(
    model="subq-savant-1.4",
    messages=[
        {
            "role": "user",
            "content": "In three bullets, explain the difference between indemnification, limitation of liability, and insurance requirements in a software contract.",
        },
    ],
    max_tokens=500,
)

print(completion.choices[0].message.content)
```

### Detecting a response spent on reasoning

```json
{
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": null,
        "reasoning": "The user wants three bullets comparing indemnification, limitation of liability, and insurance requirements. Indemnification shifts third-party claim costs to one party. Limitation of liability caps"
      },
      "finish_reason": "length"
    }
  ],
  "usage": {
    "prompt_tokens": 126,
    "completion_tokens": 64,
    "total_tokens": 190,
    "completion_tokens_details": { "reasoning_tokens": 64 }
  }
}
```

Test `message.content` directly—a `null` is easy to pass downstream as if it were
an answer.

```js
const choice = completion.choices[0];

if (choice.finish_reason === "length" && !choice.message.content) {
  // The cap was consumed before the answer began. Retry with a larger
  // max_tokens, or a lower reasoning_effort.
  // Retrying with the same parameters will produce the same result.
}
```

## Reasoning effort

SubQ Savant reasons before it answers. Set top-level `reasoning_effort` to control how much. Reasoning cannot be turned off: `none` returns `400` `unsupported_value`. For the least reasoning, use `low`.

| Value  | Use it for                                                                          |
| ------ | ----------------------------------------------------------------------------------- |
| `low`  | Short answers, extraction, and latency-sensitive requests.                          |
| `high` | The default. Most analysis, drafting, and agent loops.                              |
| `max`  | Hard questions over long inputs, where accuracy matters more than latency and cost. |

`minimal`, `medium`, and `xhigh` are accepted for OpenAI compatibility and run as `low`, `high`, and `max`.

- **Reasoning tokens are billed as output tokens.** They are included in `usage.completion_tokens` and counted in `max_tokens`. A one-line answer can bill many times more output tokens than its visible text.
- **Higher effort doesn't always use more tokens.** Token use varies by prompt, so compare efforts on your own prompts.

```json
{
  "model": "subq-savant-1.4",
  "messages": [
    {
      "role": "system",
      "content": "You are a legal research assistant. Use plain language. Cite only facts in the conversation."
    },
    {
      "role": "user",
      "content": "Summarize the major self-preferencing antitrust cases since 2010 and list open questions for counsel."
    }
  ],
  "reasoning_effort": "max"
}
```

```bash title="cURL"
curl --request POST \
  --url https://api.subq.ai/v1/chat/completions \
  --header "Authorization: Bearer $SUBQ_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '
{
  "model": "subq-savant-1.4",
  "messages": [
    {
      "role": "system",
      "content": "You are a legal research assistant. Use plain language. Cite only facts in the conversation."
    },
    {
      "role": "user",
      "content": "Summarize the major self-preferencing antitrust cases since 2010 and list open questions for counsel."
    }
  ],
  "reasoning_effort": "max"
}
'
```

```ts title="TypeScript"
import OpenAI from "openai";

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

const completion = await client.chat.completions.create({
  model: "subq-savant-1.4",
  messages: [
    {
      role: "system",
      content: "You are a legal research assistant. Use plain language. Cite only facts in the conversation."
    },
    {
      role: "user",
      content: "Summarize the major self-preferencing antitrust cases since 2010 and list open questions for counsel."
    }
  ],
  reasoning_effort: "max"
});

console.log(completion.choices[0]?.message?.content);
```

```py title="Python"
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["SUBQ_API_KEY"],
    base_url="https://api.subq.ai/v1",
)

completion = client.chat.completions.create(
    model="subq-savant-1.4",
    messages=[
        {
            "role": "system",
            "content": "You are a legal research assistant. Use plain language. Cite only facts in the conversation.",
        },
        {
            "role": "user",
            "content": "Summarize the major self-preferencing antitrust cases since 2010 and list open questions for counsel.",
        },
    ],
    reasoning_effort="max",
)

print(completion.choices[0].message.content)
```

For classification and routing with probabilities, use the [Decisions API](/endpoints/decisions-api/).

## Reasoning output

The model's reasoning comes back separately from its answer, so `content` holds only the answer.

| Field                                              | Contains                                                                            |
| -------------------------------------------------- | ----------------------------------------------------------------------------------- |
| `choices[0].message.reasoning`                     | The reasoning text. `null` if the response has no reasoning text.                   |
| `choices[0].delta.reasoning`                       | When streaming, reasoning text arrives in these deltas before the `content` deltas. |
| `usage.completion_tokens_details.reasoning_tokens` | How many of `completion_tokens` were reasoning.                                     |

```json {7,18}
{
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "reasoning": "The clause lets either party terminate for convenience. The notice period is ninety (90) days and the notice must be written. One sentence.",
        "content": "You need to give 90 days' written notice."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 58,
    "completion_tokens": 44,
    "total_tokens": 102,
    "prompt_tokens_details": { "cached_tokens": 0 },
    "completion_tokens_details": { "reasoning_tokens": 32 }
  }
}
```

`reasoning` is a SubQ field, so the SDK types don't declare it. Read it like this:

```ts title="TypeScript"
import OpenAI from "openai";

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

const completion = await client.chat.completions.create({
  model: "subq-savant-1.4",
  messages: [
    {
      role: "user",
      content:
        "A vendor contract says: Either party may terminate this Agreement for convenience upon ninety (90) days prior written notice. How much notice do we need to give to cancel? Answer in one sentence.",
    },
  ],
  reasoning_effort: "low",
});

const message = completion.choices[0].message;

// `reasoning` is a SubQ field the SDK types don't declare.
const { reasoning } = message as typeof message & { reasoning?: string | null };

console.log("Answer:", message.content);
console.log("Reasoning:", reasoning);
console.log(
  "Reasoning tokens:",
  completion.usage?.completion_tokens_details?.reasoning_tokens,
);
```

```py title="Python"
import os

from openai import OpenAI

client = OpenAI(
    api_key=os.environ["SUBQ_API_KEY"],
    base_url="https://api.subq.ai/v1",
)

completion = client.chat.completions.create(
    model="subq-savant-1.4",
    messages=[
        {
            "role": "user",
            "content": (
                "A vendor contract says: Either party may terminate this "
                "Agreement for convenience upon ninety (90) days prior written "
                "notice. How much notice do we need to give to cancel? Answer "
                "in one sentence."
            ),
        }
    ],
    reasoning_effort="low",
)

message = completion.choices[0].message

# `reasoning` is a SubQ field the SDK types don't declare.
reasoning = getattr(message, "reasoning", None)

print("Answer:", message.content)
print("Reasoning:", reasoning)
print(
    "Reasoning tokens:",
    completion.usage.completion_tokens_details.reasoning_tokens,
)
```

Show reasoning to your users or log it for debugging, but parse only `content` as the answer.

## Messages

Each message has a `role` and, usually, `content`.

| Field     | Type                      | Required                                                | Description                                                   |
| --------- | ------------------------- | ------------------------------------------------------- | ------------------------------------------------------------- |
| `role`    | string                    | Yes                                                     | One of `system`, `user`, `assistant`, or `tool`.              |
| `content` | string or content part\[] | Yes, except on an `assistant` message with `tool_calls` | Message text as a plain string, or an array of content parts. |

Use `system` for durable instructions, `user` for user input, `assistant` for prior model responses (including messages that contain `tool_calls`), and `tool` for tool result messages already produced by your application. See [Function calling](/using-the-api/function-calling/).

The simplest content shape is a string:

```json
{
  "role": "user",
  "content": "Summarize this release note."
}
```

You can also send text content parts:

```json
{
  "role": "user",
  "content": [
    { "type": "text", "text": "Summarize this release note." }
  ]
}
```

For document input, send a text instruction and one or more `file` parts in the same `user` message:

```json
{
  "role": "user",
  "content": [
    { "type": "text", "text": "Summarize these documents." },
    {
      "type": "file",
      "filename": "financial-report-2026.pdf",
      "mime_type": "application/pdf",
      "file_data": "JVBERi0xLjcKJdDUxdgK..."
    },
    {
      "type": "file",
      "filename": "meeting-notes.txt",
      "mime_type": "text/plain",
      "file_data": "U3ViUSBkb2N1bWVudCBub3Rlcy4uLg=="
    }
  ]
}
```

File parts accept inline base64 (`file_data`) or an uploaded `file_id`, set directly on the part. Inline `file_data` takes text formats, PDF, Word (`.doc`/`.docx`), and PNG, JPEG, or WebP images. `mime_type` is optional: SubQ detects the type from the bytes and filename, so give Word files a `.doc` or `.docx` `filename`. A `file_id` can point at an uploaded document or image. A nested `file` object is not accepted. Audio, video, URL-based file inputs, and other content part types are rejected. See [Sending files](/using-the-api/file-inputs/) for file part examples. For the Responses API, use `input_file` with `file_id` instead — see [Uploaded files](/endpoints/responses-api/#uploaded-files-file_id).

### Images

Send an image as an `image_url` part holding a base64 data URI, next to a `text` part that says what to do with it:

```json
{
  "role": "user",
  "content": [
    { "type": "text", "text": "What is the total due on this invoice?" },
    {
      "type": "image_url",
      "image_url": { "url": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUg..." }
    }
  ]
}
```

Or send the image as a `file` part: inline `file_data`, or the `file_id` of a PNG, JPEG, or WebP uploaded with the [Files API](/endpoints/files-api/). Either way it reaches the model as image input.

```json
{
  "role": "user",
  "content": [
    { "type": "text", "text": "What is the total due on this invoice?" },
    { "type": "file", "file_id": "file_abc123" }
  ]
}
```

Image URLs are not supported: an `http` or `https` URL returns `400` `validation_error`. The Responses API ignores image parts, so send images through Chat Completions.

### Uploaded files (`file_id`)

Upload the document or image with the [Files API](/endpoints/files-api/), wait
until `status` is `processed`, then pass its id on a `file` part:

```json
{
  "model": "subq-savant-1.4",
  "messages": [{
    "role": "user",
    "content": [
      { "type": "text", "text": "Summarize this report." },
      { "type": "file", "file_id": "file_abc123" }
    ]
  }]
}
```

An unknown id, or a file owned by another organization, returns `404`
`file_not_found`. A file that hasn't finished processing returns `409`
`file_not_ready`; retry once `status` is `processed`. See
[Sending files](/using-the-api/file-inputs/#uploaded-files) for SDK examples.

## Metadata

Attach up to 16 key-value string pairs to a request for your own tracking: run IDs, experiment names, customer tags. SubQ does not act on these values, and the model never sees them.

- Keys can be at most 64 characters; values at most 512 characters.
- Values must be strings. Numbers and booleans are coerced to strings; objects, arrays, and other non-string values are rejected with a `400` `validation_error`.
- Omit `metadata`, or pass `null` or `{}`, for no metadata — all three are treated the same.

```json
{
  "model": "subq-savant-1.4",
  "messages": [{ "role": "user", "content": "Summarize this release note." }],
  "metadata": { "run_id": "eval-2026-08-31-014", "experiment": "reasoning-ablation" }
}
```

A non-streaming response echoes `metadata` back verbatim:

```json
{
  "id": "chatcmpl-mhw3k9zq_4f7k2a",
  "metadata": { "run_id": "eval-2026-08-31-014", "experiment": "reasoning-ablation" }
}
```

Streaming chunks do not include `metadata`.

## Storage

By default SubQ stores each request and response under the [data-retention policy](/using-the-api/data-retention/). Set `store: false` to keep a single request, including any inline files, out of storage:

```json
{
  "model": "subq-savant-1.4",
  "messages": [{ "role": "user", "content": "Summarize this patient intake note." }],
  "store": false
}
```

Files you reference by `file_id` stay available. To control exactly when a
document is deleted, upload it with the [Files API](/endpoints/files-api/), pass
its `file_id`, and [delete the file](/endpoints/files-api/#delete-file) when
you're done.

## Request examples

Use cURL for direct HTTP calls, or use the official OpenAI SDK with SubQ's base URL.

```bash title="cURL"
curl --request POST \
  --url https://api.subq.ai/v1/chat/completions \
  --header "Authorization: Bearer $SUBQ_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '
{
  "model": "subq-savant-1.4",
  "messages": [
    {
      "role": "system",
      "content": "You are concise and practical."
    },
    {
      "role": "user",
      "content": "In three bullets, explain the difference between indemnification, limitation of liability, and insurance requirements in a software contract."
    }
  ],
  "max_tokens": 500
}
'
```

```ts title="TypeScript"
import OpenAI from "openai";

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

const completion = await client.chat.completions.create({
  model: "subq-savant-1.4",
  messages: [
    {
      role: "system",
      content: "You are concise and practical."
    },
    {
      role: "user",
      content: "In three bullets, explain the difference between indemnification, limitation of liability, and insurance requirements in a software contract."
    }
  ],
  max_tokens: 500
});

console.log(completion.choices[0]?.message?.content);
```

```py title="Python"
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["SUBQ_API_KEY"],
    base_url="https://api.subq.ai/v1",
)

completion = client.chat.completions.create(
    model="subq-savant-1.4",
    messages=[
        {
            "role": "system",
            "content": "You are concise and practical.",
        },
        {
            "role": "user",
            "content": "In three bullets, explain the difference between indemnification, limitation of liability, and insurance requirements in a software contract.",
        },
    ],
    max_tokens=500,
)

print(completion.choices[0].message.content)
```

## Response

A non-streaming request returns a JSON object with the OpenAI-compatible chat completion shape.

```json {10-14}
{
  "id": "chatcmpl-mhw3k9zq_4f7k2a",
  "object": "chat.completion",
  "created": 1784314379,
  "model": "subq-savant-1.4",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "*   **Indemnification** is a contractual obligation where one party agrees to compensate the other for losses, damages, or legal costs arising from third-party claims (such as intellectual property infringement or data breaches), effectively shifting the financial risk of those specific external liabilities to the responsible party.\n*   **Limitation of Liability** caps the maximum amount of damages one party can be forced to pay the other for breach of contract or negligence, often excluding consequential or indirect damages, thereby protecting both sides from catastrophic financial exposure beyond a predefined threshold (e.g., fees paid in the prior 12 months).\n*   **Insurance Requirements** mandate that one or both parties maintain specific types and minimum amounts of insurance coverage (such as general liability, professional liability, or cyber insurance) to ensure there are financial resources available to cover potential claims, serving as a verification of financial capacity rather than a direct transfer of risk between the contracting parties.",
        "reasoning": "The user wants three bullets, one per term, in a software-contract setting. Indemnification: who pays for third-party claims. Limitation of liability: a cap on damages between the parties. Insurance requirements: proof there is money behind the promises. Keep each bullet to one sentence and stay practical."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 110,
    "completion_tokens": 253,
    "total_tokens": 363,
    "prompt_tokens_details": { "cached_tokens": 0 },
    "completion_tokens_details": { "reasoning_tokens": 65 }
  }
}
```

### Response fields

| Field      | Type    | Description                                                                                                         |
| ---------- | ------- | ------------------------------------------------------------------------------------------------------------------- |
| `id`       | string  | Unique completion ID.                                                                                               |
| `object`   | string  | Object type. Non-streaming responses use `chat.completion`.                                                         |
| `created`  | integer | Unix timestamp, in seconds, for when the completion was created.                                                    |
| `model`    | string  | Model ID used for the completion.                                                                                   |
| `choices`  | array   | Generated choices: `n` of them (default `1`), each with its own `index`.                                            |
| `usage`    | object  | Token usage for the request.                                                                                        |
| `metadata` | object  | Echo of the request's `metadata`, or `{}` if none was sent. Omitted on streaming chunks. See [Metadata](#metadata). |

### Choice fields

| Field                | Type           | Description                                                                                                                                                               |
| -------------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `index`              | integer        | Choice index.                                                                                                                                                             |
| `message.role`       | string         | Role of the returned message, usually `assistant`.                                                                                                                        |
| `message.content`    | string or null | Generated text. `null` when the model returns tool calls, or when `max_tokens` was consumed before the answer began—see [Token limits](#token-limits).                    |
| `message.reasoning`  | string or null | The model's reasoning, separate from the answer. See [Reasoning output](#reasoning-output).                                                                               |
| `message.tool_calls` | array          | Present when the model requests function calls. See [Function calling](/using-the-api/function-calling/).                                                                 |
| `finish_reason`      | string         | Reason generation stopped. Common values include `stop`, `length` (hit `max_tokens` or the remaining window), and `tool_calls`. Handle unknown string values defensively. |

### Usage fields

| Field                                        | Type    | Description                                                                                  |
| -------------------------------------------- | ------- | -------------------------------------------------------------------------------------------- |
| `prompt_tokens`                              | integer | Tokens counted from the request messages. Billed at the input rate.                          |
| `prompt_tokens_details.cached_tokens`        | integer | How many of `prompt_tokens` were served from cache. Billed at the cached input rate.         |
| `completion_tokens`                          | integer | Tokens generated in the response, including any reasoning tokens. Billed at the output rate. |
| `completion_tokens_details.reasoning_tokens` | integer | How many of `completion_tokens` were reasoning.                                              |
| `total_tokens`                               | integer | Sum of prompt and completion tokens.                                                         |

See [Models](/using-the-api/models/#subq-savant-14) for the rates.

## Errors

Errors use the OpenAI-compatible error shape. `param` is present when the error traces to one request field.

```json
{
  "error": {
    "message": "logprobs is not supported for this model.",
    "type": "invalid_request_error",
    "code": "unsupported_parameter",
    "param": "logprobs"
  }
}
```

Use `code` for programmatic handling — `message` text may change.

| HTTP          | `code`                                                               | Meaning                                                                                                                                       |
| ------------- | -------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| 400           | `validation_error`                                                   | The body is malformed or a field has an invalid value.                                                                                        |
| 400           | `unsupported_value`                                                  | The request set `temperature` to a value other than `1`, or tried to turn reasoning off. See [Restricted parameters](#restricted-parameters). |
| 400           | `unsupported_parameter`                                              | The request set a parameter SubQ doesn't support. `param` names it. See [Restricted parameters](#restricted-parameters).                      |
| 400           | `context_length_exceeded`                                            | The messages plus `max_tokens` exceed the context window. Shorten the messages or lower `max_tokens`.                                         |
| 400, 413, 422 | `model_rejected_request`                                             | The model could not process the request. Check the field named in `param`.                                                                    |
| 401           | `invalid_api_key`                                                    | The API key is missing or invalid.                                                                                                            |
| 402           | `insufficient_credits`                                               | The organization is out of credits.                                                                                                           |
| 403           | `model_not_allowed`                                                  | The model is not enabled for your organization. See [SubQ Savant](/using-the-api/models/#subq-savant-14).                                     |
| 429           | `rate_limit_exceeded`                                                | Your organization hit a rate limit. Retry with backoff.                                                                                       |
| 429           | `model_rejected_request`                                             | The model is receiving too many requests. Retry shortly.                                                                                      |
| 502           | `model_backend_unavailable`, `model_backend_error`, `upstream_error` | The model is temporarily unavailable. Retry with backoff.                                                                                     |
| 503           | `authorization_failed`                                               | Key lookup temporarily unavailable. Retry.                                                                                                    |
| 504           | `model_backend_timeout`                                              | The model did not respond in time. Retry with backoff.                                                                                        |
| 529           | `model_overloaded`                                                   | The service is temporarily overloaded. Retry with backoff.                                                                                    |

A streaming request that fails after the first chunk closes the connection without an error event. Treat a stream that ends before `data: [DONE]` as failed.
