Depot live

Registers the live-metrics WebSocket.

This page is generated from the Depot route table. Every operation carries the permission it needs and the anchor an agent can link to.

GET /api/v1/endpoints/{agentID}/live

GETendpoint:readtenant facehosteditmspremoteIdempotentWebSocket

From an MSP console, prefix the path with /api/v1/clients/{clientID} to reach one client.

Source: [object Object]

liveMetrics subscribes the browser to one endpoint’s live samples for the life of the socket.

Every rejection happens BEFORE the upgrade so the caller gets a JSON problem document it can act on, rather than a socket that closes with no explanation.

Parameters

Name	In	Type	Required	Description
agentID	path	string	Yes
allowMetered	query	string	No
intervalMs	query	string	No
processes	query	string	No
topN	query	string	No

Responses

Status	Body	Description
101	None	Switching protocols. The connection continues as a websocket; see x-outpost-transport.
401	application/problem+json, ProblemDetails	No signed-in identity.
403	application/problem+json, ProblemDetails	The identity does not hold endpoint:read.
404	application/problem+json, ProblemDetails	Endpoint not found.
409	application/problem+json, ProblemDetails	Endpoint is not connected, so it cannot stream live metrics.
500	application/problem+json, ProblemDetails	No client context in request.
503	application/problem+json, ProblemDetails	Live metrics are not available.

Request samples

curl

# Sign in first. outpost_console is a session cookie, so send it with every request.
# This endpoint upgrades to a WebSocket. The sample shows the handshake only.
# This operation is idempotent. Repeating it does not repeat its effect.
curl -X GET 'https://depot.example.com/api/v1/endpoints/<agentID>/live?allowMetered=<allowMetered>&intervalMs=<intervalMs>&processes=<processes>&topN=<topN>' \
  -H 'X-CSRF-Token: <csrf-token>' \
  -H 'Accept: application/json' \
  -b 'outpost_console=<console-session>'

PowerShell

# Sign in first. outpost_console is a session cookie, so send it with every request.
# This endpoint upgrades to a WebSocket. The sample shows the handshake only.
# This operation is idempotent. Repeating it does not repeat its effect.

$headers = @{
    'X-CSRF-Token' = '<csrf-token>'
    'Accept' = 'application/json'
    'Cookie' = 'outpost_console=<console-session>'
}

$response = Invoke-RestMethod `
    -Method Get `
    -Uri 'https://depot.example.com/api/v1/endpoints/<agentID>/live?allowMetered=<allowMetered>&intervalMs=<intervalMs>&processes=<processes>&topN=<topN>' `
    -Headers $headers

$response | ConvertTo-Json -Depth 10

Python

# Sign in first. outpost_console is a session cookie, so send it with every request.
# This endpoint upgrades to a WebSocket. The sample shows the handshake only.
# This operation is idempotent. Repeating it does not repeat its effect.

import requests

url = "https://depot.example.com/api/v1/endpoints/<agentID>/live"
params = {
    "allowMetered": "<allowMetered>",
    "intervalMs": "<intervalMs>",
    "processes": "<processes>",
    "topN": "<topN>",
}
headers = {
    "X-CSRF-Token": "<csrf-token>",
    "Accept": "application/json",
}
cookies = {
    "outpost_console": "<console-session>",
}

response = requests.get(url, params=params, headers=headers, cookies=cookies, timeout=30)
response.raise_for_status()
print(response.json())

Go

// Sign in first. outpost_console is a session cookie, so send it with every request.
// This endpoint upgrades to a WebSocket. The sample shows the handshake only.
// This operation is idempotent. Repeating it does not repeat its effect.
package main

import (
  "fmt"
  "io"
  "log"
  "net/http"
)

func main() {
  req, err := http.NewRequest(http.MethodGet, "https://depot.example.com/api/v1/endpoints/<agentID>/live?allowMetered=<allowMetered>&intervalMs=<intervalMs>&processes=<processes>&topN=<topN>", nil)
  if err != nil {
    log.Fatal(err)
  }

  req.Header.Set("X-CSRF-Token", "<csrf-token>")
  req.Header.Set("Accept", "application/json")
  req.AddCookie(&http.Cookie{Name: "outpost_console", Value: "<console-session>"})

  resp, err := http.DefaultClient.Do(req)
  if err != nil {
    log.Fatal(err)
  }
  defer resp.Body.Close()

  out, err := io.ReadAll(resp.Body)
  if err != nil {
    log.Fatal(err)
  }
  fmt.Println(resp.Status, string(out))
}

TypeScript

// Sign in first. outpost_console is a session cookie, so send it with every request.
// This endpoint upgrades to a WebSocket. The sample shows the handshake only.
// This operation is idempotent. Repeating it does not repeat its effect.
// The session cookie is set by signing in. A script cannot set it itself.

const url = new URL("https://depot.example.com/api/v1/endpoints/<agentID>/live");
url.searchParams.set("allowMetered", "<allowMetered>");
url.searchParams.set("intervalMs", "<intervalMs>");
url.searchParams.set("processes", "<processes>");
url.searchParams.set("topN", "<topN>");

const response = await fetch(url, {
  method: "GET",
  headers: {
    "X-CSRF-Token": "<csrf-token>",
    "Accept": "application/json",
  },
  credentials: "include",
});

if (!response.ok) {
  throw new Error(`Request failed with status ${response.status}`);
}

const data = await response.json();
console.log(data);

C#

// Sign in first. outpost_console is a session cookie, so send it with every request.
// This endpoint upgrades to a WebSocket. The sample shows the handshake only.
// This operation is idempotent. Repeating it does not repeat its effect.

using System;
using System.Net.Http;

using var client = new HttpClient();

var request = new HttpRequestMessage(HttpMethod.Get, "https://depot.example.com/api/v1/endpoints/<agentID>/live?allowMetered=<allowMetered>&intervalMs=<intervalMs>&processes=<processes>&topN=<topN>");
request.Headers.TryAddWithoutValidation("X-CSRF-Token", "<csrf-token>");
request.Headers.TryAddWithoutValidation("Accept", "application/json");
request.Headers.TryAddWithoutValidation("Cookie", "outpost_console=<console-session>");

var response = await client.SendAsync(request);
response.EnsureSuccessStatusCode();
Console.WriteLine(await response.Content.ReadAsStringAsync());