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

# Groq

> Trace Groq SDK calls and use Groq models in Braintrust

[Groq](https://groq.com) provides fast inference for open models including Llama, Mixtral, and Gemma. Trace your Groq calls in Braintrust, run experiments against Groq models, and use them from the playground.

**TypeScript**

## Tracing

To trace Groq with Braintrust's TypeScript SDK, use auto-instrumentation, manual instrumentation, or the Braintrust gateway. Auto-instrumentation is the recommended path for most users.

> [tab] Auto-instrumentation
>
> Auto-instrumentation patches the `groq-sdk` client at runtime when you run your app with Braintrust's import hook, so you don't modify your application code.
>
> ### Setup
>
> Install the Braintrust and Groq SDKs, then set your API keys. Requires `groq-sdk` v1.0.0 or later.
>
> ```bash pnpm theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
> pnpm add braintrust groq-sdk
> ```
>
> ```bash npm theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
> npm install braintrust groq-sdk
> ```
>
> ```bash title=".env" theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
> GROQ_API_KEY=<your-groq-api-key>
> BRAINTRUST_API_KEY=<your-braintrust-api-key>
>
> # For organizations on the EU data plane, use https://api-eu.braintrust.dev
> # For self-hosted deployments, use your data plane URL
> # BRAINTRUST_API_URL=<your-braintrust-api-url-here>
> ```
>
> ### Trace your application
>
> Initialize Braintrust and call Groq normally, then run your app with the import hook to patch the client at runtime.
>
> **1. Initialize Braintrust and call Groq**
>
> ```javascript title="trace-groq-auto.js" theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
> import { initLogger } from "braintrust";
> import Groq from "groq-sdk";
>
> initLogger({
>   projectName: "My Project",
>   apiKey: process.env.BRAINTRUST_API_KEY,
> });
>
> const client = new Groq({ apiKey: process.env.GROQ_API_KEY });
>
> const response = await client.chat.completions.create({
>   model: "openai/gpt-oss-120b",
>   messages: [{ role: "user", content: "What is machine learning?" }],
> });
>
> console.log(response.choices[0].message.content);
> ```
>
> **2. Run with the import hook**
>
> ```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
> node --import braintrust/hook.mjs trace-groq-auto.js
> ```
>
> The auto-instrumentation example uses plain JavaScript so `node --import` can run the file directly. The Braintrust APIs work the same in TypeScript projects. Compile your TypeScript to JavaScript and run the compiled file with the import hook, or [run TypeScript directly](https://docs.braintrust.dev/instrument/trace-llm-calls.md#auto-instrumentation) with a TypeScript loader.
>
> > [!NOTE]
> >
> > If you're using a bundler, see [Trace LLM calls](https://docs.braintrust.dev/instrument/trace-llm-calls.md#auto-instrumentation) for plugin and loader setup.
>
> ### What Braintrust traces
>
> Braintrust patches the `groq-sdk` client and captures:
>
> * Chat completion spans (`groq.chat.completions.create`), with messages and request parameters as input, and response choices and token usage as output.
> * Reasoning content for Groq reasoning models, aggregated from streaming responses.
> * Embedding spans (`groq.embeddings.create`), with input and request parameters as input, and the first embedding's vector length as output.
> * Audio speech spans (`groq.audio.speech.create`), with the prompt and voice parameters as input. Generated audio is captured as an attachment.
> * Audio transcription spans (`groq.audio.transcriptions.create`), with the audio file as an attachment and transcription parameters as input, and the transcript text as output.
> * Audio translation spans (`groq.audio.translations.create`), with the audio file as an attachment and translation parameters as input, and the translated text as output.
> * Token usage metrics (prompt, completion, total), including Groq cache metrics (`dram_cached_tokens` and `sram_cached_tokens`) when reported.
> * `time_to_first_token` for chat completions.
> * Errors captured on every call.
>
> ### Tracing resources
>
> * [`groq-sdk` on npm](https://www.npmjs.com/package/groq-sdk)
> * [Groq documentation](https://console.groq.com/docs/overview)

> [tab] Manual instrumentation
>
> To trace Groq manually, wrap the `groq-sdk` client yourself with `wrapGroq()`.
>
> ### Setup
>
> Install the Braintrust and Groq SDKs, then set your API keys. Requires `groq-sdk` v1.0.0 or later.
>
> ```bash pnpm theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
> pnpm add braintrust groq-sdk
> ```
>
> ```bash npm theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
> npm install braintrust groq-sdk
> ```
>
> ```bash title=".env" theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
> GROQ_API_KEY=<your-groq-api-key>
> BRAINTRUST_API_KEY=<your-braintrust-api-key>
>
> # For organizations on the EU data plane, use https://api-eu.braintrust.dev
> # For self-hosted deployments, use your data plane URL
> # BRAINTRUST_API_URL=<your-braintrust-api-url-here>
> ```
>
> ### Trace your application
>
> Wrap the Groq client with `wrapGroq()` so every call is traced.
>
> ```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
> import { initLogger, wrapGroq } from "braintrust";
> import Groq from "groq-sdk";
>
> initLogger({
>   projectName: "My Project",
>   apiKey: process.env.BRAINTRUST_API_KEY,
> });
>
> const client = wrapGroq(new Groq({ apiKey: process.env.GROQ_API_KEY }));
>
> const response = await client.chat.completions.create({
>   model: "openai/gpt-oss-120b",
>   messages: [{ role: "user", content: "What is machine learning?" }],
> });
>
> console.log(response.choices[0].message.content);
> ```
>
> ### What Braintrust traces
>
> Braintrust patches the `groq-sdk` client and captures:
>
> * Chat completion spans (`groq.chat.completions.create`), with messages and request parameters as input, and response choices and token usage as output.
> * Reasoning content for Groq reasoning models, aggregated from streaming responses.
> * Embedding spans (`groq.embeddings.create`), with input and request parameters as input, and the first embedding's vector length as output.
> * Token usage metrics (prompt, completion, total), including Groq cache metrics (`dram_cached_tokens` and `sram_cached_tokens`) when reported.
> * `time_to_first_token` for chat completions.
> * Errors captured on every call.
>
> ### Tracing resources
>
> * [`groq-sdk` on npm](https://www.npmjs.com/package/groq-sdk)
> * [Groq documentation](https://console.groq.com/docs/overview)

> [tab] Gateway
>
> The [Braintrust gateway](https://docs.braintrust.dev/deploy/gateway.md) routes your Groq requests server-side. Point an OpenAI-compatible client at the gateway base URL, then set the `x-bt-parent` header to log each request to your project.
>
> ### Setup
>
> Install the Braintrust and OpenAI SDKs, then set your Braintrust API key. The gateway reads your Groq key from the provider you configure in [Add Groq as an AI provider](#add-groq-as-an-ai-provider).
>
> ```bash pnpm theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
> pnpm add braintrust openai
> ```
>
> ```bash npm theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
> npm install braintrust openai
> ```
>
> ```bash title=".env" theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
> BRAINTRUST_API_KEY=<your-braintrust-api-key>
>
> # For organizations on the EU data plane, use https://api-eu.braintrust.dev
> # For self-hosted deployments, use your data plane URL
> # BRAINTRUST_API_URL=<your-braintrust-api-url-here>
> ```
>
> ### Trace your application
>
> Point an OpenAI client at the gateway, then set the `x-bt-parent` header on the request so the gateway logs it to your project. Use a `project_name:` prefix to target a project directly, or pass `span.export()` to nest the call in a [distributed trace](https://docs.braintrust.dev/deploy/gateway.md#enable-logging).
>
> ```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
> import { OpenAI } from "openai";
> import { initLogger } from "braintrust";
>
> initLogger({
>   projectName: "My Project",
>   apiKey: process.env.BRAINTRUST_API_KEY,
> });
>
> const client = new OpenAI({
>   baseURL: "https://gateway.braintrust.dev/v1",
>   apiKey: process.env.BRAINTRUST_API_KEY,
> });
>
> // Gateway logging is opt-in: set x-bt-parent so the gateway logs to the project.
> const result = await client.chat.completions.create(
>   {
>     model: "openai/gpt-oss-120b",
>     messages: [{ role: "user", content: "What is machine learning?" }],
>   },
>   {
>     headers: { "x-bt-parent": "project_name:My Project" },
>   },
> );
> ```
>
> ### Tracing resources
>
> * [Braintrust gateway](https://docs.braintrust.dev/deploy/gateway.md)
> * [Supported AI providers](https://docs.braintrust.dev/integrations/ai-providers.md)

## Evals

Run experiments against Groq models to measure quality and catch regressions. An `Eval` is composed of a dataset of inputs, a task, and a set of scorers. To learn more, see the [Experiments](https://docs.braintrust.dev/evaluate/run-evaluations.md) guide.

```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
import { Eval } from "braintrust";
import { OpenAI } from "openai";

const client = new OpenAI({
  baseURL: "https://gateway.braintrust.dev/v1",
  apiKey: process.env.BRAINTRUST_API_KEY,
});

Eval("Groq Evaluation", {
  data: () => [
    { input: "What is 2+2?", expected: "4" },
    { input: "What is the capital of France?", expected: "Paris" },
  ],
  task: async (input) => {
    const response = await client.chat.completions.create({
      model: "openai/gpt-oss-120b",
      messages: [{ role: "user", content: input }],
    });
    return response.choices[0].message.content;
  },
  scores: [
    {
      name: "accuracy",
      scorer: (args) => (args.output === args.expected ? 1 : 0),
    },
  ],
});
```

**Python**

## Tracing

To trace Groq with Braintrust's Python SDK, use the Braintrust gateway.

> [tab] Gateway
>
> The [Braintrust gateway](https://docs.braintrust.dev/deploy/gateway.md) routes your Groq requests server-side. Point an OpenAI-compatible client at the gateway base URL, then set the `x-bt-parent` header to log each request to your project.
>
> ### Setup
>
> Install the Braintrust and OpenAI SDKs, then set your Braintrust API key. The gateway reads your Groq key from the provider you configure in [Add Groq as an AI provider](#add-groq-as-an-ai-provider).
>
> ```bash uv theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
> uv add braintrust openai
> ```
>
> ```bash pip theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
> pip install braintrust openai
> ```
>
> ```bash title=".env" theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
> BRAINTRUST_API_KEY=<your-braintrust-api-key>
>
> # For organizations on the EU data plane, use https://api-eu.braintrust.dev
> # For self-hosted deployments, use your data plane URL
> # BRAINTRUST_API_URL=<your-braintrust-api-url-here>
> ```
>
> ### Trace your application
>
> Point an OpenAI client at the gateway, then set the `x-bt-parent` header on the request so the gateway logs it to your project. Use a `project_name:` prefix to target a project directly, or pass `span.export()` to nest the call in a [distributed trace](https://docs.braintrust.dev/deploy/gateway.md#enable-logging).
>
> ```python Python theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
> import os
>
> from braintrust import init_logger
> from openai import OpenAI
>
> init_logger(project="My Project")
>
> client = OpenAI(
>     base_url="https://gateway.braintrust.dev/v1",
>     api_key=os.environ["BRAINTRUST_API_KEY"],
> )
>
> # Gateway logging is opt-in: set x-bt-parent so the gateway logs to the project.
> result = client.chat.completions.create(
>     model="openai/gpt-oss-120b",
>     messages=[{"role": "user", "content": "What is machine learning?"}],
>     extra_headers={"x-bt-parent": "project_name:My Project"},
> )
> ```
>
> ### Tracing resources
>
> * [Braintrust gateway](https://docs.braintrust.dev/deploy/gateway.md)
> * [Supported AI providers](https://docs.braintrust.dev/integrations/ai-providers.md)

## Evals

Run experiments against Groq models to measure quality and catch regressions. An `Eval` is composed of a dataset of inputs, a task, and a set of scorers. To learn more, see the [Experiments](https://docs.braintrust.dev/evaluate/run-evaluations.md) guide.

```python Python theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
import os

from braintrust import Eval
from openai import OpenAI

client = OpenAI(
    base_url="https://gateway.braintrust.dev/v1",
    api_key=os.environ["BRAINTRUST_API_KEY"],
)

def task(input):
    response = client.chat.completions.create(
        model="openai/gpt-oss-120b",
        messages=[{"role": "user", "content": input}],
    )
    return response.choices[0].message.content

def accuracy_scorer(output, expected, **kwargs):
    return 1 if output == expected else 0

Eval(
    "Groq Evaluation",
    data=[
        {"input": "What is 2+2?", "expected": "4"},
        {"input": "What is the capital of France?", "expected": "Paris"},
    ],
    task=task,
    scores=[accuracy_scorer],
)
```

## Add Groq as an AI provider

Configure your Groq API key in Braintrust to route requests through the gateway and use Groq models from the playground.

**1. Get a Groq API key**

Get a Groq API key from [Groq Console](https://console.groq.com/keys).

**2. Add Groq as an AI provider**

Add the Groq API key as an [organization or project AI provider](https://docs.braintrust.dev/admin/ai-providers.md).

> [!NOTE]
>
> API keys are stored as one-way cryptographic hashes, never in plaintext.

### Groq provider resources

* [Groq models](https://console.groq.com/docs/models)
* [AI providers](https://docs.braintrust.dev/admin/ai-providers.md)


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