Skip to main content

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.

Applies to:
  • Plan -
  • Deployment -

​
Summary

Issue: Tags logged via the SDK do not appear in the tag filter dropdown in the experiments table, even though the tag values exist in logged span data. Cause: The filter dropdown only shows tags explicitly registered at the project level — it does not auto-discover tags from ingested data. Resolution: Register tags using the UI or POST /v1/project_tag, or filter using the SQL filter as an immediate workaround.

​
Resolution steps

​
To filter by an unregistered tag immediately

​
Use the SQL filter

In the experiments table, open the SQL filter and use this syntax: 
tags includes ["<your tag name>"]
This works for any tag value regardless of whether it is registered as a project tag.

​
To make tags appear in the filter dropdown

​
Register the tag via the UI

  1. Navigate to your project settings
  2. Go to the Tags section
  3. Click “Add Tag”
  4. Enter the tag name and optional description/color
  5. Save the tag

​
Register the tag via the API (for bulk operations)

Send a POST /v1/project_tag request for each tag you want to appear in the dropdown: 
curl -X POST https://api.braintrust.dev/v1/project_tag \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "project_id": "<project_id>",
    "name": "<tag_name>",
    "color": "#000000"
  }'

​
Step 3: Repeat across projects if needed

For multiple projects, use the UI for each project or script the API request above. Use GET /v1/project_tag to list existing tags before creating duplicates.

​
Notes

  • Auto-discovery of tags from logged data is not currently supported.
  • Registering a project tag only affects the dropdown — it does not change or backfill existing logged data.
  • See the Project Tags API reference for full field options including description and color.