GET
/
v1
/
private-locations
List all private locations
curl --request GET \
  --url https://api.checklyhq.com/v1/private-locations \
  --header 'Authorization: <api-key>'
[
  {
    "id": "0baf2a80-7266-44af-b56c-2af7086782ee",
    "name": "New Private Location",
    "slugName": "new-private-location",
    "icon": "location",
    "created_at": "2023-12-25",
    "updated_at": "2023-12-25",
    "checkAssignments": [
      {
        "id": "4295d566-18bd-47ef-b22b-129a64ffd589",
        "checkId": "25039e6d-8631-4ee8-950a-bf7c893c3c1c",
        "privateLocationId": "cc3f943d-7a99-49f4-94aa-bddbaaad6eb0"
      }
    ],
    "groupAssignments": [
      {
        "id": "450d2f06-2300-46ed-8982-b63cd53fc494",
        "groupId": 10,
        "privateLocationId": "895c13cc-7de2-46df-9985-cb01b995a3cf"
      }
    ],
    "keys": [
      {
        "id": "fed3ada8-7d9b-4634-a0fe-471afe0518b6",
        "rawKey": "pl_a89026d28a0c45cf9e11b4c3637f3912",
        "maskedKey": "...6a1e",
        "created_at": "2023-12-25",
        "updated_at": "2023-12-25"
      }
    ],
    "proxyUrl": "https://user:password@164.92.149.127:3128",
    "lastSeen": "2023-12-25",
    "agentCount": 123
  }
]

​
Overview

Private locations allow you to run checks from your own infrastructure, providing monitoring from behind firewalls, in specific geographic regions, or from custom network environments. This endpoint returns all private locations configured in your account.
Private locations require running the Checkly Agent in your infrastructure to execute checks from your own network.

​
Response Example

{
  "data": [
    {
      "id": "pl_123456789",
      "name": "AWS US-East Data Center",
      "slugName": "aws-us-east-dc",
      "status": "ACTIVE",
      "region": "us-east-1",
      "tags": ["aws", "production", "us-east"],
      "agentVersion": "1.2.3",
      "lastHeartbeat": "2024-01-25T10:25:00.000Z",
      "checksCount": 15,
      "createdAt": "2024-01-15T10:30:00.000Z",
      "updatedAt": "2024-01-25T10:25:00.000Z"
    },
    {
      "id": "pl_987654321",
      "name": "On-Premise European Office",
      "slugName": "onprem-eu-office",
      "status": "INACTIVE",
      "region": "eu-west-1",
      "tags": ["on-premise", "europe"],
      "agentVersion": "1.1.8",
      "lastHeartbeat": "2024-01-24T15:30:00.000Z",
      "checksCount": 8,
      "createdAt": "2024-01-10T08:15:00.000Z",
      "updatedAt": "2024-01-24T15:30:00.000Z"
    }
  ],
  "meta": {
    "currentPage": 1,
    "totalPages": 1,
    "totalItems": 2,
    "limit": 10
  }
}

​
Private Location Status

The private location is healthy and accepting checks:
  • Agent is connected and responding
  • Recent heartbeat within expected interval
  • Ready to execute checks
  • All systems operational
The private location is not responding:
  • Agent may be disconnected
  • No recent heartbeat received
  • Checks will fail or be skipped
  • Requires investigation
The private location has issues but is partially functional:
  • Intermittent connectivity
  • Performance issues detected
  • Some checks may fail
  • Monitoring recommended
The private location is temporarily disabled for maintenance:
  • Manually disabled by user
  • Checks are suspended
  • Agent may be running but not accepting work
  • Planned maintenance mode

​
Use Cases

Internal Network Monitoring

Monitor internal services behind firewalls or in private networks

Geographic Coverage

Run checks from specific geographic locations not covered by public locations

Compliance Requirements

Meet regulatory requirements for monitoring from specific jurisdictions

Performance Testing

Test performance from your actual user locations or network paths

​
Code Examples

curl -X GET "https://api.checklyhq.com/v1/private-locations" \
  -H "Authorization: Bearer cu_1234567890abcdef" \
  -H "X-Checkly-Account: 550e8400-e29b-41d4-a716-446655440000"

​
Filtering and Monitoring

Filter private locations by various criteria:
  • limit (integer): Number of results per page (max 100)
  • page (integer): Page number (1-based)
  • status (string): Filter by status (ACTIVE, INACTIVE, DEGRADED, MAINTENANCE)
  • region (string): Filter by region
  • tag (string): Filter by tag
Monitor private location health:
// Check if private location is healthy
function isLocationHealthy(location) {
  const lastHeartbeat = new Date(location.lastHeartbeat);
  const fiveMinutesAgo = new Date(Date.now() - 5 * 60 * 1000);
  
  return location.status === 'ACTIVE' && lastHeartbeat > fiveMinutesAgo;
}

// Get stale private locations
function getStaleLocations(locations) {
  return locations.filter(location => !isLocationHealthy(location));
}
Track agent versions across your private locations:
def check_agent_versions(locations):
    versions = {}
    for location in locations:
        version = location['agentVersion']
        if version not in versions:
            versions[version] = []
        versions[version].append(location['name'])
    
    return versions

# Example usage
version_report = check_agent_versions(data['data'])
for version, location_names in version_report.items():
    print(f"Agent v{version}: {', '.join(location_names)}")

​
Private Location Management

To set up a private location:
  1. Create the Private Location: Use the API or web interface
  2. Generate API Keys: Get authentication credentials
  3. Install the Agent: Deploy the Checkly Agent in your infrastructure
  4. Configure Connectivity: Ensure network access to Checkly services
  5. Verify Status: Check that the location shows as ACTIVE
Private locations require:
  • Outbound HTTPS (443): To Checkly’s API endpoints
  • WebSocket Connection: For real-time communication
  • DNS Resolution: Access to public DNS or custom resolvers
  • Resource Requirements: Sufficient CPU and memory for check execution
Regular maintenance tasks:
  • Agent Updates: Keep agents updated to latest versions
  • Health Monitoring: Monitor heartbeat and status
  • Performance Tracking: Monitor check execution times
  • Log Review: Check agent logs for errors or warnings

​
Example Filtered Requests

curl -X GET "https://api.checklyhq.com/v1/private-locations?status=ACTIVE" \
  -H "Authorization: Bearer cu_1234567890abcdef" \
  -H "X-Checkly-Account: 550e8400-e29b-41d4-a716-446655440000"
Private locations require the Checkly Agent to be installed and running in your infrastructure. The agent handles check execution and communicates results back to Checkly’s platform.

Authorizations

​
Authorization
string
header
required

The Checkly Public API uses API keys to authenticate requests. You can get the API Key here.

Your API key is like a password: keep it secure!

Authentication to the API is performed using the Bearer auth method in the Authorization header and using the account ID.

For example, set Authorization header while using cURL:

curl -H "Authorization: Bearer [apiKey]" "X-Checkly-Account: [accountId]"

Headers

​
x-checkly-account
string

Your Checkly account ID, you can find it at https://app.checklyhq.com/settings/account/general

Response

Successful

​
id
string
required
Example:

"0baf2a80-7266-44af-b56c-2af7086782ee"

​
name
string
required

The name assigned to the private location.

Example:

"New Private Location"

​
slugName
string
required

Valid slug name.

Example:

"new-private-location"

​
created_at
string<date>
required
​
icon
string

The private location icon.

Example:

"location"

​
updated_at
string<date>
​
checkAssignments
object[]

The check this private location has assigned.

​
groupAssignments
object[]

The group this private location has assigned.

​
keys
object[]
​
proxyUrl
string

A proxy for outgoing API check HTTP calls from your private location.

Example:

"https://user:password@164.92.149.127:3128"

​
lastSeen
string<date>
​
agentCount
number