Monitor and manage Private Links

Overview

After you set up a private link, use the LiveKit CLI, the Go SDK, or the LiveKit Cloud dashboard to manage it and check its health. Each link reports a status, whether the latest connectivity test passed, and details about the link.

For the full CLI reference, see Private link commands.

To manage Private Links from your own backend, use the Go SDK . The client in its cloudagents package supports the Private Links API. The Go examples on this page read your project URL and API credentials from the LIVEKIT_URL, LIVEKIT_API_KEY, and LIVEKIT_API_SECRET environment variables.

Check link status

Retrieve the current status of a private link by ID.

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

package main

import (
	"context"
	"fmt"
	"os"

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

func main() {
	// Authenticate with your LiveKit Cloud project URL, API key, and API secret.
	agentClient, err := cloudagents.New(cloudagents.WithProject(
		os.Getenv("LIVEKIT_URL"),
		os.Getenv("LIVEKIT_API_KEY"),
		os.Getenv("LIVEKIT_API_SECRET"),
	))
	if err != nil {
		fmt.Println(err)
		return
	}

	resp, err := agentClient.GetPrivateLinkStatus(context.Background(), &livekit.GetPrivateLinkStatusRequest{
		PrivateLinkId: "<PRIVATE_LINK_ID>",
	})
	if err != nil {
		fmt.Println(err)
		return
	}

	// Print the status, its last update time, and the reason for it.
	status := resp.GetValue()
	fmt.Println("Status:", status.GetStatus())
	fmt.Println("Updated at:", status.GetUpdatedAt().AsTime())
	fmt.Println("Reason:", status.GetReason())
}

Navigate to your project Settings → Project → Private Links page in the LiveKit Cloud dashboard.
Find the link you want to check and view its status. The dashboard also shows when the status was last updated and details such as the reason for an UNHEALTHY status.

Status values

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

Status	Meaning
`PROVISIONING`	LiveKit is creating or reconciling the resources for the link. If an AWS link stays in this status, see Link stays in provisioning.
`PENDING_APPROVAL`	The connection is waiting for you to approve it in your cloud console.
`APPROVED`	You approved the connection, but a connectivity result isn't available yet. This is normally a transitional state.
`HEALTHY`	The latest connectivity check succeeded.
`UNHEALTHY`	The connectivity check failed, or the connection was rejected, disconnected, or otherwise unavailable. Check the `reason` field, your endpoint service, and your network configuration.
`UNKNOWN`	The state couldn't be mapped to a known provisioning or health state. Retry, and contact LiveKit if it persists.

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.

List private links

You can list every private link in a project, along with its ID and status, using the LiveKit CLI, the Go SDK, or the LiveKit Cloud dashboard.

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

The list response doesn't include status, so the following example requests the status of each link separately:

package main

import (
	"context"
	"fmt"
	"os"

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

func main() {
	// Authenticate with your LiveKit Cloud project URL, API key, and API secret.
	agentClient, err := cloudagents.New(cloudagents.WithProject(
		os.Getenv("LIVEKIT_URL"),
		os.Getenv("LIVEKIT_API_KEY"),
		os.Getenv("LIVEKIT_API_SECRET"),
	))
	if err != nil {
		fmt.Println(err)
		return
	}

	ctx := context.Background()

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

	// Print the current status of each link.
	for _, link := range links.GetItems() {
		resp, err := agentClient.GetPrivateLinkStatus(ctx, &livekit.GetPrivateLinkStatusRequest{
			PrivateLinkId: link.GetPrivateLinkId(),
		})
		if err != nil {
			// Report the error and continue with the remaining links.
			fmt.Printf("%s (%s): %v\n", link.GetName(), link.GetPrivateLinkId(), err)
			continue
		}
		status := resp.GetValue()
		fmt.Printf("%s (%s): %s %s\n", link.GetName(), link.GetPrivateLinkId(), status.GetStatus(), status.GetReason())
	}
}

Navigate to your project Settings → Project → Private Links page in the LiveKit Cloud dashboard.

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:

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

Remove a link

Delete a private link using the LiveKit CLI, the Go SDK, or the LiveKit Cloud dashboard.

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

package main

import (
	"context"
	"fmt"
	"os"

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

func main() {
	// Authenticate with your LiveKit Cloud project URL, API key, and API secret.
	agentClient, err := cloudagents.New(cloudagents.WithProject(
		os.Getenv("LIVEKIT_URL"),
		os.Getenv("LIVEKIT_API_KEY"),
		os.Getenv("LIVEKIT_API_SECRET"),
	))
	if err != nil {
		fmt.Println(err)
		return
	}

	privateLinkID := "<PRIVATE_LINK_ID>"

	_, err = agentClient.DestroyPrivateLink(context.Background(), &livekit.DestroyPrivateLinkRequest{
		PrivateLinkId: privateLinkID,
	})
	if err != nil {
		fmt.Println(err)
		return
	}
	fmt.Println("Deleted private link", privateLinkID)
}

Navigate to your project Settings → Project → Private Links page in the LiveKit Cloud dashboard.
Find the link you want to delete, scroll to the more menu (⋮) and select Delete private link.
Confirm the deletion by selecting Yes, delete.

After you delete the private link in LiveKit, wait until the private endpoint connection no longer appears in the Azure portal or AWS console, then delete your Azure Private Link Service or AWS endpoint service. If the connection persists, reject the connection request in the Azure portal or AWS console, or contact LiveKit support .

Additional resources

The following topics provide additional information about Private Links.

Private Links

How Private Links work, supported regions, and limitations.

Agent CLI reference

Reference for the agent commands in the LiveKit CLI including private link commands.

Private Links API

Reference for the Private Links API methods and types.