Skip to main content
Applies to:
  • Plan -
  • Deployment -

​
Summary

Goal: Generate trace URLs that open directly in Thread or a custom view. Features: Span.permalink(), Project Logs API URL construction, tvt query parameter.

​
Configuration steps

​
Step 1: Generate the base trace URL

SDK approach: 
span.permalink()
API-only approach (project logs): 
https://www.braintrust.dev/app/{org}/object?object_type=project_logs&object_id={projectId}&id={eventId}
Fetch the event id from the Project Logs API, then substitute the values above.

​
Step 2: Append the tvt query parameter

Append &tvt= to the base URL to control which view opens:
ViewParameter
Thread&tvt=thread
Custom&tvt=custom
Example: 
https://www.braintrust.dev/app/{org}/object?object_type=project_logs&object_id={projectId}&id={eventId}&tvt=thread

​
Step 3: Save the custom view project-wide

For &tvt=custom links, the target custom view must be saved at the project level. Otherwise, recipients may see a different view or none at all. To save a custom view project-wide: Save → Save as new view version → Update.

​
Step 4: Pin a specific custom view

To open a particular saved custom view instead of the project’s default, append the view’s ID:
SurfaceParameter
Traces&tv={viewId}
Datasets&dv={viewId}
The view ID appears in the URL when you select a saved view in the UI. Copy it from there. The tv and dv parameters take precedence over each recipient’s locally remembered view selection, so the link opens the exact view you specify. Unsaved views can’t be pinned this way. Example: 
https://www.braintrust.dev/app/{org}/object?object_type=project_logs&object_id={projectId}&id={eventId}&tvt=custom&tv={viewId}

​
Notes

  • tvt controls the visualization mode only. To open a specific saved custom view, use tv (traces) or dv (datasets) as described in Step 4.
  • Thread view is a visualization mode, not a distinct object — it has no separate permalink type. See Thread view span extraction and filtering.