---
title: Manage private locations
source: https://docs.newrelic.com/docs/apis/nerdgraph/examples/synthetics-api/private-locations
---

[Private locations](https://docs.newrelic.com/docs/synthetics/synthetic-monitoring/private-locations/private-locations-overview-monitor-internal-sites-add-new-locations) allow you to monitor applications behind your firewall or in restricted networks. When you create a private location, you install and configure private minions to execute the monitors assigned to that private location. This tutorial provides examples of how to use the NerdGraph API to programmatically manage private locations.

## Create a private location [#create-private-location]

You can create a private location using the `syntheticsCreatePrivateLocation` mutation. This mutation allows you to set up a new private location in your monitoring infrastructure where you can deploy private minions or job managers.

### Input parameters

| Parameter                 | Data Type | Is it Required? | Description                                                                                                                                   |
| ------------------------- | --------- | --------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| `accountId`               | Integer   | Yes             | The [account ID](https://docs.newrelic.com/docs/accounts/accounts-billing/account-structure/account-id) associated with the private location. |
| `description`             | String    | No              | The description of the private location.                                                                                                      |
| `name`                    | String    | Yes             | The name of the private location.                                                                                                             |
| `shared`                  | Boolean   | No              | Specifies whether the private location is shared across the organization.                                                                     |
| `verifiedScriptExecution` | Boolean   | Yes             | If the value is true, the private location requires a password to edit.                                                                       |

### Sample request

```graphql
mutation {
  syntheticsCreatePrivateLocation(
    accountId: ACCOUNT_ID,
    name: "PrivateLocationName",
    description: "Optional description",
    shared: true,
    verifiedScriptExecution: false
  ) {
    guid
    errors {
      description
      type
    }
  }
}
```

### Sample response

A successful response returns the GUID of the newly created private location:

```json
{
  "data": {
    "syntheticsCreatePrivateLocation": {
      "guid": "PRIVATE_LOCATION_GUID",
      "errors": null
    }
  }
}
```

If there are any issues creating the private location, the `errors` array will contain objects with `description` and `type` fields explaining what went wrong.

## Update a private location [#update-private-location]

You can update an existing private location using the `syntheticsUpdatePrivateLocation` mutation. This allows you to modify the configuration of a private location that has already been created.

> #### ⚠️ IMPORTANT
>
> If a location is shared and used by other accounts in your organization to run synthetic monitors, you cannot unshare this private location until those monitors are disabled.

### Input parameters

| Parameter                 | Data Type | Is it Required? | Description                                                                                                                                                                               |
| ------------------------- | --------- | --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `guid`                    | String    | Yes             | The unique entity [GUID](https://docs.newrelic.com/docs/apis/nerdgraph/examples/synthetics-api/query-synthetics-data#query-private-locations) of the private location you want to update. |
| `description`             | String    | No              | The description of the private location.                                                                                                                                                  |
| `shared`                  | Boolean   | No              | Specifies whether the private location is shared across the organization.                                                                                                                 |
| `verifiedScriptExecution` | Boolean   | Yes             | If the value is true, the private location requires a password to edit.                                                                                                                   |

### Sample request

```graphql
mutation {
  syntheticsUpdatePrivateLocation(
    guid: "ENTITY_GUID",
    description: "EnterYourDescription",
    shared: false,
    verifiedScriptExecution: true
  ) {
    description
    verifiedScriptExecution
    errors {
      description
      type
    }
  }
}
```

### Sample response

A successful response returns the updated fields and `null` for errors:

```json
{
  "data": {
    "syntheticsUpdatePrivateLocation": {
      "description": "EnterYourDescription",
      "verifiedScriptExecution": true,
      "errors": null
    }
  }
}
```

If there are any issues updating the private location, the `errors` array will contain objects with `description` and `type` fields explaining what went wrong.

## Purge a private location job queue [#purge-private-location]

You can clear the job queue for a private location using the `syntheticsPurgePrivateLocationQueue` mutation. This is useful when you need to remove a backlog of queued synthetic monitor jobs that may have accumulated due to performance issues or temporary connectivity problems.

> #### 💡 TIP
>
> Use this operation carefully as it will permanently remove all queued jobs. Jobs currently running will not be affected.

### Input parameters

| Parameter | Data Type | Is it Required? | Description                                                                                                                                                                                                    |
| --------- | --------- | --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `guid`    | String    | Yes             | The [unique identifier (GUID)](https://docs.newrelic.com/docs/apis/nerdgraph/examples/synthetics-api/query-synthetics-data#query-private-locations) of the private location whose job queue you want to purge. |

### Sample request

```graphql
mutation {
  syntheticsPurgePrivateLocationQueue(
    guid: "PRIVATE_LOCATION_ENTITY_GUID"
  ) {
    errors {
      description
      type
    }
  }
}
```

### Sample response

A successful response returns `null` for errors:

```json
{
  "data": {
    "syntheticsPurgePrivateLocationQueue": {
      "errors": null
    }
  }
}
```

If there are any issues purging the queue, the `errors` array will contain objects with `description` and `type` fields explaining what went wrong.

## Delete a private location [#delete-private-location]

When a private location is no longer needed, you can permanently remove it using the `syntheticsDeletePrivateLocation` mutation.

> #### ⚠️ IMPORTANT
>
> Before deleting a private location, ensure no monitors are assigned to it. Deleting a private location that has active monitors assigned will cause those monitors to fail.

### Input parameters

| Parameter | Data Type | Is it Required? | Description                                                                                                                                                                               |
| --------- | --------- | --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `guid`    | String    | Yes             | The unique entity [GUID](https://docs.newrelic.com/docs/apis/nerdgraph/examples/synthetics-api/query-synthetics-data#query-private-locations) of the private location you want to delete. |

### Sample request

```graphql
mutation {
  syntheticsDeletePrivateLocation(
    guid: "ENTITY_GUID"
  ) {
    errors {
      description
      type
    }
  }
}
```

### Sample response

A successful response returns `null` for errors:

```json
{
  "data": {
    "syntheticsDeletePrivateLocation": {
      "errors": null
    }
  }
}
```

If there are any issues deleting the private location, the `errors` array will contain objects with `description` and `type` fields explaining what went wrong.

## Query private locations [#query-private-locations]

Use NerdGraph to retrieve location metadata and configuration details.

For more information, refer to:

-   [Query private locations](https://docs.newrelic.com/docs/apis/nerdgraph/examples/synthetics-api/query-synthetics-data#query-private-locations) - Get all private locations with their configuration details.

To view complete list of query examples, refer to the [Query synthetics data](https://docs.newrelic.com/docs/apis/nerdgraph/examples/synthetics-api/query-synthetics-data) document.