Content Previous Next

PRTG Manual: Multiple Object Property or Status

<%NUMBERING1%>.<%NUMBERING2%>.<%NUMBERING3%> PRTG Manual: Multiple Object Property or Status

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

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

The 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.

Examples

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

/api/table.xml?content=sensortree

sensortree 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 , which most data tables have in the PRTG web interface. Navigate to the information that you want to use, click , 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.

For 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.

Example

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

Strings 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.

Some 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). JSON 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 For 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. For 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. For 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. Multiple 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) @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. Log tables with content=messages are always sorted by descending date.

Examples

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 (/). The output contains HTML. probegroupdevice is not available in the CSV format. For 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 PRTG 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 PRTG 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 PRTG 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 PRTG 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 PRTG 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 PRTG 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 PRTG only counts the sensor itself or sensors below the object in the hierarchy.	all sensors devices groups probes
totalsens	Number of all sensors PRTG 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)

KNOWLEDGE BASE

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

https://kb.paessler.com/en/topic/76501

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

https://kb.paessler.com/en/topic/593