Skip to main content
Parameters let you create reusable configuration for your evaluations. Define parameters once in Braintrust, then load them across multiple evaluations. This approach enables:
  • Reusability: Share configurations across multiple evaluations
  • Centralized management: Update parameters in one place for all evaluations
  • Version control: Track parameter changes independently of evaluation code
  • Environment management: Use different parameter values across dev, staging, and production
Saved parameters can be created and loaded from both the TypeScript and Python SDKs. The examples below use TypeScript SDK v2.2.1+ and Python SDK v0.10.0+.

​
Create parameters

Define parameters in code and push to Braintrust:
eval-config.ts
import * as braintrust from "braintrust";
import { z } from "zod";

const project = braintrust.projects.create({
  name: "My Project",
});

export const evalConfig = project.parameters.create({
  name: "Evaluation config",
  slug: "eval-config",
  description: "Configuration for model evaluation",
  schema: {
    model: {
      type: "model",
      default: "gpt-5-mini",
      description: "Model to evaluate",
    },
    temperature: z.number().min(0).max(1).default(0.2).describe("Sampling temperature"),
    system_prompt: z.string().default("You are a helpful assistant.").describe("System prompt to use"),
    eval_prompt: {
      type: "prompt",
      description: "Prompt to use for the evaluation task",
      default: {
        messages: [
          {
            role: "user",
            content: "{{input}}",
          },
        ],
        model: "gpt-5-mini",
      },
    },
  },
  metadata: { version: "1.0" },
});
Push to Braintrust: 
npx braintrust push eval-config.ts
When you create parameters with default values, Braintrust automatically initializes them with those defaults. This means the first version of your parameter will already have the default values set, ready to use in evaluations or modify in the UI.

​
Specify parameter types

Define the structure and types of your parameters using Zod (TypeScript) or Pydantic plus Braintrust parameter descriptors (Python). You can combine these building blocks to create any structure your evaluation needs, whether simple flat configurations or complex nested objects. Use Zod or Pydantic models for regular data parameters such as strings, numbers, booleans, arrays, and objects. Use Braintrust’s built-in descriptors for special parameter types such as model and prompt, which power model pickers and prompt editors in the UI. 
import { z } from "zod";

const schema = {
  model: {
    type: "model",
    default: "gpt-5-mini",
    description: "Model name",
  },
  system_prompt: z.string().default("You are a helpful assistant.").describe("System instructions"),
  temperature: z.number().min(0).max(1).default(0.2).describe("Sampling temperature"),
  enable_streaming: z.boolean().default(false).describe("Enable streaming"),
  eval_mode: z.enum(["baseline", "strict"]).default("baseline").describe("Evaluation mode"),
  tags: z.array(z.string()).default(["baseline"]).describe("Tags to attach to each run"),
  generation_config: z.object({
    max_tokens: z.number(),
    top_p: z.number(),
  }).default({
    max_tokens: 500,
    top_p: 1.0,
  }).describe("Additional generation settings"),
  eval_prompt: {
    type: "prompt",
    description: "Prompt to use",
    default: {
      messages: [
        {
          role: "user",
          content: "{{input}}",
        },
      ],
      model: "gpt-5-mini",
    },
  },
};

​
Edit parameters

Update parameter values or schemas in the UI or in code. Every edit creates a new version automatically, preserving the history of changes.
  1. Go to Parameters.
  2. Select the parameters to edit.
  3. Modify values in the editor.
  4. Click Save version.
Every edit creates a new version automatically, preserving the history of changes.

​
Use in evaluations

Load parameters in your Eval() function using loadParameters() in TypeScript or load_parameters() in Python. Parameters are accessed in your task function via the parameters argument.
For remote evals, parameters automatically become editable controls in the playground UI, letting you modify values without changing code.
import { Eval, loadParameters } from "braintrust";
import { evalConfig } from "./eval-config";

Eval("My Project", {
  experimentName: "Parameter test",
  data: async () => [
    { input: "What is 2+2?", expected: "4" },
  ],
  task: async (input, { parameters }) => {
    return await callModel(input, {
      model: parameters.model,
      temperature: parameters.temperature,
    });
  },
  parameters: loadParameters<typeof evalConfig>({
    projectName: "My Project",
    slug: "eval-config",
  }),
});
When using loadParameters() or load_parameters() in remote evals, the playground displays a version selector, letting you experiment with different parameter versions without editing code.
When you pass a loaded parameter set into Eval(...), Braintrust links the experiment to that saved parameter version so the experiment metadata includes the corresponding parameters_id and parameters_version.

​
Pin to a version

Load a specific parameter version by ID: 
parameters: loadParameters({
  projectName: "My Project",
  slug: "eval-config",
  version: "5878bd218351fb8e",
})

​
Assign to an environment

To assign a specific parameter version to an environment:
  1. Go to Parameters.
  2. Open the parameter.
  3. Click the icon.
  4. Select an environment.
Once assigned, load parameters for that environment in your code: 
import { loadParameters } from "braintrust";

const params = await loadParameters({
  projectName: "My Project",
  slug: "eval-config",
  environment: "production",
});

​
Create custom table views

The Parameters page supports custom table views to save your preferred filters, column order, and display settings. To create or update a custom table view:
  1. Apply the filters and display settings you want.
  2. Open the menu and select Save view… or Save view as….
Custom table views are visible to all project members. Creating or editing a table view requires the Update project permission.

​
Set default table views

You can set default views at two levels:
  • Organization default: Visible to all members when they open the page. This applies per page — for example, you can set separate organization defaults for Logs, Experiments, and Review. To set an organization default, you need the Manage settings organization permission (included by default in the Owner role). See Access control for details.
  • Personal default: Overrides the organization default for you only. Personal defaults are stored in your browser, so they do not carry over across devices or browsers.
To set a default view:
  1. Switch to the view you want by selecting it from the menu.
  2. Open the menu again and hover over the currently selected view to reveal its submenu.
  3. Choose Set as personal default view or Set as organization default view.
To clear a default view:
  1. Open the menu and hover over the currently selected view to reveal its submenu.
  2. Choose Clear personal default view or Clear organization default view.
When a user opens a page, Braintrust loads the first match in this order: personal default, organization default, then the standard “All …” view (e.g., “All logs view”).

​
Next steps