LiveKit docs › Manage & Deploy › Agent deployment › Private Links › Monitor and manage

---

# Monitor and manage Private Links

> Check the status of your Private Links and manage them with the LiveKit CLI, the Go SDK, or the LiveKit Cloud dashboard.

## Overview

After you [set up a private link](https://docs.livekit.io/deploy/agents/private-links.md), use the [LiveKit CLI](https://docs.livekit.io/reference/developer-tools/livekit-cli.md#install-the-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](https://docs.livekit.io/reference/developer-tools/livekit-cli/agent/deployment/private-links.md).

To manage Private Links from your own backend, use the [Go SDK](https://github.com/livekit/server-sdk-go). The client in its [`cloudagents`](https://pkg.go.dev/github.com/livekit/server-sdk-go/v2/pkg/cloudagents) package supports the [Private Links API](https://docs.livekit.io/reference/agents/private-links-api.md). 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.

**LiveKit CLI**:

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

```

---

**Go**:

```go
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())
}

```

---

**LiveKit Cloud**:

1. Navigate to your project **Settings** → **Project** → [Private Links page](https://cloud.livekit.io/projects/p_/settings/private-links) in the LiveKit Cloud dashboard.
2. 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`](https://docs.livekit.io/reference/developer-tools/livekit-cli/agent/deployment/private-links.md#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](https://docs.livekit.io/deploy/agents/private-links/aws.md#stuck-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](https://github.com/livekit/protocol/blob/v1.52.0/protobufs/livekit_cloud_agent.proto#L300-L313).

If a link is `UNHEALTHY`, see the troubleshooting steps for your provider: [AWS](https://docs.livekit.io/deploy/agents/private-links/aws.md#troubleshooting) or [Azure](https://docs.livekit.io/deploy/agents/private-links/azure.md#troubleshooting).

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

**LiveKit CLI**:

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

```

---

**Go**:

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

```go
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())
	}
}

```

---

**LiveKit Cloud**:

Navigate to your project **Settings** → **Project** → [Private Links page](https://cloud.livekit.io/projects/p_/settings/private-links) 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:

1. Create a new link with the updated configuration, following the [setup steps](https://docs.livekit.io/deploy/agents/private-links.md#setup) for your provider.
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).

## Remove a link

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

**LiveKit CLI**:

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

```

---

**Go**:

```go
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)
}

```

---

**LiveKit Cloud**:

1. Navigate to your project **Settings** → **Project** → [Private Links page](https://cloud.livekit.io/projects/p_/settings/private-links) in the LiveKit Cloud dashboard.
2. Find the link you want to delete, scroll to the more menu (**⋮**) and select **Delete private link**.
3. 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](https://cloud.livekit.io).

## Additional resources

The following topics provide additional information about Private Links.

- **[Private Links](https://docs.livekit.io/deploy/agents/private-links.md)**: How Private Links work, supported regions, and limitations.

- **[Private links CLI reference](https://docs.livekit.io/reference/developer-tools/livekit-cli/agent/deployment/private-links.md)**: Reference for the `lk agent private-link` commands.

- **[Private Links API](https://docs.livekit.io/reference/agents/private-links-api.md)**: Reference for the Private Links API methods and types.

---

This document was rendered at 2026-11-14T14:19:26.076Z.
For the latest version of this document, see [https://docs.livekit.io/deploy/agents/private-links/monitoring.md](https://docs.livekit.io/deploy/agents/private-links/monitoring.md).

To explore all LiveKit documentation, see [llms.txt](https://docs.livekit.io/llms.txt).