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

# Databricks

> Wrap a client for Databricks model serving to meter and gate calls, and see which model actually answered each one.

Databricks model serving puts models behind serving endpoints in your workspace: Databricks-hosted foundation models, such as Claude or Llama, and external models that use your own OpenAI or Anthropic key.

## Set up

The SDK recognizes both ways of calling Databricks model serving and selects the Databricks recipe automatically:

* **OpenAI's `openai` client** with its `baseURL` pointing at your workspace's `/serving-endpoints`, since the serving API follows OpenAI's format. This is the route Databricks' own docs show, and the one that supports streaming and tools.
* **Databricks' own client**, from `@databricks/sdk-modelservingquery`, whose one method is `query()`.

```typescript OpenAI client theme={null}
import OpenAI from 'openai';

const databricks = stigg.wrap(
  new OpenAI({
    baseURL: 'https://my-workspace.cloud.databricks.com/serving-endpoints',
    apiKey: process.env.DATABRICKS_TOKEN,
  }),
);

await databricks.chat.completions.create({
  model: 'databricks-claude-sonnet-4-6', // a serving endpoint name
  messages,
  stiggContext: { customerId: 'customer-acme', entitlement: { currencyId: 'credits' } },
});
```

```typescript Databricks client theme={null}
import { ModelServingQueryClient } from '@databricks/sdk-modelservingquery/v1';
import { newPatCredentials } from '@databricks/sdk-auth/credentials';

const client = new ModelServingQueryClient({
  host: 'https://my-workspace.cloud.databricks.com',
  credentials: newPatCredentials(process.env.DATABRICKS_TOKEN),
});

const databricks = stigg.wrap(client, {
  stiggContext: { customerId: 'customer-acme', entitlement: { currencyId: 'credits' } },
});

await databricks.query({
  name: 'databricks-claude-sonnet-4-6', // a serving endpoint name
  messages,
});
```

* **A workspace on a private address**, such as PrivateLink or custom DNS, is not recognized automatically. Pass the recipe with the same base URL as the client: `stigg.wrap(client, { recipe: databricksRecipe({ baseUrl }) })`. Public workspaces on `cloud.databricks.com`, `azuredatabricks.net` and `gcp.databricks.com` are recognized, on both the `/serving-endpoints` and `/ai-gateway/mlflow/v1` paths.
* **Ask for usage on streamed calls.** Databricks includes usage in a stream only when the request sets `stream_options: { include_usage: true }`.
* **Databricks' own client cannot stream**, and reports fewer metrics (see below). Use the `OpenAI` client when you need either.

### External models

An endpoint configured as an **external model** calls OpenAI, Anthropic or another provider with your own key, so that provider charges you, not Databricks. Nothing in the request or response shows which kind of endpoint answered, so tell the SDK by wrapping the client with the external recipe:

```typescript theme={null}
import { databricksExternalRecipe } from '@stigg/agent-sdk-js';

const external = stigg.wrap(client, { recipe: databricksExternalRecipe() });
```

Its calls are reported under `databricks-external.*` event names instead of `databricks.*`, so you can meter the two kinds of spend separately. If one workspace serves both kinds of endpoint, wrap one client for each.

## What is reported

Every response includes a `usage` object in OpenAI's format with the number of tokens the call consumed, and the `model` that answered. The wrapper reads these and reports them to Stigg as the metrics below. For details, see Databricks' [Foundation Model APIs](https://docs.databricks.com/aws/en/machine-learning/foundation-model-apis/) docs.

| Client | Method | Event name |
| - | - | - |
| `OpenAI` | `chat.completions.create` | `databricks.chat.completions.create` |
| `OpenAI` | `responses.create` | `databricks.responses.create` |
| Databricks | `query` | `databricks.query` |

With `databricksExternalRecipe()`, the event names start with `databricks-external.` instead.

| Route | Metrics |
| - | - |
| Chat Completions and `query` | `prompt_tokens`, `completion_tokens`, `total_tokens`, `reasoning_tokens`, `cache_read_input_tokens`, `cache_creation_input_tokens` |
| Responses | `input_tokens`, `output_tokens`, `total_tokens`, `reasoning_tokens`, `cache_read_input_tokens`, `cache_creation_input_tokens` |

Databricks' own client reports only `prompt_tokens`, `completion_tokens` and `total_tokens`. It returns usage in camelCase, such as `promptTokens`, and the SDK reports it under the API's field names, so both clients report the same metrics for the same workspace.

Databricks does not document whether cache reads are counted inside `prompt_tokens`, so the SDK reports both as the API returns them. Price `total_tokens`, which Databricks reports itself, or check against your own endpoint before pricing the parts.

Each event also carries:

| Reported | What it is |
| - | - |
| `model` dimension | The model that actually answered. A call names a serving endpoint, which can have any name and front any model, so this is often the only record of which model ran. |
| `served_model_name` dimension | The served entity behind an endpoint that splits traffic across several, when the response names one. |
| `response_object` dimension | For `query` only: what kind of response it was, since one method serves chat, completions and embeddings. |

* **No `cost`.** Databricks does not return a price on any response, so you can meter tokens but not what the call cost. Databricks reports spend in its own system tables.
* **No endpoint name.** The SDK records the model that answered, not the endpoint you called. To meter by endpoint, add it yourself, for example `stiggContext: { dimensions: { endpoint: 'prod-chat' } }`.

Every usage field the vendor returns is also included, with a `raw.` prefix. See [How usage is reported](/documentation/ai-agents/usage-metering#how-usage-is-reported).


## Related topics

- [Databricks](/documentation/importing-and-exporting-data/export/databricks.md)
- [JavaScript](/api-and-sdks/changelog/agent-sdk/javascript.md)
- [Agent SDK](/api-and-sdks/references/sdk/backend/graphql/agent-sdk.md)
- [Usage metering](/documentation/ai-agents/usage-metering.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.