> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gatelit.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Chat

> Non-streaming chat requests with usage tracking, abort support, and error handling.

`chat()` sends a request and waits for the full response. Use it when you need the complete output before continuing — data extraction, classification, or when streaming isn't practical.

## Basic usage

```ts theme={null}
import { GatelitClient } from "@gatelit/sdk"

const client = new GatelitClient({
  gatewayUrl: "https://gateway.yourapp.com",
  getToken: async () => ({ token: "sk_live_...", scheme: "GatelitKey" }),
})

const response = await client.chat({
  model: "openai/gpt-4o",
  messages: [
    { role: "system", content: "You are a helpful assistant." },
    { role: "user", content: "What is the capital of Bhutan?" },
  ],
})

console.log(response.content)
// → "The capital of Bhutan is Thimphu."

console.log(response.usage)
// → { inputTokens: 28, outputTokens: 9, totalTokens: 37 }
```

## The response

`chat()` returns a `ChatResponse` with everything you need:

| Field          | Type             | Description                                                                         |
| -------------- | ---------------- | ----------------------------------------------------------------------------------- |
| `content`      | `string`         | The assistant's response text                                                       |
| `model`        | `string`         | Resolved model in `provider/model` format (the model that actually responded)       |
| `usage`        | `Usage \| null`  | Token counts (`inputTokens`, `outputTokens`, `totalTokens`)                         |
| `finishReason` | `string \| null` | Why the model stopped — `"stop"`, `"length"`, `"tool_calls"`, or `"content_filter"` |
| `meta`         | `GatelitMeta`    | Request ID (`requestId`) and model — use for log lookup in the dashboard            |

## Controlling generation

```ts theme={null}
const response = await client.chat({
  model: "anthropic/claude-3-5-sonnet-20241022",
  messages: [{ role: "user", content: "Write a short story about a robot." }],
  maxTokens: 500,       // Cap response length
  temperature: 0.7,     // Control creativity (0 = deterministic, 2 = wild)
})
```

Parameters you don't pass stay at provider defaults. The gateway handles provider-specific quirks automatically — `temperature` is stripped for reasoning models (o3, o3-mini, o4-mini), `max_tokens` is renamed to `max_completion_tokens` where needed.

## Aborting a request

Pass an `AbortSignal` to cancel an in-flight request:

```ts theme={null}
const controller = new AbortController()

setTimeout(() => controller.abort(), 5000) // Cancel after 5 seconds

try {
  const response = await client.chat({
    model: "openai/gpt-4o",
    messages: [{ role: "user", content: "Write a very long essay..." }],
    signal: controller.signal,
  })
} catch (err) {
  if (err.name === "AbortError") {
    console.log("Request was cancelled")
  }
}
```

## Linking requests to the dashboard

Pass `promptId` to associate the request with a saved prompt for log correlation:

```ts theme={null}
const response = await client.chat({
  model: "openai/gpt-4o",
  messages: [{ role: "user", content: "Hi" }],
  promptId: "my-translator",
})
```

The prompt's content is **not** used — this just tags the log entry. Run a saved prompt's actual template through `/v1/prompts/:slug/run` instead.

## Tracking end users

Pass `endUserId` to tag requests with a user identifier. This shows up in the logs so you can filter by user:

```ts theme={null}
const response = await client.chat({
  model: "openai/gpt-4o",
  messages: [{ role: "user", content: "Summarize this ticket" }],
  endUserId: "customer_42",
})
```

## Error handling

The SDK throws a `GatelitError` with three fields:

```ts theme={null}
import { GatelitError } from "@gatelit/sdk"

try {
  await client.chat({ model: "openai/gpt-4o", messages: [...] })
} catch (err) {
  if (err instanceof GatelitError) {
    console.log(err.code)    // "unauthorized" | "gateway_error" | "provider_error"
    console.log(err.message) // Human-readable description
    console.log(err.status)  // HTTP status code
  }
}
```