Report API

AlertSite provides a programming interface for gathering report data for monitored devices. Of the Reports available from the Performance Reports section of the Console, the Report API has been implemented for the following reports:

  • Detail Report
  • SLA Detail Report
  • Transaction Detail Report
  • Page Objects Report
  • Site Status Report
  • Outage Report
  • Usage Report

The Report API interface communicates with data sources, called endpoints, that correspond to the different report types. The reports require different selection parameters for data collection requests, depending on the type of report. All requests are sent over a secure https connection.

The AlertSite Report Center in the Console returns a pre-formatted URL for the Site Detail Report, Site Status Report, SLA Detail Report, and Page Objects Report. See Report Center API Command below for more information.

There are 2 versions of the API, Version 1 and Version 2. This document details each report API request, which parameters are accepted, and whether they are required or optional, for each API version.

API Commands

Each request uses the following format:

https://www.alertsite.com/report-api/{endpoint}/{customer_id}?{report_parameters}

where {endpoint} is one of:

Endpoint Description
detail Detail Report
objects Fullpage Objects Report (individual http objects)
outage Outage Report
sitestatus Site Status Report
sla SLA Detail Report
txndetail Transaction Detail Report (to Event level)
usage Usage Report

The endpoint corresponds to reports available in the AlertSite Console Report Center.

The txndetail endpoint sends all data about specified transactions, but does not include individual HTTP objects. The separate objects endpoint is provided for that purpose (note that objects data latency is very high compared to txndetail data).

The {customer_id} is found in the AccountManage Account screen in the upper left, just below the Company name.

The two versions of the API, Version 1 and Version 2, are referenced as report parameter api_version=<n>. The default is api_version=1. In order to use Version 2, you must include api_version=2 as a parameter.

Report parameters are delimited by '&', for example:

...?obj_device=114349&obj_location=63&rdate=LastWeek&sort_order=desc

In all cases, a date parameter is required, either rdate OR start_date+end_date.

The list of all current location IDs are available on the Monitoring Locations page.

The sections below describe the parameters that are valid for each endpoint. Examples follow each Report Parameters table.


Detail Endpoint

VERSION 1 Report Parameters:

Parameter Description Value Required
obj_device Device Identifier Device Id Yes
obj_location Location ID Number comma-separated list of location ids Yes
rdate
from+to
Relative Date
Date Range
See below
YYYY-MM-DD [optionally +HH:MM:SS]
Yes
showrecs Data Filters err=Show Only Errors
ok=Show Only Successes
No
sort_order Sort Order asc=Ascending
desc=Descending
No

Example: This URL returns Detail data for customer ID C99999, device ID 83931, from Location ID 20 (Atlanta), for Today:

https://www.alertsite.com/report-api/detail/C99999?obj_device=83931&
obj_location=20&rdate=Today 

Example: This URL returns Detail data for customer ID C99999, device ID 76981, from all three monitoring locations, Atlanta (Location ID 20), Boston (Location ID 72) and Chicago (50), for January 20, 2013 through January 22, 2013:

https://www.alertsite.com/report-api/detail/C99999?obj_device=76981&
obj_location=20,72,50&from=2013-01-20+00:00:00&to=2013-01-22+23:59:59

VERSION 2 Report Parameters:

Parameter Description Value Required
api_version API Version # 2 Yes
devices Device Identifier if omitted, all applicable devices, or
a comma-separated list of device ids
No
dimensions Grouping Dimensional filter on results, aggregated by what was requested
See below
No
dow Day of Week Numeric days of week
0=Sunday (comma-separated list)
No
format Output format xml (default), json No
hours Hours of Day Numeric hours of day
0=Midnight (comma-separated list)
No
locations Location ID Number If omitted, all locations, or
a comma-separated list of location ids
No
max_results Maximum results How many results are allowed to be returned No
rdate
start_date+end_date
Relative Date
Date Range
See below
YYYY-MM-DD+HH:MM:SS
Yes
showrecs Data Filters err=Show Only Errors
ok=Show Only Successes
No
ignore_ctl_recs Ignore control records 0 (default) = include control records that indicate the start of a scheduled set of tests (see below).
1 = exclude control records.
No

Example: This URL returns Detail data for customer ID C99999, device ID 83931, from Location ID 20 (Atlanta), for Today:

https://www.alertsite.com/report-api/detail/C99999?devices=83931&
locations=20&rdate=Today&api_version=2

Example: This URL returns Detail data for customer ID C99999, device IDs 76981 and 94332, from all monitoring locations, for January 20, 2013 through January 22, 2013:

https://www.alertsite.com/report-api/detail/C99999?devices=76981,94332&
start_date=2013-01-20+00:00:00&end_date=2013-01-22+23:59:59&api_version=2

Example: This URL returns Detail data for customer ID C99999, device ID 83931, from all monitoring locations, for Today, grouped by locations and the hour of day:

https://www.alertsite.com/report-api/detail/C99999?devices=83931&rdate=Today&
&api_version=2&dimensions=locations,hour

Control Records

If testing from multiple locations at a time, test results that are part of the same set have the same value for ctl_devlog.

Additionally, the results from Detail Endpoint v2 may include special control records that indicate the start of a scheduled set of tests. These records have status_warning=9085 and http_status="Monitoring locations started", and are included for devices that use any of the following:

  • rotated locations,
  • Round Robin monitoring mode,
  • SLA (MultiPOP) monitoring mode.

You can use the control records to present the data grouped by test sets, for example:

  • Test started at 10:00 AM (status_warning=9085, ctl_devlog=145-01)
    • Atlanta at 10:00 AM (ctl_devlog=145-01)
    • Boston at 10:00 AM (ctl_devlog=145-01)
  • Test started at 10:05 AM (status_warning=9085, ctl_devlog=145-02)
    • Fort Lauderdale at 10:05 AM (ctl_devlog=145-02)
    • Portland at 10:05 AM (ctl_devlog=145-02)

If you do not want control records in the response, add the ignore_ctl_recs=1 parameter to the API request.

Back to top


Objects Endpoint

NOTE: A short time period is highly recommended when using the objects data source.

VERSION 1 Report Parameters:

Parameter Description Value Required
obj_device Device Identifier comma-separated list of device ids Yes
obj_location Location ID Number comma-separated list of location ids Yes
rdate
from+to
Relative Date
Date Range
See below
YYYY-MM-DD [optionally +HH:MM:SS]
Yes
sort_order Sort Order asc=Ascending
desc=Descending
No
step_seqno Transaction Step and Step Number <step description>::SEQ::<step number> Yes

Example: This URL produces Page Objects data for customer ID C99999, using device ID 114349 from Austin (Location ID 63), displaying data for the objects in the second transaction step Second Step for January 5, 2013 from 1:00 AM to 1:05 AM:

https://www.alertsite.com/report-api/objects/C99999?obj_device=114349&obj_location=63&
step_seqno=Second%20Step::SEQ::2&from=2013-01-05+01:00:00&to=2013-01-05+01:05:00

NOTE: The %20 between Second and Step represents a URL-encoded space between the two words and is required.

VERSION 2 Report Parameters:

Parameter Description Value Required
api_version API Version # 2 Yes
devices Device Identifier if omitted, all applicable devices, or
a comma-separated list of device ids
No
dimensions Grouping Dimensional filter on results, aggregated by what was requested
See below
No
dow Day of Week Numeric days of week, 0=Sunday (comma-separated list) No
format Output format xml (default), json No
hours Hours of Day Numeric hours of day, 0=Midnight (comma-separated list) No
locations Location ID Number if omitted, all locations, or
a comma-separated list of location ids
No
max_results Maximum results How many results are allowed to be returned No
rdate
start_date+end_date
Relative Date
Date Range
See below
YYYY-MM-DD+HH:MM:SS
Yes
showrecs Data Filters err=Show Only Errors
ok=Show Only Successes
No
seqno Transaction Step Number <step number> No

Example: This URL produces Page Objects data for customer ID C99999, using device ID 114349 from Austin (Location ID 63), displaying data for the objects in the second transaction step for January 5, 2013 from 1:00 AM to 1:05 AM:

https://www.alertsite.com/report-api/objects/C99999?devices=114349&location=63&
step_seqno=2&start_date=2013-01-05+01:00:00&end_date=2013-01-05+01:05:00&api_version=2

Example: This URL produces the same Page Objects data above, but for all locations and steps::

https://www.alertsite.com/report-api/objects/C99999?devices=114349&
start_date=2013-01-05+01:00:00&end_date=2013-01-05+01:05:00&api_version=2

Back to top


Outage Endpoint

This endpoint is valid for Version 2 only.

VERSION 2 Report Parameters:

Parameter Description Value Required
devices Device Identifier if omitted, all applicable devices, or
a comma-separated list of device ids
No
format Output format json No
rdate
start_date+end_date
Relative Date
Date Range
See below
YYYY-MM-DD+HH:MM:SS
Yes

Example: This URL returns the Outage data for customer ID C99999 for all devices from all locations for Last Month:

https://www.alertsite.com/report-api/outage/C99999?&rdate=LastMonth

Back to top


Sitestatus Endpoint

This endpoint is valid for Version 1 only.

VERSION 1 Report Parameters:

Parameter Description Value Required
obj_device Device Identifier Comma-separated list of device IDs.
Leave empty to include all devices.
Yes
rdate Relative Date Now Yes
sitesonly Device Filter 1=include only Sites/Servers
0=include all devices
No
txnonly Device Filter 1=include only DéjàClick and API devices
0=include all devices
No
serversonly Device Filter 1=include only ServerAgent devices
0=include all devices
No
showrecs Data Filters err=Show only errors
ok=Show only successes
No
sort_order Sort Order asc=Ascending
desc=Descending
No

Example: This URL returns the Site Status data for all DéjàClick and API transactions. All locations are automatically included. Only rdate Now is valid:

https://www.alertsite.com/report-api/sitestatus/C99999?obj_device=&rdate=Now&txnonly=1

Back to top


SLA Endpoint

This endpoint is valid for Version 1 only.

VERSION 1 Report Parameters:

Parameter Description Value Required
obj_device Device Identifier device id Yes
location Location ID Number comma-separated list of location ids Yes
rdate
from+to
Relative Date
Date Range
See below
YYYY-MM-DD [optionally +HH:MM:SS]
Yes
sort_order Sort Order asc=Ascending
desc=Descending
No

Note: SLA Detail Report supports only one device per API call.

Example: This URL returns the SLA Detail data for customer ID C99999, for device ID 130705, from all 3 monitoring locations, Charlotte, Boston, and Austin (Location IDs 22,63,72), for LastWeek:

https://www.alertsite.com/report-api/sla/C99999?obj_device=130705&location=22,63,72&rdate=LastWeek 

Back to top


Txndetail Endpoint

This endpoint is valid for Version 2 only.

VERSION 2 Report Parameters:

Parameter Description Value Required
devices Device Identifier none=all applicable devices, or
a comma-separated list of device ids
No
dow Day of Week Numeric days of week, 0=Sunday (comma-separated list) No
format Output format To get JSON data, use format=json.
To get XML data, do not include format in the URL.
No
api_version API version To get JSON data, use api_version=2.
To get XML data, do not include api_version in the URL.
No
hours Hours of Day Numeric hours of day, 0=Midnight (comma-separated list) No
locations Location ID Number none=all locations, or
a comma-separated list of location ids
No
max_results Maximum results How many results are allowed to be returned No
rdate
start_date+end_date
Relative Date
Date Range
See below
YYYY-MM-DD+HH:MM:SS
Yes

Example: This URL returns the Transaction Detail data for all devices from Los Angeles (Location ID 42) for Yesterday, in the JSON format:

https://www.alertsite.com/report-api/txndetail/C99999?&locations=42&rdate=Yesterday&api_version=2&format=json

This call returns the same data in the XML format:

https://www.alertsite.com/report-api/txndetail/C99999?&locations=42&rdate=Yesterday

Back to top


Usage Endpoint

This endpoint is valid for Version 2 only.

VERSION 2 Report Parameters:

Parameter Description Value Required
devices Device Identifier if omitted, all applicable devices, or
a comma-separated list of device ids
No
dimensions Grouping Dimensional filter on results, aggregated by what was requested
See below
No
dow Day of Week Numeric days of week, 0=Sunday (comma-separated list) No
format Output format xml (default), json No
hours Hours of Day Numeric hours of day, 0=Midnight (comma-separated list) No
locations Location ID Number if omitted, all locations, or
a comma-separated list of location ids
No
rdate
start_date+end_date
Relative Date
Date Range
See below
YYYY-MM-DD+HH:MM:SS
Yes

Example: This URL returns the Usage data for customer ID C99999 for all devices from all locations for This Quarter:

https://www.alertsite.com/report-api/usage/C99999?&rdate=ThisQuarter&api_version=2

By default, the Usage report is grouped by device.


Available Relative Date Ranges (rdate parameter)

LastOneHour Last 1 Hour
LastTwoHours Last 2 Hours
LastFourHours Last 4 Hours
LastEightHours Last 8 Hours
LastTwelveHours Last 12 Hours
LastTwentyFourHours Last 24 Hours
LastFortyEightHours Last 48 Hours
Today Today
Yesterday Yesterday
LastTwoDays Last 2 Days
LastThreeDays Last 3 Days
LastSevenDays Last 7 Days
LastEightDays Last 8 Days
ThisWeek This Week (beginning Sunday)
ThisMonth This Month
LastMonth Last Month
LastWeek Last Week (beginning Sunday)
LastBizWeek Last Business Week
Now Now (Site Status report only)

NOTE: When using the objects endpoint, data pulls should be limited to less than 1 hour due to excessive data load.


Dimensions

Valid dimensions for all reports except Usage, which can be a comma-separated list:

device By Monitor Device
location By Monitor Location
month By Month
week By Week (Starts Sunday)
bizweek By Week (Starts Monday)
dayofweek By Day of Week
day By Date
dayofmonth By Day of Month
hour By Hour of day

Valid dimensions for Usage report, which can be a comma-separated list (NOTE: default is device if no dimensions are specified):

device By Monitor Device
location By Monitor Location
month By Month
week By Week (Starts Sunday)
bizweek By Week (Starts Monday)
dayofweek By Day of Week
day By Date
year By Year

Back to top


Report Center API Command

The Report Center in the AlertSite Console returns a pre-formatted URL for the following reports:

  • Detail
  • Site Status
  • SLA Detail
  • Page Objects

After generating one of these reports from the Performance Reports screen, the Report Options page will include the link Report API - generate report externally. Click this link to bring up a dialog window with the command to run the report via the Report API.

The example below shows the general syntax of the API command using the program wget, but similar programs can also be used, as long as the expected parameters are included:

wget -O test.xml --http-user=ACCOUNT_USERNAME --http-passwd=ACCOUNT_PASSWORD
'https://www.alertsite.com/report-api/detail/CUSTID?obj_device=OBJDEVICE&location=LOCATION
&rdate=DATERANGE&showrecs=SHOWRECS&showsubaccounts=SHOWSUBACCOUNTS&sort_order=ORDER'

The https: command within single quotes must appear as a single line with no spaces.

All the parameters in the URL above, except ACCOUNT_PASSWORD, will be provided once you run the report. ACCOUNT_USERNAME and ACCOUNT_PASSWORD in the command line above are your AlertSite account login ID and password. Any program used to access the URL will need to authenticate with the account login ID and password.

You can manually modify the following parameters:

  • locations
  • rdate
  • showrecs
  • showsubaccounts
  • sort_order

The alternative method to generate this XML report provided by Report Options shows the same URL that can be accessed directly from a browser:

https://www.alertsite.com/report-api/detail/CUSTID?obj_device=OBJDEVICE&locations=LOCATION&rdate=DATERANGE&
showrecs=SHOWRECS&sort_order=ORDER

The command must appear as a single line with no spaces.

Back to top

© 2016 SmartBear Software --
Syndicate this site RSSATOM