> ## 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](/docs/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, and for capabilities the CLI doesn't cover, such as monitor views, alerts, and authoring evaluators, preprocessors, and facets.

[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](/docs/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](/docs/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](/docs/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](/docs/deploy/gateway)
      * [Supported AI providers](/docs/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](/docs/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](/docs/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](/docs/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](/docs/deploy/gateway)
      * [Supported AI providers](/docs/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](/docs/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](/docs/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](/docs/admin/ai-providers)