Introducing the PRTG Network Monitor API

Written by Dirk Paessler | Aug 18, 2008

Starting with Version 7.0.8 PRTG Network Monitor (currently in public beta testing) includes a web-based API that enables external programs to have access information from the monitoring database and to manipulate the object database of PRTG. The API is HTTP based and uses a set of URLs to access the data.

Note 1: The API is currently under development and in BETA! All features described below are working and have been tested, but there may be minor changes to the API and its output in future versions. Please help us to improve the API! Send your feedback or comments to our support team.

Note 2: After installing the latest version of PRTG please refer to the documentation that is included in the program (see menu item "Help|PRTG API") for the latest version of the documentation.

For example the following URL gives you a hierarchical list of all groups, devices and sensors:

http://yourserver/api/table.xml?content=sensortree

The first part of the URL /api/table.xml addresses an API function, here it is the function that renders a table in XML. The second part is a number of parameters that control the output.

Authentication and Security

All requests to the API are "stateless" which means that there is no multi-step login process of any kind. The authentication with username/password must always be included in each request by using the username and password parameters. With these parameters the URLs will look like this:

http://yourserver/api/table.xml?content=sensors&columns=sensor&username=myuser&password=mypassword

If you are accessing the API inside your secure LAN you can simply use HTTP. In insecure environments (e.g. when accessing your PRTG server across the Internet) you should use HTTPS requests to make sure that your parameters and passwords are encrypted.

Read Access

The easiest part is to access the current status of the monitoring data in a read only manner

Accessing Data Organized in Trees and Tables

You will have the easiest start if you click the small XML icons that most tables with data have in PRTG's web interface. Simply navigate to the information that you want to use in your external program, click the XML icon and you will be taken to a URL which renders the content of the table in XML format. You can now use the URL as it is or change various parameters (see parameter description below) to suit your needs.

Often Used XML Tables

There is a number of commonly used XML URLs:

A hierarchical list of all groups, devices and sensors (with their current state information):
```
/api/table.xml?content=sensorstree&username=myuser&password=mypassword
```

All sensors that are not up (with their current state and downtime information):

/api/table.xml?content=sensors&columns=objid,downtimetime,device,sensor,lastvalue,status,message,priority,minigraph,checkbox&filter_status=5&filter_status=4&filter_status=10&sortby=priority&username=myuser&password=mypassword

All sensors (with current status information):

/api/table.xml?content=sensors&columns=objid,group,device,sensor,status,message,lastvalue,priority,favorite&username=myuser&password=mypassword

All recent log entries:

/api/table.xml?content=messages&columns=objid,datetime,parent,type,name,status,message&sortby=date&username=myuser&password=mypassword

All recent Todos that need to be acknowledged:

/api/table.xml?content=todos&columns=objid,datetime,name,status,priority,message&sortby=date&filter_active=1&username=myuser&password=mypassword

XML Table Parameters

The following parameters are common to all XML table URLs:

Parameter	Description	Possible values
content	Selects what objects you want to have in your table	sensortree, sensors, todos, messages, values, channels
columns	Comma delimited list of columns per record	depends on the content parameter
output	Controls the output format (there are two XML formats available: xml is the default format (recommended), xmltable renders the HTML table in XML format	xml, xmltable
count	Maximum number of items (default 500)	1-50000
start	Start with this entry number (can be used with "count" to request the data page-by-page)	any
filter_drel	Only include records younger than this setting (for log tables with content="messages" only)	today, yesterday, 7days, 30days, 12months, 6months
id	The table will only contain information for this object id and its child objects (all objects will be used if this parameter is omitted)	any object id of a probe, group, device or sensor
filter_xxxx	Filters the data	filter_xxxx where xxxx is any column name used in the columns parameter
sortby	Sorts the data (add a leading "-" to reverse sort order)	any column name used in the columns parameter
username	Login name of the user account
password	Password of the user account

Requesting Various System Data

Here is a number of URLs that will provide system data:

Current system status (number of alarms, messages, etc.) in XML format:
```
/api/getstatus.xml?username=myuser&password=mypassword
```
Current system status (number of alarms, messages, etc.) in JSON format:
```
/api/getstatus.htm?username=myuser&password=mypassword
```

Write Access

There are a few URLs available to manipulate monitoring objects:

Pause a sensor or object:

/api/pause.htm?id=objectid&action=0&username=myuser&password=mypassword

Resume a sensor or object:

/api/pause.htm?id=objectid&action=1&username=myuser&password=mypassword

Scan a sensor now:

/api/scannow.htm?id=objectid&username=myuser&password=mypassword

More features will be available soon.

View full post