<%NUMBERING1%>.<%NUMBERING2%>.<%NUMBERING3%> PRTG Manual: Live Data

You can access live data and live status data of objects using the PRTG Application Programming Interface (API).

icon-i-round-redAuthentication with username and passhash (or username and password) must always be included in each PRTG API request. See section Authentication for more information.

Here are quick links for ease of use.

Property/Setting of an Object

You can get the properties or settings of an object (name, hostname, url) using the following API calls.

icon-i-roundBecause properties may contain HTML content, we recommend that you include &show=nohtmlencode in all getobjectproperty API calls.

icon-speechExamples

Get an object property/setting:

/api/getobjectproperty.htm?id=objectid&name=propertyname&show=nohtmlencode

icon-i-roundFor propertyname, look at the name of the INPUT fields while editing an object. The propertyname parameter can be discerned by opening the Settings page of an object and looking at the HTML source of the INPUT fields. For example, the INPUT field for the tags of an object has the name tags_. Leave away the _ and use the rest (tags) as a value for the propertyname parameter.
 
Get a list of all tags for object id 1003

/api/getobjectproperty.htm?id=1003&name=tags&show=nohtmlencode

The XML result looks like this:

    <?xml version="1.0" encoding="UTF-8" ?>
    <prtg>
        <version>18.3.45.1224+</version>
        <result>probehealthsensor</result>
    </prtg>

getobjectproperty.htm supports the following object types:

  • probe
  • group
  • device
  • sensor
  • channel
  • library
  • map
  • notification
  • report
  • schedule
  • user account

getobjectproperty.htm does not support the object types ticket and user group.

Property of a Channel

With this API call, you can get a sensor's channels settings, for example channel limits. In general, this works like getting properties of any other object. To get channel properties via the API, you need to provide

  • the ID of a sensor (parameter id)
  • a subtype (channel for channels), and
  • a subid (ID of the channel you want to edit)

icon-i-roundBecause properties may contain HTML content, we recommend that you include &show=nohtmlencode in all getobjectproperty API calls.

icon-speechExamples

Get a channel limit

/api/getobjectproperty.htm?id=sensorid&subtype=channel&subid=channelid&name=limitname&show=nohtmlencode

For example, the following API call gets the upper warning limit of a channel with the ID 0 of a sensor with the ID 1003

/api/getobjectproperty.htm?id=1003&subtype=channel&subid=0&name=limitmaxwarning&show=nohtmlencode

The XML result looks like this:

    <?xml version="1.0" encoding="UTF-8" ?>
    <prtg>
        <version>18.3.45.1224+</version>
        <result>25</result>
    </prtg>

Channels: Available Parameters

Name of INPUT field

Settings Name (as displayed in the web Interface)

name

Name

limitmode

Limit disabled or enabled (0 or 1)

limitmaxerror

Upper Error Limit

limitmaxwarning

Upper Warning Limit

limitminwarning

Lower Warning Limit

limitminerror

Lower Error Limit

limiterrormsg

Error Limit Message

limitwarningmsg

Warning Limit Message

Status of an Object

You can get the status information (lastvalue, downtime) of an object using the following API calls:

icon-speechExamples

Get object status:

/api/getobjectstatus.htm?id=objectid&name=columnname

icon-i-roundFor columnname, see section Supported Output Columns ("columns=" Parameter).
 

The XML result looks like this:

    <?xml version="1.0" encoding="UTF-8" ?>
    <prtg>
        <version>18.1.37.10127+</version>
        <result>True</result>
    </prtg>

Sensor Details

icon-i-roundYou need the sensor ID to get details about a sensor. You can find the ID on the sensor's overview tab or by hovering over a sensor in the device tree, for example.

icon-speechExamples

Get details about a sensor in XML:

/api/getsensordetails.xml?id=sensorid

Get details about a sensor in JSON:

/api/getsensordetails.json?id=sensorid

Property or Status of Multiple Objects

Most data that you can request from the API is available in data tables in XML, JSON, and CSV format (using XML format is recommended). The API function /api/table.xml is used to access data in tables. Here are some sample calls (URLs are shown without authentication parameters to improve readability).

icon-i-roundThe example URLs only show the XML URLs. Use the API function /api/table.csv or the output=csvtable parameter to select CSV format, or /api/table.json to return JSON format.

icon-speechExamples

A hierarchical list of all groups, devices, and sensors with their current status information:

/api/table.xml?content=sensortree

All sensors (with current status information):

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

All recent log entries:

/api/table.xml?content=messages&columns=objid,datetime,parent,type,name,status,message

icon-i-bluesensortree does not support JSON output.

You will have the easiest start if you use the XML table query builder or click the XML icon that most data tables have in the PRTG web interface. Simply navigate to the information that you want to use, click the XML icon, and you will be taken to a URL that renders the content of the table in XML format. You can now use the URL as it is or change various parameters to suit your needs.

icon-book-bulbFor more information on possible raw message status values returned by table-based API calls, see the Knowledge Base article Is there a list of log status values for the PRTG API?

XML Table Query Builder

You can use the query builder tool to experiment with the API and to fine-tune your queries. You can find it in the web interface under Setup | PRTG API, section Live Data.

Output Data Format

XML data from the PRTG API contains the fields that you have requested in the columns parameter. In most cases, numerical values will be included twice: One field contains the value in human-readable format and an additional _RAW field contains the value as a number, which is better suited for further processing and calculations.

icon-speechExample

        <status>Up</status>
        <status_RAW>3</status_RAW>
        <lastvalue>98 %</lastvalue>
        <lastvalue_RAW>97.7583</lastvalue_RAW>
        <message>Created.<br/>18.3.43.1360</message>
        <message_RAW>Created. 18.3.43.1360</message_RAW>

  • The status field shows the value Up (the according RAW value is 3).
  • The lastvalue field shows the value 98% (the according RAW value is 97.7583).
  • The message field shows the text Created.<br/>18.3.43.1360 (the according RAW value is Created. 18.3.43.1360).

icon-i-roundStrings returned from _RAW columns are surrounded by double quotes (") in JSON output.

RAW Date/Time Format

For columns with date/time value, the RAW value is defined as follows: The integral part of a value is the number of days that have passed since Dec 30th, 1899. The fractional part of a value is a fraction of a 24-hour day that has elapsed. To find the fractional number of days between two dates, simply subtract the two values. Similarly, to increment a date and time value by a certain fractional number of days, add the fractional number to the date and time value.

Here are some examples of date/time RAW values and their corresponding dates and times:

RAW Date/Time Value

Description

0

12/30/1899 00h00m (12:00 midnight)

2.75

1/1/1900 18h00m (6:00 pm)

35065

1/1/1996 00h00m (12:00 midnight)

Common Data Table Parameters

The following parameters are common to all data table API calls:

Parameter

Description

Possible Values

content

Selects what objects you want to have in your table

sensortree (JSON output not supported), devices, sensors, tickets, ticketdata, messages, values, channels, reports, storedreports, toplists, sysinfo (only JSON output supported)

columns

Comma-separated list of columns per record

see Supported Output Columns ("columns=" Parameter)

output

Controls the output format

  • xml: default format (recommended)
  • xmltable: an HTML table in XML format
  • csvtable: comma-separated format
  • html: HTML table
  • json: JSON format
  • jsontable: a table in JSON format

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

Filtering by Object ID

Add an ID parameter (for example, id=1) to the API URL to select a subset of items for the data table, for example, to reduce the amount of data transferred for each data table API call). The data table will only contain information for this object ID and its child objects.

icon-i-roundSome table types require an ID. If you omit the ID parameter or it has the value zero (0), all available objects will be used.

Table Type
(content=)

ID Required or Optional

Description

Object Types Allowed for the ID

sensortree

optional

You will only get a part of the tree (the object with the given ID and all child objects below it).

icon-i-round-redJSON output is not supported.

Probe or group

sensors
devices

optional

You will only get the object with the given ID and all child objects below it.

Probe, group, or device

tickets
messages

optional

You will only get tickets or logfile entries that are related to the object with the given ID or any child objects below it.

Any object

values
channels

required

You will get the data values (or channels) of the sensor with the given ID.

Sensor

reports

not used

This data table will always include all reports.

n/a

storedreports

required

You will get a list of stored PDF files of the report selected by the ID.

Report

ticketdata

required

You will get the history of the ticket selected by the ID.

Ticket

sysinfo

required

You will get system information of the object with the given ID.

Device

Sorting and Advanced Filtering

There are various options to further filter and to sort the data for each data table API call:

Parameter

Description

Possible Values

filter_drel

Only include records younger than this setting

icon-i-round-redFor content=messages and content=tickets only.

today, yesterday, 7days, 30days, 12months, 6months

filter_status

Only include sensors with a specific status. Using multiple filter_status fields performs a logical OR.

icon-i-round-redFor content=sensors only.

Unknown=1, Collecting=2, Up=3, Warning=4, Down=5, NoProbe=6, PausedbyUser=7, PausedbyDependency=8, PausedbySchedule=9, Unusual=10, PausedbyLicense=11, PausedUntil=12, DownAcknowledged=13, DownPartial=14

filter_tags

Only include sensors with a specific tag. Using multiple filter_tag fields performs a logical OR.

icon-i-round-redFor content=sensors only.

@tag(tagname)

filter_xyz

Filters the data. (Samples: filter_type=ping, filter_favorite=1). Using multiple filter_xyz fields performs a logical OR.

Filtering using columns is only possible for tree objects. You cannot use columns to filter objects like messages or tickets, for example. For content=tickets, you can use the special filter terms
filter_status
filter_user, and
filter_type (this corresponds to column tickettype).

Like for messages, you can also use
filter_drel,
filter_dstart,
and filter_dend.

icon-i-round-redMultiple filters are not available for tickets.

filter_xyz where xyz is any column name used in the columns parameter
Substrings: use filter_xyz=@sub(substring1,substring2)
Values not equal/above/below: use filter_xyz=@neq(value), filter_xyz=@above(value), filter_xyz=@below(value)

sortby

Sorts the data. If this parameter is omitted, the table will be sorted based on the first column. Add a leading "-" to reverse sort order. (Samples: sortby=name, sortby=lastvalue, sortby=-lastvalue, sortby=uptime)

Any column name used in the columns parameter.

icon-i-roundLog tables with content=messages are always sorted by descending date.

icon-speechExamples

Here are some samples for filtered API calls:

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

/api/table.xml?content=sensors&columns=objid,downtimesince,device,sensor,lastvalue,status,message,priority&filter_status=5&filter_status=4&filter_status=10&filter_status=13&filter_status=14&sortby=priority

Fastest Ping sensors:

/api/table.xml?content=sensors&columns=objid,sensor,lastvalue,status,message&sortby=lastvalue&filter_type=ping

Log entries of the last 7 days for object id 2003:

/api/table.xml?content=messages&id=2003&start=0&filter_drel=7days&columns=objid,datetime,type,name,status,message

Supported Output Columns ("columns=" Parameter)

You can use the following column names for the columns parameter (separated by comma, for example, columns=objid,name,type).

Column Name

Description

Can be Used for

objid

ID of the current object

all object tables

type

Displays the object type (group, device, report, etc.), or the sensor type (ping, http, etc.), or event type for tickets (relevant for ToDo tickets)

all object tables

name

Name of the object or channel.

For log messages/tickets: the name of the related object.

For stored reports: the name of the report file.

all object tables, channels, messages, storedreports, toplists, tickets

tags

List of all tags (for tickets: tags for the related object). This includes tags from the object itself plus those inherited from parent objects.

all object tables (except for user)

active

Displays true/false depending on whether an object is set to paused by a user (for tickets: related object). For notifications that are paused by schedule, it also displays the end of the schedule.

all object tables

downtime

Cumulated downtime of a sensor (displayed as percentage of uptime+downtime)

sensors

downtimetime

Cumulated downtime of a sensor (in minutes/hours)

sensors

downtimesince

Elapsed time since last UP of a sensor

sensors

uptime

Cumulated uptime of a sensor (displayed as percentage of uptime+downtime)

sensors

uptimetime

Cumulated uptime of a sensor (in minutes/hours)

sensors

uptimesince

Elapsed time since last DOWN of a sensor

sensors

knowntime

Sum of cumulated uptime and downtime of a sensor

sensors

cumsince

Timestamp when accumulation of uptimes/downtimes began

sensors

sensor

Name of the sensor

sensors, toplists

interval

This displays the effective interval setting for a sensor

sensors

lastcheck

Timestamp of the last sensor result

sensors

lastup

Timestamp of the most recent UP status

sensors

lastdown

Timestamp of the most recent DOWN status

sensors

device

Name of the associated device

sensors, devices

group

Name of the associated group

sensors, devices, groups

probe

Name of the associated probe

sensors, devices, groups, probes

grpdev

Name of associated device and group separated by slash

sensors, devices

notifiesx

Number of each trigger type defined for this sensor tree object

probes, groups, devices, sensors

intervalx

Displays either 'inherited' or the current interval setting of that object

probes, groups, devices, sensors

accessrights

Displays the access rights of the current user for a sensor tree object

all objects (except for user), for example, probes, groups, devices, sensors

dependency

Displays the name of an associated dependency or 'parent'

probes, groups, devices, sensors

probegroupdevice

Complete object hierarchy with names of associated device, group, and probe separated by slash. If more than one group is in the object hierarchy, these are displayed with '..'

sensor, device, group, probe

status

For sensor tree objects: status of the object (1=Unknown, 2=Scanning, 3=Up, 4=Warning, 5=Down, 6=No Probe, 7=Paused by User, 8=Paused by Dependency, 9=Paused by Schedule, 10=Unusual, 11=Not Licensed, 12=Paused Until, 13=Down Acknowledged, 14=Down Partial)

For messages: category of the log message

For tickets: status of ticket (open, resolved, closed)

sensors, devices, groups, probes, messages, tickets

message

Detailed message of a sensor tree object (for example, last error of a sensor) or a history entry, log entry, ticket subject

sensors, devices, groups, probes, messages, tickets, ticketdata, history

priority

Displays the priority setting of a sensor tree object or the priority of a log entry/ticket

sensors, devices, groups, probes, messages, tickets (not supported: schedule, notification, user)

lastvalue

Last sensor result value or channel values.

When used with channels, the 'lastvalue_' has to be used to automatically display volumes and speed

sensors, channels

upsens

Number of sensors currently in UP state.

Only the sensor itself or sensors in the hierarchy below the displayed object are counted

all sensors, devices, groups, probes

downsens

Number of sensors currently in DOWN state.

Only the sensor itself or sensors in the hierarchy below the displayed object are counted

all sensors, devices, groups, probes

downacksens

Number of sensors currently in DOWN (ACKNOWLEDGED) state.

Only the sensor itself or sensors in the hierarchy below the displayed object are counted

all sensors, devices, groups, probes

partialdownsens

Number of sensors currently in PARTIAL DOWN state.

Only the sensor itself or sensors in the hierarchy below the displayed object are counted

all sensors, devices, groups, probes

warnsens

Number of sensors currently in WARNING state.

Only the sensor itself or sensors in the hierarchy below the displayed object are counted

all sensors, devices, groups, probes

pausedsens

Number of sensors currently in a PAUSED state. This includes all PAUSED states (paused by user', 'paused by dependency, 'paused by schedule', etc.)

all sensors, devices, groups, probes

unusualsens

Number of sensors currently in UNUSUAL state.

Only the sensor itself or sensors in the hierarchy below the displayed object are counted

all sensors, devices, groups, probes

undefinedsens

Number of sensors currently in UNDEFINED state.

Only the sensor itself or sensors in the hierarchy below the displayed object are counted

all sensors, devices, groups, probes

totalsens

Number of sensors.

Only the sensor itself or sensors in the hierarchy below the displayed object are counted

all sensors, devices, groups, probes

value

Displays a channel value or a toplist value.

Should only be used as 'value_', because then it will be expanded for all visible channels/toplist columns

values, topdata

coverage

Displays the sensor coverage of a time span in a value table

values

favorite

Displays an exclamation mark when the sensor tree object is marked as favorite

sensors, devices, groups, probes

user

Displays the user responsible for a history entry or the user (or user group) a ticket is assigned to

history, tickets, ticketdata

parent

Name of the parent object of the associated object of a log message

messages

datetime

Timestamp or timespan of an object (for tickets: last modification)

messages, tickets, ticketdata, values, history, storedreports, topidx

dateonly

Like datetime but only the date part

messages, tickets, history, values

timeonly

Like datetime but only the time part

messages, tickets, history, values

schedule

For sensor tree objects: displays the name of an associated schedule

For reports: displays the report generation schedule

probes, groups, devices, sensors, reports

period

Displays the period of a report (day, week, etc.)

reports

email

Displays the email address of a report

reports

template

Displays the template used by a report

reports

lastrun

Timestamp of the last generation of a report

reports

nextrun

Timestamp of the next generation of a report

reports

size

Size of a stored report

size of a stored report

minigraph

Numerical data for the minigraphs. Numbers are 5-minute averages for the last 24 hours (must be scaled to the maximum of the series). There are two datasets: "|" separates measured value series and error series.

sensors

deviceicon

Device icon

devices

comments

Object comments

For tickets: related object

all objects

host

Hostname or IP address

devices

devices

For probes: probe status (0=Disconnected, 1=Unauthorized, 2=Connected, 3=Banned, 4=Init)

For groups: auto-discovery status

probes, groups

basetype

Object type (string)

all tree objects

baselink

URL of the object

all tree objects

icon

URL of the device icon

devices

parentid

ID of the parent object or ID of a ticket

all tree objects, tickets

location

Location property (used in Geo Maps)

devices

fold

Sub-objects are folded up (true) or down (false)

For tickets: user (or user group) to which a ticket is assigned read it since last change

probes, groups, tickets

groupnum
devicenum

Number of groups/devices in a probe/group node

probes, groups

tickettype

Type of the ticket: user, notification, todo

tickets

modifiedby

User who edited the ticket most recently

tickets, ticketdata

actions

Types of all ticket edits

ticketdata

content

The text of the ticket that was added with the last edit

ticketdata

_key, _value

The key value pair from the system table

sysinfo (category: system)

_displayname, _class, _caption

Display name, class, and caption from the system table.

sysinfo (category: hardware)

_user, _domain

User and domain pair from the system table.

sysinfo (category: loggedonusers)

_displayname, _creationdate, _processid

Display name, creation date, and process id from the system table.

sysinfo (category: processes)

_displayname, _state, _startmode

Display name, state, and start mode from the system table.

sysinfo (category: services)

_displayname, _version

Display name and version pair from the system table.

sysinfo (category: software)

Current System Status

The following API calls are lightweight options to get status data like number of alarms or messages.

icon-speechExamples

Current system status in XML format:

/api/getstatus.xml?id=0

Current system status in JSON format:

/api/getstatus.json?id=0

All currently used sensor types in JSON format:

/api/sensortypesinuse.json

Current number of all sensor states:

/api/gettreenodestats.xml

Current Ticket Status and Message

The following API calls return status and message of a ticket.

icon-speechExamples

The status of a ticket:

/api/getticketstatus.htm?id=ticketid

The subject and assignee of a ticket:

/api/getticketmessage.htm?id=ticketid

System Information

To retrieve system information using API calls, we recommend that you use the following order:

  1. Refresh the system information so that it is current.
    For details, see System Information—Scan Now.
  2. Retrieve generic system information to ensure that the last scan (step 1) was successful and that there are no errors.
    For details, see System Information—Generic Data.
  3. Retrieve system information in the form of data tables.
    For details, see System Information—Data Tables.

icon-i-blueSystem information API calls only support JSON output.

System Information—Scan Now

The following API calls to retrieve current information for a System Information category. To refresh system information via the API, you need to provide

icon-speechExamples

Refresh process information

/api/sysinfochecknow.json?id=deviceid&kind=processes

Refresh hardware information

/api/sysinfochecknow.json?id=deviceid&kind=hardware

icon-i-bluesysinfochecknow only supports JSON output.

Supported Output Columns ("kind=" Parameter)

System Information: Available Parameters

Column Name

Category (as displayed in the web Interface)

system

System

hardware

Hardware

processes

Processes

services

Services

software

Software

loggedonusers

Users

System Information—Generic Data

The following API calls to retrieve generic data about the System Information category since the last scan, for example timestamps and if the last scan was successful. To retrieve this information via the API, you need to provide

icon-speechExamples

Users

/api/sysinfo.json?id=deviceid&kind=loggedonusers

Services

/api/sysinfo.json?id=deviceid&kind=services

icon-i-bluesysinfo only supports JSON output.

System Information—Data Tables

The following API calls retrieve all information from a System Information category table. To retrieve this information via the API, you need to provide

icon-speechExamples

System

/api/table.json?content=sysinfo&category=system&columns=_key%2C_value&id=deviceid

Software

/api/table.json?content=sysinfo&category=software&columns=_displayname%2C_version%2C*&id=deviceid

icon-i-blueData tables for system information only support JSON output.

More

Knowledge Base: How can I use the PRTG Application Programming Interface (API)?

 

Application Programming Interface (API) Definition—Topics

Keywords: