---
title: "Create or replace custom column"
method: PUT
path: "/v1/column"
tags: ["CustomColumns"]
---

# Create or replace custom column

`PUT /v1/column`

## Request

- Base URL: `https://api.braintrust.dev`
- URL: `https://api.braintrust.dev/v1/column`
- Auth: one of:
  - HTTP bearer
  - none

Create or replace a custom column. If there is an existing custom column with the same name in the same scope, will replace its expression. Requires update permission on the scoping object.

Custom columns are scoped to a specific table by the combination of `object_type`, `object_id`, `subtype`, and `variant`. Use the same scope when creating and listing columns. Use these combinations to display columns in the corresponding UI table:

| Page | `object_type` | `object_id` | `subtype` | `variant` |
| --- | --- | --- | --- | --- |
| Dataset | `dataset` | Dataset ID | `""` | `dataset` |
| Project logs | `project` | Project ID | `project_log` | `project_log` |
| Experiment details | `project` | Project ID | `experiment` | `experiment` |
| Experiments list | `project` | Project ID | `experiment` | `experiment_list` |

Experiment span columns apply across experiments in the project.

## Request body

- CreateCustomColumn
  - `object_type` 'organization' | 'project' | 'experiment' | 'dataset' | 'prompt' | 'prompt_session' | 'group' | 'role' | 'org_member' | 'project_log' | 'org_project' | 'org_audit_logs' | 'project_group' | 'project_group_projects' | 'ai_secret' | 'org_ai_secret' | 'org_account', required: The type of the object the custom column is scoped to, usually `project`
  - `object_id` string, uuid, required: The ID of the scoping object. Use the project ID for project logs, experiment spans, and the experiments list. Use the dataset ID for dataset rows
  - `subtype` union, required: The child object type the custom column applies to, such as `experiment` or `project_log`. Use an empty string when the column applies directly to the scoping object, such as a dataset
    - 'organization' | 'project' | 'experiment' | 'dataset' | 'prompt' | 'prompt_session' | 'group' | 'role' | 'org_member' | 'project_log' | 'org_project' | 'org_audit_logs' | 'project_group' | 'project_group_projects' | 'ai_secret' | 'org_ai_secret' | 'org_account': The object type that the ACL applies to
    - ''
  - `variant` 'project' | 'experiment' | 'dataset' | 'project_log' | 'experiment_list': The table variant the custom column applies to. If omitted, defaults to the nonempty `subtype`, or otherwise to `object_type`. Set `experiment_list` explicitly to target the experiments list instead of experiment details. Use the same scope when creating and listing columns
  - `name` string, required: The name of the custom column
  - `expr` string, required: The expression used to extract the value for the custom column

## Response `200`

Returns the new custom column object

- CustomColumn
  - `id` string, uuid, required: Unique identifier for the custom columns
  - `object_type` 'organization' | 'project' | 'experiment' | 'dataset' | 'prompt' | 'prompt_session' | 'group' | 'role' | 'org_member' | 'project_log' | 'org_project' | 'org_audit_logs' | 'project_group' | 'project_group_projects' | 'ai_secret' | 'org_ai_secret' | 'org_account', required: The object type that the ACL applies to
  - `object_id` string, uuid, required: The id of the object the custom column is scoped for
  - `subtype` union, required: The object type that the ACL applies to
    - 'organization' | 'project' | 'experiment' | 'dataset' | 'prompt' | 'prompt_session' | 'group' | 'role' | 'org_member' | 'project_log' | 'org_project' | 'org_audit_logs' | 'project_group' | 'project_group_projects' | 'ai_secret' | 'org_ai_secret' | 'org_account': The object type that the ACL applies to
    - ''
  - `variant` 'project' | 'experiment' | 'dataset' | 'project_log' | 'experiment_list', required: The table variant that the custom column applies to
  - `name` string, required: The name of the custom column
  - `expr` string, required: The expression used to extract the value for the custom column
  - `created` string, date-time, nullable: Date of custom columns creation

## Other responses

- `400`: The request was unacceptable, often due to missing a required parameter
- `401`: No valid API key provided
- `403`: The API key doesn’t have permissions to perform the request
- `429`: Too many requests hit the API too quickly. We recommend an exponential backoff of your requests
- `500`: Something went wrong on Braintrust's end. (These are rare.)

## Changes

- **2026-11-04** `19184ec94018`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/braintrustdata/apis/braintrust-api/changes/v1/column/put.md)

---

[API](https://skmtc.dev/braintrustdata/apis/braintrust-api.md) - [All operations](https://skmtc.dev/braintrustdata/apis/braintrust-api/llms.txt) - [OpenAPI document](https://skmtc.dev/braintrustdata/apis/braintrust-api/revisions/19184ec94018?raw)