Monitor and manage Private Links

Overview

After you set up a private link, use the LiveKit CLI to manage it and check its health. Each link reports a status that reflects where it is in its lifecycle and whether the latest connectivity test passed. For the full command reference, see Private link commands.

Check link status

Retrieve the current status of a link by ID:

lk --project <LIVEKIT_PROJECT> agent private-link health-status \
  --id <PRIVATE_LINK_ID>

To list all Private Links in a project and their status:

lk --project <LIVEKIT_PROJECT> agent private-link list

Status values

A private link moves through the following states, reported by the health-status command:

The API returns each status prefixed with PRIVATE_LINK_STATUS_. For the canonical definitions, see the LiveKit protocol .

If a link is UNHEALTHY, see the troubleshooting steps for your provider: AWS or Azure.

Programmatic access

To monitor private links from your own backend, call the Private Links API with a LiveKit SDK instead of the CLI. The Go SDK  supports this API through its AgentClient.

The following example lists every private link in a project and prints the status of each:

package main

import (
	"context"
	"fmt"

	"github.com/livekit/protocol/livekit"
	lksdk "github.com/livekit/server-sdk-go/v2"
)

func main() {
	// Authenticate with your LiveKit Cloud project URL, API key, and API secret.
	agentClient, err := lksdk.NewAgentClient("<LIVEKIT_URL>", "<API_KEY>", "<API_SECRET>")
	if err != nil {
		panic(err)
	}

	ctx := context.Background()

	// List every private link in the project.
	links, err := agentClient.ListPrivateLinks(ctx, &livekit.ListPrivateLinksRequest{})
	if err != nil {
		panic(err)
	}

	// Print the current status of each link.
	for _, link := range links.Items {
		status, err := agentClient.GetPrivateLinkStatus(ctx, &livekit.GetPrivateLinkStatusRequest{
			PrivateLinkId: link.PrivateLinkId,
		})
		if err != nil {
			panic(err)
		}
		fmt.Printf("%s (%s): %s\n", link.Name, link.PrivateLinkId, status.Value.Status)
	}
}

Update a link

Private Links are immutable, so you can't change the endpoint, port, or region of a link after you create it. To change any of these settings, create a replacement link and migrate your agents to it:

1. Create a new link with the updated configuration, following the setup steps.
2. Update your agents to connect to the new *.link hostname, and deploy them.
3. Confirm no agents still use the old link, then delete it.

Remove a link

Delete a link with the CLI:

lk --project <LIVEKIT_PROJECT> agent private-link delete \
  --id <PRIVATE_LINK_ID>

Wait for the private endpoint connection to disappear from the Azure portal before you delete the Private Link Service. If the connection persists, contact LiveKit support .

Additional resources

The following topics provide additional information about Private Links.