> ## Documentation Index
> Fetch the complete documentation index at: https://docs.braintrust.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Open trace URLs in a specific view mode

> [!NOTE]
>
> **Applies to:**
>
> * Plan - Any
> * Deployment - Any
> *
> * Use case - Generating shareable trace links that open directly in a custom or thread view

## 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://docs.braintrust.dev/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 (the **Spans** tab on desktop) | `&tvt=trace` |
| Evaluators | `&tvt=facets` |
| Custom | `&tvt=custom` |

On desktop, `thread` and `custom` open the **Thread** or **Custom view** tab in the Views pane, even if the recipient last selected the other tab, and open the **Spans** tab in the trace pane. If the recipient's saved [trace layout](https://docs.braintrust.dev/observe/examine-traces.md#choose-a-trace-layout) is **Trace**, a `custom` link switches it to **Views and trace**. A `thread` link leaves the layout unchanged, so the Views pane stays hidden until the recipient switches layouts.

Switching between **Thread** and **Custom view** updates `tvt` in your browser's address bar, so a URL copied from there opens the same tab.

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.