---
title: "Private Location Service"
url: "https://www.openstatus.dev/docs/sdk/nodejs/private-location-service"
date: "2018-10-20"
author: "openstatus"
description: "Manage private locations — self-hosted probes that run monitors from your own network — with the openstatus Node.js SDK"
category: "SDK"
---

Manage [private locations](/docs/concept/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.

```typescript
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.

```typescript
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

```typescript
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.

```typescript
// 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

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

## Related resources

- **[Private location reference](/docs/reference/private-location)** — fields and the full API surface.
- **[Create a private location](/docs/guides/how-to-create-private-location)** — deploying the probe container.