PRTG API v2 Overview

Introduction

The Paessler PRTG API v2 is a Representation State Transfer (REST) application programming interface (API).

This documentation refers to the PRTG API v2. It describes how to use the PRTG API v2 features and what to expect from it.

Important: The PRTG API v2 is not yet feature-complete. Most endpoints are stable and you can use them in production, with the exception of endpoints marked as experimental or deprecated. Experimental endpoints are subject to change, so use them with caution. For more information, see the section Endpoint maturity.

ℹ️ If you cannot achieve your objective with the PRTG API v2, you can try the PRTG API (v1). For more information, see the PRTG Manual: HTTP API.

Updates

The PRTG API v2 follows the PRTG release cycle. Select the Canary release channel to get the latest updates.

Versioning

This documentation refers only to the PRTG API v2. Be aware that the PRTG API v2 is completely separate from the PRTG API (v1).

Resources

Feedback and Issues

Share your feedback about the PRTG API v2 through this survey. We love to hear about features or endpoints you want to see or where we can improve.

If you need help, contact the Paessler support team via the Paessler Help Desk.

Endpoints reference

Paessler provides a list of available resources and their endpoints in the PRTG API v2 Reference.

This reference guide is a Swagger UI that contains the documentation of all individual endpoints. You can use it to try out API calls and understand error codes.

Endpoint maturity

There are three endpoint states in the PRTG API v2:

Stable

If an endpoint is not labeled as deprecated or experimental, it is stable. These are endpoints that are complete and we do not plan to change them in the future with the exception of additive changes (e.g., more query parameters, additional data returned, etc.).

We recommend that you use these endpoints in productive environments.

If we plan to remove a stable endpoint, we change its status to deprecated as a warning of its removal.

Experimental

You can recognize an experimental endpoint by the URI prefix: /experimental. These are the endpoints that we are actively working on. We might make changes to them that break your integration between releases.

Once we finish the development of an experimental endpoint, we remove the /experimental prefix and consider the endpoint stable. It is also possible that experimental endpoints never become stable. In this case, we remove the endpoint in a future release.

We do not recommend that you use these endpoints in productive environments.

ℹ️ When we introduce a new endpoint, we consider it experimental for at least one PRTG release cycle.

List of experimental endpoints

Endpoint Feature Since Stable
GET /experimental/probes Returns a list of probes 24.3.100 -
GET /experimental/groups Returns a list of groups 24.3.100 -
GET /experimental/devices Returns a list of devices 24.3.100 -
DELETE /experimental/devices Deletes a device 24.3.100 -
POST /experimental/groups/{id}/devices Creates a new device in a group 24.3.100 -
POST /experimental/probes/{id}/devices Creates a new device in a probe 24.3.100 -
GET /experimental/sensors Returns a list of sensors 24.3.100 -
GET /experimental/channels Returns a list of channels 24.3.100 -
GET /experimental/timeseries/{id}/type Returns timeseries data for a predefined time frame 24.3.100 -
GET /experimental/timeseries/{id} Returns time series data 24.3.100 deprecated
GET /experimenal/feature-toggles Returns a list of all enabled feature-toggles 24.3.100 deprecated

Deprecated

In the PRTG API v2 Reference, deprecated endpoints are gray, the endpoint name is crossed out, and there is a deprecation warning in the endpoint description. These are endpoints that we no longer support.

We plan to remove deprecated endpoints in a future release of PRTG. The deprecation warning often includes the PRTG version when we plan to remove the endpoint.

In most cases, we provide an alternate endpoint that provides a similar function.

List of deprecated endpoints

Endpoint Feature Deprecated Removed Successor
GET /channels List of channels 24.3.100 GET /experimental/channels
GET /channels/{id}/overview Channel data 24.3.100 GET /channels/{id}
GET /channels/data List of measurements 24.3.100 no version None planned
GET /devices List of devices 24.3.100 GET /experimental/devices
GET /devices/{id}/overview Device data 24.3.100 GET /devices/{id}
GET /devices/{id}/clone Device clone 24.3.100 TBD
GET /experimental/devices/{id}/settings Device data 24.3.100 24.3.100 None planned
GET /groups List of groups 24.3.100 GET /experimental/groups
GET /groups/{id}/overview Group data 24.3.100 GET /groups/{id}
GET /group/{id}/clone Group clone 24.3.100 TBD
GET /objects List of probes, groups, devices, and sensors 24.3.100 no version None planned
GET /probes List of probes 24.3.100 GET /experimental/probes
GET /probes/{id}/overview Probe data 24.3.100 GET /probes/{id}
GET /sensors List of sensors 24.3.100 GET /experimental/sensors
GET /sensors/{id}/overview Sensor data 24.3.100 GET /sensors/{id}
GET /sensors/{id}/clone Sensor clone 24.3.100 TBD
GET /sensors/alarms List of sensors with alarms 24.3.100 no version None planned
GET /experimental/sensors/{id}/settings Sensor data 24.3.100 24.3.100 None planned
GET /libraries List of libraries 24.3.100 no version None planned
GET /experimental/feature-toggles List of all enabled feature-toggles 24.3.100 no version None planned
GET /experimental/timeseries/{id} Time series data 24.3.100 no version None planned
GET /users List user 24.3.100 TBD
GET /users/{id} User data 24.3.100 TBD
GET /usergroups List of user groups 24.3.100 TBD
GET /usergroups/{id} User group data 24.3.100 TBD
GET /lookup-definitions List of lookup-definitions 24.3.100 TBD
GET /lookup-definitions/{id} Lookup-definitions data 24.3.100 TBD
GET /settings-lookups/{name} Settings-lookups data 24.3.100 TBD
GET /schemas/{kind} Schemas 24.3.100 TBD

Basic Usage

Example of a valid API request:

# PowerShell
Invoke-RestMethod "https://prtg.example.com/api/v2/settings/public"

ℹ️ Replace prtg.example.com with your PRTG instance in all examples.

Authentication

Most endpoints require authentication. They are marked with a lock symbol in the PRTG API v2 Reference.

ℹ️ An open lock indicates that you are missing the required authentication. After you are authenticated, the lock symbols are closed and you can use protected endpoints.

There are three kinds of authentication:

Credentials

To authenticate in the PRTG API v2 Reference with credentials:

  1. Open the POST /session endpoint under Authentication.
  2. Click Try it out.
  3. Enter your credentials in the Request body.
  4. Click Execute.

API key

You can create API keys through the PRTG UI (Account Settings | My Account | API Keys) or with the API key endpoint in the PRTG API v2 Reference (Accounts | POST /users/{id}/api-keys).

Authenticate in the PRTG API v2 Reference with an API key

  1. Click Authorize in the top-right corner of the endpoint list.
  2. Enter the API key or bearer token as the Value.
  3. Click Authorize to confirm.

Note: You need to enter the API key or the bearer token with the prefix Bearer.

Authenticate with the PRTG API v2

  1. Obtain a bearer token from the /session endpoint with a user name and password in a POST request:

    # PowerShell
Invoke-RestMethod -Method 'POST' -Body '{"username": "prtgadmin", "password": "prtgadmin"}' 'https://prtg.example.com/api/v2/session'

    ℹ️ The bearer token appears in the response body under the parameter token.

  2. Send the bearer token in the Authorization header with your request:

    # PowerShell
Invoke-RestMethod -Headers @{'Authorization' = 'Bearer 68015e0e-f3b7-465c-bd3d-729533cf8fce'} 'https://prtg.example.com/api/v2/endpoint'

ℹ️ Replace endpoint with the PRTG API v2 endpoint you want to use.

You can also store the token and build a header for use in later requests:

# PowerShell
$url = 'https://prtg.example.com/api/v2'
$token = (Invoke-RestMethod -Method 'POST' -Body '{"username": "prtgadmin", "password": "prtgadmin"}' ($url + '/session')).token
$headers = @{'Authorization' = 'Bearer ' + $token}

Single sign-on

If your PRTG installation has single sign-on (SSO) configured there will be a SSO Login button on top of the Swagger UI page. Clicking on it, will forward you to the configured SSO provider. If the login there was successful you will be redirected back to the Swagger UI page and should be logged in.

Note: This authentication method can only be used within the Swagger UI and is not suitable for scripting or other methods of automation.

Errors

Status Codes

If an error occurs, the PRTG API v2 responds with an HTTP status code. For more information about HTTP status codes, see RFC 7231, Section 6.

Code Standard Phrase Reason
400 Bad Request The PRTG API v2 returns 400 if any of the provided parameters or the request body are invalid.
401 Unauthorized The PRTG API v2 returns 401 if the Authorization header is missing the bearer token.
403 Forbidden The PRTG API v2 returns 403 if the requested endpoint requires a certain user access right that the requesting user account does not have.
404 Not Found The PRTG API v2 returns 404 if the referenced object does not exist or is not visible to the user.
408 Request Timeout The PRTG API v2 returns 408 if it took too long to read or write the request body or execute the request.
409 Conflict The PRTG API v2 returns 409 if the referenced object in a PUT or PATCH request does not exist or is not visible to the user.
500 Internal Server Error The PRTG API v2 returns 500 for all errors that do not have an individual HTTP status code.
502 Bad Gateway The PRTG API v2 returns 502 if the PRTG core server responded to a forwarded request with an invalid response. This status code can only occur if the PRTG core server is incompatible with the PRTG application server.
503 Service Unavailable The PRTG API v2 returns 503 if the connection to the PRTG core server is currently not working.
504 Gateway Timeout The PRTG API v2 returns 504 if the PRTG application server did not receive a response from the PRTG core server in time that was necessary to complete the request while acting as a gateway or proxy.

Error Format

The body of an error response always has the following format:

{
    "code": "INVALID_FILTER",
    "message": "The filter is invalid.",
    "request_id": "LlBbCc"
}

Error Codes

Code Description
AUTH_FAILED The authentication has failed. Enter valid credentials.
BAD_GATEWAY The response received from the PRTG core server was invalid.
BAD_REQUEST The request could not be processed. Check if the format and the data types are correct.
BODY_TOO_LARGE The body of the POST request is too large. The limit for the body size is 15 KB.
EXECUTION_TIMEOUT The execution time of a request took longer than 25 seconds.
FORBIDDEN The requested action is not allowed with the user’s current access privileges.
GATEWAY_TIMEOUT The request to the PRTG core server timed out.
INTERNAL_ERROR An unexpected internal error occurred. This is not the user’s fault.
INVALID_DURATION The provided duration is invalid. Enter a duration in seconds as a floating-point number.
INVALID_FILTER The provided filter is invalid.
INVALID_PASSWORD_RESET_TOKEN The password reset token is invalid. Enter a valid password reset token.
LICENSE_INACTIVE The PRTG license is invalid or expired.
LOGIN_FAILED The login has failed. Enter a valid user name and password or token.
LOGOUT_FAILED The logout of the active user session has failed.
LOW_PASSWORD_COMPLEXITY The entered password does not meet password complexity requirements.
NOT_FOUND The resource could not be found at this endpoint. Check the ID of the object.
METHOD_NOT_IMPLEMENTED The requested action is not implemented.
PAUSE_ADMIN The PRTG System Administrator user account cannot be paused.
RENEW_FAILED The renewal of the active user session failed.
SERVICE_UNAVAILABLE Service unavailable. The PRTG application server could not connect to the PRTG core server.
UNKNOWN An unknown error has occurred. Check the log files for more information.
WRONG_NODE_STATUS The requested action is not possible for the current status of the node.

Pagination

The PRTG API v2 uses pagination in most lists to limit the response of a request to a reasonable size.

You can define the number of elements and the starting point of the page using the limit and offset query parameters.

ℹ️ The PRTG API v2 uses the Link HTTP header (see RFC5988) in responses with paginated content to indicate URLs of the previous page and the next page. The X-Result-Count header contains the actual number of items in the actual response. The X-Total-Count header contains the total number of items available.

Limit

Use the the limit parameter to specify the maximum number of objects a request returns.

ℹ️ If you omit the limit parameter or set it to 0, the PRTG API v2 returns the maximum number of objects. The maximum number of objects in the PRTG API v2 is 3,000.

Offset

Use the offset parameter to specify at which result the PRTG API v2 starts at in a response. The index is zero based, which means that the first result in the array has the position of 0 in the index.

ℹ️ If you have an offset of 0 and a limit of 100, the PRTG API v2 returns results 0 through 99. You can see if more results are available in the Response headers, as seen in the example below.

Example:

# Request
GET /api/v2/devices?limit=50&offset=150 HTTP/1.1

# Response
HTTP/1.1 200 OK
Content-type: application/json
Content-length: 78
Link: </api/v2/devices?limit=50&offset=100>; rel="previous"
Link: </api/v2/devices?limit=50&offset=200>; rel="next"
X-Result-Count: 50
X-Total-Count: 1000
X-Request-Id: LlBbCc
...

In the example above, the response from the GET request has a X-Result-Count of 50, as defined by the limit parameter. The X-Total-Count is 1,000. This means that there are 1,000 devices available on the PRTG instance.

Example You can get data from all pages at once using PowerShell (-FollowRelLink automatically follows the Link HTTP headers):

# PowerShell
# Using $headers from the authentication example above to authenticate.
# This only works in PowerShell 6 and higher.
Invoke-RestMethod -FollowRelLink -Headers $headers -Uri ($url + '/devices')

Includes

By default, many endpoints only return the most relevant information about an object. You can request additional properties with the include parameter. This parameter expects one or more strings that are separated by a comma (,). The parameter also accepts a wildcard (*) to include every possible option. If the parameter is left empty, the PRTG API v2 only returns the default selection of information.

The type of object determines the possible options for the include parameter. Some available options appear in the desired endpoint in the PRTG API v2 Reference. You can also use the inlcude=all_sections parameter to view all available sections available for the endpoint and then refine your request.

Example:

You want to see the Credentials for Windows Systems setting of your local probe. The PRTG API v2 does not return this setting by default. To get this setting in the response, add include=windowsconnection:

# Request
GET /api/v2/devices/40?include=windowsconnection

# Response
...

 "href": "/api/v2/devices/40",
  "id": "40",
  "kind": "probedevice",
  "name": "Probe Device",
...
  "windowsconnection": {
    "windowslogindomain": "Example Domain Name",
    "windowsloginpassword": "**********",
    "windowsloginusername": "JohnQSmith"
  }
...

ℹ️ If there are no credentials saved in the setting, the parameters appear blank.

Inheritance

The inheritance parameter is a special ‘include’ parameter. In PRTG, you can set an object to inherit settings from another object that is above it in the device tree.

By default, the PRTG API v2 returns the settings that only apply to the object requested, regardless of whether that setting is inherited or defined explicitly on the object.

Example:

You have a device on the local probe. You define a scanning interval on the probe and set every object on the probe to inherit the probe’s scanning interval. As a result, the device has a scanning interval that is not explicitly but rather inherited.

If you request the device settings, the PRTG API v2 returns the set scanning interval with no additional information:

# Request
GET /api/v2/devices/40?include=intervalgroup

# Response
...
  "intervalgroup": {
    "errorintervalsdown": "1",
    "interval": "60"
  },
...

However, if you use inheritance in addition to the setting you want to see, the response includes information about the returned objects that show if a value is inherited and where the value is inherited from. All inheritance properties are prefixed with an underscore (_).

# Request
GET /api/v2/devices/40?include=intervalgroup,inheritance

# Response
...
  "intervalgroup": {
    "_inheritanceSource": {
      "id": "0",
      "name": "Root",
      "type": "REFERENCED_ROOT",
      "href": "/api/v2/groups/0"
    },
    "_inherited": true,
    "_shadowed": {
      "errorintervalsdown": "1",
      "inherittriggers": "1",
      "interval": "60"
    },
    "errorintervalsdown": "1",
    "interval": "60"
  },
 ...

ℹ️ If you defined the settings of an object explicitly, the _inherited property shows as false. The _shadowed property always shows the settings defined in the object that is the source of inheritance.

# Response on an explicitly-defined object
... 
 "_inherited": false,
 "_shadowed": null,
  "errorintervalsdown": "1",
  "interval": "60"
...

Filters

Important: The Filters feature is still a work in progress. Some settings are missing while others need to be improved, such as text filters sensitivity (e.g. removing case-sensitivity). The following section describes only what is currently available. Feature settings such as notations, property names, and property types might change in the future.

Filters limit the results a request returns. You can use the filter parameter with most endpoints that return a list of results. A filter describes the properties of the entries of interest using a simple language.

Simple Expressions

Example:

You want the request to only return devices that are online without error or warnings. In your setup, online devices are in the Up status. Therefore, you can filter with the expression status = up.

This simple expression consists of the name of a property (status), a comparison operator (=), and a value (up). Each property has a certain data type that determines which comparison operators and what kind of values you can use with the property in a filter expression.

Example: A filter in PowerShell

# PowerShell
Invoke-RestMethod -Headers $headers -Uri ($url + '/devices?filter=' + [System.Web.HttpUtility]::UrlEncode('status = up'))

Data Types

Each property and value has a specific data type. In a simple filter expression, the data type of the property must be the same as the data type of the value. Each data type has a specific notation:

Data Type Notation Example Expression
Text “text” name = "Local Probe"
Number 123 priority = 1
Boolean true, false favorite = true
Enumeration up status = up
List [1, 2] name in ["Local Probe", "Unknown Devices"]

ℹ️ The data type list is a special case in which the data type of all the elements in a list must match the data type of the property. For example, you can filter with lists of text or lists of numbers, but not a list with both text and numbers. The list expression follows the syntax parameter + in + [comma-separated list of elements].

Operators

Operators further refine the results returned by filters. PRTG API v2 supports the use of following operators.

Note: Support of individual operators may vary. Every operator cannot work with every property. For more information about the supported combinations of properties with operators, see section Properties.

Operator Description
= The equal operator compares if the value of the property is exactly equal to the value.
!= The not equal operator compares if the value of the property is not equal to the value.
< The less than operator compares if the value of the property is less than the value.
<= The less or equal operator compares if the value of the property is less than or equal to the value.
> The greater than operator compares if the value of the property is greater than the value.
>= The greater or equal operator compares if the value of the property is greater than or equal to the value.
in The in operator compares if the value of the property is equal to at least one of the values in a list.
contains The contains operator compares if the value of the property exists in the object values.
matches The matches operator compares if the value of the property is similar to the text value.

Properties

The following table shows a list of all properties and their associated operators.

Property Data Type Operators Example Expression
basic.host Text =, !=, in basic.host = "192.0.0.1"
basic.hostv6 Text =, !=, in basic.hostv6 = "::1"
id Text =, != id = "50"
kind Text =, != kind != "Probe Device"
name Text list =, !=, in name in ["Core Health", "Probe Health"]
parentid Text =, != parentid = "1"
basic.parenttags Text contains basic.parenttags contains "snmp"
status Enumeration =, != status = up
basic.tags Text contains basic.tags contains "ping"
type Enumeration =, != type = channel

Enumeration

Enumerations are a set of unique textual value tokens. In the PRTG API v2, there are two properties with the type enumeration: status and type.

Note: The support for enumeration in filter expressions is still a work in progress. We plan document all enumeration properties and their corresponding enumeration tokens in the future.

Status

The status property can have the following values:

In filter expressions, the enumeration tokens are used as identifiers without quotes, for example status = up.

Object Types

The type property can have the following values:

Filtering by Device Tree Structure

The property parentid provides access to the device tree structure in filter expressions.

Example: All children of the group with ID 2004

parentid = "2004"

# PowerShell
Invoke-RestMethod -Headers $headers -Uri ($url + '/objects?filter=' + [System.Web.HttpUtility]::UrlEncode('parentid = "2004"'))

Complex Expressions

Simple filter expressions are combined into complex filter expressions by using the logical operators such as and, or, and not. For this, parentheses are used to group expressions and to modify the evaluation order of the simple expressions within a complex filter expression.

The precedence order of the logical operators is:

Example: The precedence order of and and or

# 1
type=sensor and tags contains "HA" or status = up

# 2
type=sensor and (tags contains "HA" or status = up)

# PowerShell
# 1
Invoke-RestMethod -Headers $headers -Uri ($url + '/objects?filter=' + [System.Web.HttpUtility]::UrlEncode('type=sensor and tags contains "HA" or status = up'))
# 2
Invoke-RestMethod -Headers $headers -Uri ($url + '/objects?filter=' + [System.Web.HttpUtility]::UrlEncode('type=sensor and (tags contains "HA" or status = up)'))

The first expression finds all entries that are either a sensor and have the tag HA, or that are up. In contrast, the second expression finds all entries that are a sensor and either have the HA tag or are up. The difference is that all entries in the second list are a sensor, while entries in the first list can be of any type as long as their status is up.

Example: Negation

# 1
tags contains "HA"

# 2
not(tag contains "HA")

# PowerShell
# 1
Invoke-RestMethod -Headers $headers -Uri ($url + '/objects?filter=' + [System.Web.HttpUtility]::UrlEncode('tags contains "HA"'))
# 2
Invoke-RestMethod -Headers $headers -Uri ($url + '/objects?filter=' + [System.Web.HttpUtility]::UrlEncode('not(tag contains "HA")'))

The not operator negates the expression that follows in parentheses. The first expression in the example above matches all entries that have the tag HA. The second expression matches the exact opposite: all entries that do NOT have the tag HA.

Example Expressions

Here are some more examples of filter expressions.

Example: Find all Ping sensors in the group with ID 2004 via the /api/v2/objects API endpoint

type = sensor and tags contains "ping" and parentid = "2004"

# PowerShell
Invoke-RestMethod -Headers $headers -Uri ($url + '/objects?filter=' + [System.Web.HttpUtility]::UrlEncode('type = sensor and tags contains "ping" and parentid = "2004"'))

Example: Find all Ping sensors that are in the status “Down” in the group with ID 2004 via the /api/v2/sensors API endpoint

tags contains "ping" and parentid = "2004" and status = down

# PowerShell
Invoke-RestMethod -Headers $headers -Uri ($url + '/sensors?filter=' + [System.Web.HttpUtility]::UrlEncode('tags contains "ping" and parentid = "2004" and status = down'))

Sorting

In some endpoints, you can sort the results with the sort_by parameter.

By default, the results are sorted in ascending order. This means, if you use the parameter sort_by=id, the response contains results sorted from the lowest ID to the highest ID. If you use sort_by=name, the results appear in numerical and then alphabetical order.

Enter a minus sign (-) in front of the setting to sort the results in descending order. For example, sort_by=-name.

References

References to other objects are represented by a generic structure in JSON. Here is an example of how the primary group of a user is referenced:

Example

{
  "primary_group": {
    "id": "200",
    "type": "REFERENCED_USERGROUP",
    "name": "PRTG Administrators",
    "href": "/api/v2/usergroups/200"
  }
}

The href attribute contains the URL of the REST resource that represents the referenced object. In this case, this is the user group with the ID 200.