Private Location Service

Manage private locations: self-hosted probes that run your monitors from inside your own network. The Private Location Service provides 5 RPC methods.

Note

Private locations are available on the Pro and Scale plans.

Create Private Location

The agent token is generated by the server and returned in the response — you cannot supply one. Use it to configure the probe container so it can pull its monitors and report results.

const { privateLocation } = await client.privateLocation.v1
  .PrivateLocationService.createPrivateLocation({
    name: "eu-datacenter",
    monitorIds: ["123456"],
    metadata: { city: "Frankfurt", provider: "Hetzner" },
  });

console.log(`Token: ${privateLocation?.token}`);

Field	Type	Required	Description
`name`	`string`	Yes	Display name, 1–256 characters.
`monitorIds`	`string[]`	No	Monitors this location should run.
`metadata`	`Record<string, string>`	No	Up to 20 labels; keys 1–64 chars, values up to 256 chars.

Caution

The token authenticates the probe as your workspace. Store it the way you store other secrets — it is returned by create, get, and update, but never by list.

List Private Locations

Returns summaries. Each carries monitorCount rather than the full monitorIds, and the agent token is deliberately omitted — use getPrivateLocation when you need it.

const { privateLocations, totalSize } = await client.privateLocation.v1
  .PrivateLocationService.listPrivateLocations({
    limit: 50,
    offset: 0,
  });

console.log(`Found ${totalSize} private locations`);

Parameter	Type	Description
`limit`	number (optional)	Max results to return (1–100, default 50).
`offset`	number (optional)	Number of results to skip (default 0).

Get Private Location

const { privateLocation } = await client.privateLocation.v1
  .PrivateLocationService.getPrivateLocation({ id: "12" });

console.log(`Status: ${privateLocation?.status}`);
console.log(`Last seen: ${privateLocation?.lastSeenAt || "never"}`);

status is read-only and derived from the agent heartbeat — PRIVATE_LOCATION_STATUS_ACTIVE when the probe is reporting normally, PRIVATE_LOCATION_STATUS_ERROR when it has stopped. lastSeenAt is an RFC 3339 string, empty if the probe has never reported.

Update Private Location

monitorIds and metadata are only applied when you explicitly opt in with updateMonitorIds / updateMetadata. Without those flags the existing associations and labels are preserved, so a partial update can't silently clear them.

// Rename only — monitors and metadata untouched.
await client.privateLocation.v1.PrivateLocationService.updatePrivateLocation({
  id: "12",
  name: "eu-datacenter-01",
});

// Replace the monitor list (an empty array clears every association).
await client.privateLocation.v1.PrivateLocationService.updatePrivateLocation({
  id: "12",
  monitorIds: ["123456", "789012"],
  updateMonitorIds: true,
});

Delete Private Location

const { success } = await client.privateLocation.v1
  .PrivateLocationService.deletePrivateLocation({ id: "12" });

Private location reference — fields and the full API surface.
Create a private location — deploying the probe container.