PRTG Manual: Multiple Object Property or Status

You can access live data and live status data of multiple objects using the PRTG API.

i_round_redAuthentication with API key or user name and passhash (or user name and password) must always be included in each PRTG API request. See section HTTP API for more information.

In this section:

Property or Status of Multiple Objects

Most data that you can request from the PRTG API is available in data tables in the Extensible Markup Language (XML) format, the JavaScript Object Notation (JSON) format, and the comma-separated values (CSV) format (using the 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 enhance readability).

i_round_blueThe example URLs only show the XML URLs. Use the API function /api/table.csv or the output=constable parameter to select the CSV format, or /api/table.json to return the JSON format.

i_speechExamples

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

/api/table.xml?content=sensortree

i_round_bluesensortree does not support JSON output.

All sensors (with 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

You have the easiest start if you use the table query builder or click b_view_xml, which most data tables have in the PRTG web interface. Navigate to the information that you want to use, click b_view_xml, and you are 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.

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

Table Query Builder

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

Output Data Format

XML data from the PRTG API contains the fields that you requested in the columns parameter. In most cases, numeric values are 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.

i_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).

i_round_blueStrings returned from _RAW columns are surrounded by double quotation marks (") 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, 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

Select the objects that 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

Control the output format

xml: default format (recommended)

xmltable: an HTML table in the XML format

csvtable: CSV format

html: HTML table

json: JSON format

jsontable: a table in the JSON format

count

Maximum number of items (The default count is 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 only contains information for this object ID and its child objects.

i_round_blueSome table types require an ID. If you omit the ID parameter or if it has the value zero (0), all available objects are used.

Table Type
(content=)

ID Required or Optional

Description

Object Types Allowed for the ID

sensortree

optional

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

i_round_redJSON output is not supported.

Probe

Group

sensors
devices

optional

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

Probe

Group

Device

tickets
messages

optional

You only get tickets or log file entries that are related to the object with the specified ID or any child objects below it.

Any object

values
channels

required

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

Sensor

reports

not used

This data table always includes all reports.

n/a

storedreports

required

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

Report

ticketdata

required

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

Ticket

sysinfo

required

You get system information of the object with the specified 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

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.

i_round_redFor content=sensors and content=devices 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.

i_round_redFor content=sensors only.

@tag(tagname)

filter_xyz

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

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.

i_round_redMultiple filters are not available for tickets.

filter_xyz where xyz is any column name used in the columns parameter

Numerical values not equal to/above/below: use filter_xyz=@neq(value), filter_xyz=@above(value), filter_xyz=@below(value)

Partial match substrings: use filter_xyz=@sub(substring1,substring2)

Exact match substrings: use filter_xyz=@txt(substring) or filter_xyz=@ntxt(substring)

i_round_red@txt and @ntxt require that you enter the entire substring to filter properly. The filters are case sensitive. Use @ntxt if you want to define a substring to exclude from the results.

sortby

Sort the data. If this parameter is omitted, the table is 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.

i_round_blueLog tables with content=messages are always sorted by descending date.

i_speechExamples

Here are some samples for filtered API calls:

All sensors that are not in the Up status (with their status 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

What It Displays

Can Be Used for

objid

ID of the object

all object tables

type

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 tags that are inherited from parent objects.

all object tables (except for user)

active

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 the sensor (displayed as percentage of uptime+downtime)

sensors

downtimetime

Cumulated downtime of the sensor (in minutes/hours)

sensors

downtimesince

Elapsed time since last Up status of the sensor

sensors

uptime

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

sensors

uptimetime

Cumulated uptime of the sensor (in minutes/hours)

sensors

uptimesince

Elapsed time since the last Down status of the sensor

sensors

knowntime

Sum of cumulated uptime and downtime of the sensor

sensors

cumsince

Time stamp when accumulation of uptimes/downtimes began

sensors

sensor

Name of the sensor

sensors

toplists

interval

Effective interval setting for the sensor

sensors

lastcheck

Time stamp of the last sensor result

sensors

lastup

Time stamp of the most recent Up status of the sensor

sensors

lastdown

Time stamp of the most recent Down status of the sensor

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 the associated device and the associated group separated by a forward slash (/)

sensors

devices

notifiesx

Number of each trigger type defined for the object

probes

groups

devices

sensors

intervalx

Either Inherited or the current interval setting of the object

probes

groups

devices

sensors

accessrights

Access rights of the current user for the sensor tree object

all objects (except for user), for example:

probes

groups

devices

sensors

dependency

Name of an associated dependency or Parent

probes

groups

devices

sensors

probegroupdevice

Partial object hierarchy with names of associated device, group, and probe separated by a forward slash (/).

i_round_blueThe output contains HTML.

i_round_blueprobegroupdevice is not available in the CSV format.

i_round_blueFor the complete object hierarchy, use probe, group, device instead.

sensor

device

group

probe

status

For sensor tree objects: status of the object (0=None, 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 the sensor tree object (for example, last error of the sensor) or the history entry, log entry, ticket subject

sensors

devices

groups

probes

messages

tickets

ticketdata

history

priority

Priority setting of the sensor tree object or the priority of the 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, you must use lastvalue_ to automatically display volumes and speed.

sensors

channels

upsens

Number of sensors in the Up status

i_round_bluePRTG only counts the sensor itself or sensors below the object in the hierarchy.

all sensors

devices

groups

probes

downsens

Number of sensors in the Down status

i_round_bluePRTG only counts the sensor itself or sensors below the object in the hierarchy.

all sensors

devices

groups

probes

downacksens

Number of sensors in the Down (Acknowledged) status

i_round_bluePRTG only counts the sensor itself or sensors below the object in the hierarchy.

all sensors

devices

groups

probes

partialdownsens

Number of sensors in the Down (Partial) status

i_round_bluePRTG only counts the sensor itself or sensors below the object in the hierarchy.

all sensors

devices

groups

probes

warnsens

Number of sensors in the Warning status

i_round_bluePRTG only counts the sensor itself or sensors below the object in the hierarchy.

all sensors

devices

groups

probes

pausedsens

Number of sensors in the Paused status. This includes all Paused states ('paused by user', 'paused by dependency, 'paused by schedule', etc.).

all sensors

devices

groups

probes

unusualsens

Number of sensors in the Unusual status

i_round_bluePRTG only counts the sensor itself or sensors below the object in the hierarchy.

all sensors

devices

groups

probes

undefinedsens

Number of sensors in an undefined status, like None, Unknown, No Probe

i_round_bluePRTG only counts the sensor itself or sensors below the object in the hierarchy.

all sensors

devices

groups

probes

totalsens

Number of all sensors

i_round_bluePRTG only counts the sensor itself or sensors below the object in the hierarchy.

all sensors

devices

groups

probes

size

Performance impact of the sensor (1=Very Low, 2=Low, 3=Medium, 4=High, 5=Very High)

sensors

value

The channel value or the Toplist value

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

values

topdata

coverage

Sensor coverage of the time span in a value table.

values

favorite

An exclamation mark (!) if the sensor tree object is marked as favorite

sensors

devices

groups

probes

user

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

Time stamp or time span of the 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: Name of the associated schedule

For reports: Report generation schedule

probes

groups

devices

sensors

reports

period

Period of the report (day, week, etc.)

reports

email

Email address of the report

reports

template

Template used by the report

reports

lastrun

Time stamp of the last generation of a report

reports

nextrun

Time stamp of the next generation of a report

reports

size

Size of a stored report

size of a stored report

minigraph

Numeric 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

Subobjects 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 or devices in the probe or group

probes

groups

tickettype

Type of ticket: user, notification, todo

tickets

modifiedby

User who edited the ticket most recently

tickets

ticketdata

actions

Types of all ticket edits

ticketdata

content

Text of the ticket that was added with the last edit

ticketdata

channel

Number of channels with an ID greater than or equal to 0

sensors

_key, _value

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)

More

i_square_blueKNOWLEDGE BASE

Is there a list of log status values for the PRTG API?

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