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

# Groq

> Trace Groq SDK calls and use Groq models in Braintrust

If you are a coding agent, prefer the Braintrust [`bt` CLI](/reference/cli/quickstart) for repeatable, scriptable work: running evals, instrumenting code, querying logs, syncing data, managing functions, and configuring coding agents. Use the MCP server for reasoning over Braintrust data in conversation, such as ad-hoc lookups and exploration from your IDE.

[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.

<View title="TypeScript" icon="https://img.logo.dev/typescriptlang.org?token=pk_BdcHD9e5SCW3j1rnJkNyMQ">
  <h2 id="tracing-typescript">
    Tracing
  </h2>

  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.

  <Tabs>
    <Tab title="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.

      <h3 id="setup-typescript-auto">
        Setup
      </h3>

      Install the Braintrust and Groq SDKs, then set your API keys. Requires `groq-sdk` v1.0.0 or later.

      <CodeGroup>
        ```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
        ```
      </CodeGroup>

      ```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>
      ```

      <h3 id="trace-typescript-auto">
        Trace your application
      </h3>

      Initialize Braintrust and call Groq normally, then run your app with the import hook to patch the client at runtime.

      <Steps>
        <Step title="Initialize Braintrust and call Groq">
          <CodeGroup>
            ```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);
            ```
          </CodeGroup>
        </Step>

        <Step title="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, then run the compiled file with the import hook.

          <Note>
            If you're using a bundler, see [Trace LLM calls](/instrument/trace-llm-calls#auto-instrumentation) for plugin and loader setup.
          </Note>
        </Step>
      </Steps>

      <h3 id="what-traced-typescript-auto">
        What Braintrust traces
      </h3>

      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.

      <h3 id="tracing-resources-typescript-auto">
        Tracing resources
      </h3>

      * [`groq-sdk` on npm](https://www.npmjs.com/package/groq-sdk)
      * [Groq documentation](https://console.groq.com/docs/overview)
    </Tab>

    <Tab title="Manual instrumentation">
      To trace Groq manually, wrap the `groq-sdk` client yourself with `wrapGroq()`.

      <h3 id="setup-typescript-manual">
        Setup
      </h3>

      Install the Braintrust and Groq SDKs, then set your API keys. Requires `groq-sdk` v1.0.0 or later.

      <CodeGroup>
        ```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
        ```
      </CodeGroup>

      ```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>
      ```

      <h3 id="trace-typescript-manual">
        Trace your application
      </h3>

      Wrap the Groq client with `wrapGroq()` so every call is traced.

      <CodeGroup>
        ```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);
        ```
      </CodeGroup>

      <h3 id="what-traced-typescript-manual">
        What Braintrust traces
      </h3>

      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.

      <h3 id="tracing-resources-typescript-manual">
        Tracing resources
      </h3>

      * [`groq-sdk` on npm](https://www.npmjs.com/package/groq-sdk)
      * [Groq documentation](https://console.groq.com/docs/overview)
    </Tab>

    <Tab title="Gateway">
      The [Braintrust gateway](/deploy/gateway) 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.

      <h3 id="setup-typescript-gateway">
        Setup
      </h3>

      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).

      <CodeGroup>
        ```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
        ```
      </CodeGroup>

      ```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>
      ```

      <h3 id="trace-typescript-gateway">
        Trace your application
      </h3>

      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](/deploy/gateway#enable-logging).

      <CodeGroup>
        ```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" },
          },
        );
        ```
      </CodeGroup>

      <h3 id="tracing-resources-typescript-gateway">
        Tracing resources
      </h3>

      * [Braintrust gateway](/deploy/gateway)
      * [Supported AI providers](/integrations/ai-providers)
    </Tab>
  </Tabs>

  <h2 id="evals-typescript">
    Evals
  </h2>

  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](/evaluate/run-evaluations) guide.

  <CodeGroup>
    ```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),
        },
      ],
    });
    ```
  </CodeGroup>
</View>

<View title="Python" icon="https://img.logo.dev/python.org?token=pk_BdcHD9e5SCW3j1rnJkNyMQ">
  <h2 id="tracing-python">
    Tracing
  </h2>

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

  <Tabs>
    <Tab title="Gateway">
      The [Braintrust gateway](/deploy/gateway) 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.

      <h3 id="setup-python-gateway">
        Setup
      </h3>

      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).

      <CodeGroup>
        ```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
        ```
      </CodeGroup>

      ```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>
      ```

      <h3 id="trace-python-gateway">
        Trace your application
      </h3>

      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](/deploy/gateway#enable-logging).

      <CodeGroup>
        ```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"},
        )
        ```
      </CodeGroup>

      <h3 id="tracing-resources-python-gateway">
        Tracing resources
      </h3>

      * [Braintrust gateway](/deploy/gateway)
      * [Supported AI providers](/integrations/ai-providers)
    </Tab>
  </Tabs>

  <h2 id="evals-python">
    Evals
  </h2>

  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](/evaluate/run-evaluations) guide.

  <CodeGroup>
    ```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],
    )
    ```
  </CodeGroup>
</View>

## 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.

<Steps>
  <Step title="Get a Groq API key">
    Get a Groq API key from [Groq Console](https://console.groq.com/keys).
  </Step>

  <Step title="Add Groq as an AI provider">
    Add the Groq API key as an [organization or project AI provider](/admin/ai-providers).

    <Note>
      API keys are stored as one-way cryptographic hashes, never in plaintext.
    </Note>
  </Step>
</Steps>

### Groq provider resources

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