> ## 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.

# Open trace URLs in a specific view mode

export const plans_0 = "Any"

export const deployments_0 = "Any"

export const data_plane_version_0 = undefined

export const use_case_0 = "Use case - Generating shareable trace links that open directly in a custom or thread view"

<Note>
  **Applies to:**

  * Plan - {plans_0}
  * Deployment - {deployments_0}
  * {data_plane_version_0}
  * {use_case_0}
</Note>

## 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:**

```python theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
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](https://braintrust.dev/docs/kb/creating-permalinks-to-log-events-via-api), then substitute the values above.

### Step 2: Append the `tvt` query parameter

Append `&tvt=` to the base URL to control which view opens:

| View       | Parameter       |
| ---------- | --------------- |
| Thread     | `&tvt=thread`   |
| Timeline   | `&tvt=timeline` |
| Trace      | `&tvt=trace`    |
| Evaluators | `&tvt=facets`   |
| 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:

| Surface  | Parameter      |
| -------- | -------------- |
| 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](https://braintrust.dev/docs/kb/thread-view-span-extraction-and-filtering).