Reports

GET /v6/reports Reports list

This endpoint returns a list of reports configured in ThousandEyes in the context of the user’s current account group. This endpoint requires the View Reports permission be assigned to the role of the user accessing this endpoint. Use this data to find a report in your account, which is then used in other endpoint to access aggregated data.

Parameters

  • format=json|xml optional, specifies the format of output requested. See Output Formats for more information
  • aid={aid} optional and requires the user to be assigned to the target account group, specifies the account group context of the request, obtained from the /account-groups endpoint. Specifying this parameter without the user being assigned to the target account will result in an error response. See Account group context for more information

Request

  • no request body

Example

$ curl https://api.thousandeyes.com/v6/reports.json \ -u noreply@thousandeyes.com:g351mw5xqhvkmh1vq6zfm51c62wyzib2

Response

Sends back an array of reports configured in the current account group. Each report contains the following fields:

Field NameData TypeNotes
reportIdstringunique Id of the report
reportNamestringname of the report
builtInboolean1 for built-in reports, 0 for user-created reports
apiLinksarray of apiLink objectsa list of links which can be followed to pull more information

HTTP/1.1 200 OK Server: nginx Date: Mon, 21 Nov 2016 16:04:24 GMT Content-Type: application/json;charset=UTF-8 Transfer-Encoding: chunked Connection: keep-alive Cache-Control: no-store X-Organization-Rate-Limit-Limit: 970 X-Organization-Rate-Limit-Remaining: 968 X-Organization-Rate-Limit-Reset: 1492076520 Strict-Transport-Security: max-age=31536000 X-Server-Name: 1-2

Body

{ "reports: [ { "apiLinks": [...], "builtIn": 1, "reportId": "2", "reportName": "ThousandEyes Built-in: HTTP Server" }, { "apiLinks": [...], "builtIn": 1, "reportId": "1", "reportName": "ThousandEyes Built-in: Network Layer" }, ... ] }

For error responses, see the response status codes documentation.

GET /v6/reports/{reportId} Report detail

This endpoint returns a list of widgets configured in reports configured in ThousandEyes. Seed this endpoint with a reportId found from the /reports endpoint. This endpoint requires the View Reports permission be assigned to the role of the user accessing this endpoint.

Parameters

  • format=json|xml optional, specifies the format of output requested. See Output Formats for more information
  • aid={aid} optional and requires the user to be assigned to the target account group, specifies the account group context of the request, obtained from the /account-groups endpoint. Specifying this parameter without the user being assigned to the target account will result in an error response. See Account group context for more information
  • {reportId} the ID of the report you’re interested in.

Request

  • no request body

Example

$ curl https://api.thousandeyes.com/v6/reports/590ca0db90b0357f7e8ae1ad.json \ -u noreply@thousandeyes.com:g351mw5xqhvkmh1vq6zfm51c62wyzib2

Response

Returns a list of widgets configured in the report. Each widget will show a list of data components shown in the widget. Each data component includes a metric, measure, and grouping information, as well as details around any embeddings which exist for the widget:

Field NameData TypeNotes
reportIdstringunique ID of the report
reportNamestringname of the report
builtInboolean1 for built-in reports, 0 for user-created reports
apiLinksarray of apiLink objectsa list of links which can be followed to pull more information
widgetsarrayan array of widget objects

Each widget object has the following fields:

Field NameData TypeNotes
titlestringwidget title
typestringwidget type; table, multi-metric-table, geomap, numbers, pie-chart, timeseries, stacked-areachart, box-and-whiskers, …
dataComponentsarrayarray of widget data components
embedUrlstringif widget is marked as embedded, embedUrl is provided

Each widget is comprised of one or more data components, fields represented by the following table:

Field NameData TypeNotes
dataComponentIdstringunique ID of the data component. Use this value to retrieve dataComponent values.
metricstringthe metric being tabulated in the report: defined by the layer, test type and metric.
measurestringstatistical measure shown, i.e. Minimum, Maximum, …
groupByarray of groupBy objectsarray of groupBy strings, i.e. Tests, Agents, …
filtersarray of filter objects(optional) where the widget is filtered, filters property is shown. Each filter object represents one selected item and contains filterProperty and filterValue properties. filterProperty can be Agents, Agent Groups, Tests, Monitors, etc. filterValue holds the Id of the property, i.e. test, agent, monitor Id.
fixedTimeSpannumber(optional) where widget timespan is different from report’s timespan, this parameter is set to number of seconds in the timespan

HTTP/1.1 200 OK Server: nginx Date: Mon, 21 Nov 2016 16:04:24 GMT Content-Type: application/json;charset=UTF-8 Transfer-Encoding: chunked Connection: keep-alive Cache-Control: no-store X-Organization-Rate-Limit-Limit: 970 X-Organization-Rate-Limit-Remaining: 968 X-Organization-Rate-Limit-Reset: 1492076520 Strict-Transport-Security: max-age=31536000 X-Server-Name: 1-2

Body

{ "reports": [ { "apiLinks": [...], "builtIn": 1, "reportId": "2", "reportName": "ThousandEyes Built-in: HTTP Server", "widgets": [ { "dataComponents": [ { "apiLinks": [...], "dataComponentId": "vlvb1", "description": "Average Availability", "groupBy": [], "measure": "Mean", "metric": "Web - HTTP Server \u2014 Availability" }, { "apiLinks": [...], "dataComponentId": "dyivi", "description": "Average Response Time", "groupBy": [], "measure": "Mean", "metric": "Web - HTTP Server \u2014 Response Time" }, ... ], "title": "HTTP Server Overview", "type": "numbers" }, { "dataComponents": [ { "apiLinks": [ { "href": "https://api.thousandeyes.com/v6/reports/590ca0db90b0357f7e8ae1ad/ynubv", "rel": "data" } ], "dataComponentId": "ynubv", "filters": [ { "filterProperty": "Tests", "filterValue": "817" }, { "filterProperty": "Tests", "filterValue": "818" } ], "groupBy": [ "Agents" ], "measure": "Mean", "metric": "Web - HTTP Server \u2014 Availability" } ], "title": "Overall Average Availability", "type": "timeseries" }, ... ] } ] }

For error responses, see the response status codes documentation.

GET /v6/reports/{reportId}/{dataComponentId} Report data

This endpoint returns actual metrics used in the generation of the reports shown. Unlike the metadata options, this endpoint accepts parameters for a time range shown in the data, which defaults to 7 days.

Parameters

  • format=json|xml optional, specifies the format of output requested. See Output Formats for more information
  • window=[0-9]+[smhdw]? specifies a window of time for the result set. See Time Ranges for more information.
  • from=YYYY-mm-ddTHH:MM:SS&to=YYYY-mm-ddTHH:MM:SS specifies an explicit start (and optionally, end) for your range of data. See Time Ranges for more information.
  • aid={aid} optional, changes the account group context of the current request. If an invalid account group ID is specified as a parameter, the response will come back as an HTTP/400 error.
  • {reportId} the ID of the report you’re interested in.
  • {dataComponentId} the ID of the data component for which to retrieve data.

Request

  • no request body

Example

$ curl https://api.thousandeyes.com/v6/reports/2/vlvb1.json \ -u noreply@thousandeyes.com:g351mw5xqhvkmh1vq6zfm51c62wyzib2

Response

Sends back a list of data elements associated with the report. The data components are aggregated by our services, then reported back in bins: each bin represents a point on the chart: the granularity of the points shown in the chart is based on the data range shown in the report. Bin sizes are based on the table below:

Report time rangeBin size
1 hour - 7 days5 minutes
7 days - 30 days1 hour
30 days - 50 days2 hours
50 days - 80 days4 hours
80 days - 93 days6 hours

If your data is grouped, a value will be shown for each data grouping for each bin.

Corresponding data is returned according to the following fields:

Field NameData TypeNotes
fromdateTimethe start of the data shown in the API output
todateTimeend of the data window shown in the API output
data.binIdintegercorresponds to the start time for the bin
data.countintegernumber of datapoints shown in the round
data.valuefloatvalue of the datapoint
data.groupsarray of group objectsthis corresponds to how the data is labelled in the widget. Match the groupProperty and groupId to retrieve the label as represented in the widget.
groupLabelMapsarray of groupLabelMap objectssee groupLabelMap fields below
groupLabelMap.groupPropertystringmatches the groupProperty listed in the data.groups object
groupLabelMap.groupLabelsarray of groupLabel objectssee individual fields below
groupLabel.groupIdintegerlookup value of the group
groupLabel.groupLabelstringvalue of the legend
binSizeintegerduration of each bin

HTTP/1.1 200 OK Server: nginx Date: Mon, 21 Nov 2016 16:04:24 GMT Content-Type: application/json;charset=UTF-8 Transfer-Encoding: chunked Connection: keep-alive Cache-Control: no-store X-Organization-Rate-Limit-Limit: 970 X-Organization-Rate-Limit-Remaining: 968 X-Organization-Rate-Limit-Reset: 1492076520 Strict-Transport-Security: max-age=31536000 X-Server-Name: 1-2

Body

{ "from": "2017-04-25 14:00:00", "to": "2017-05-02 14:00:00", "reportDataComponentData": { "binSize": 3600, "data": [ { "binId": 1492524000, "count": 5376, "value": 99.90699404761905 }, { "binId": 1493730000, "count": 5376, "value": 99.7953869047619 } ], "groupLabelMaps":[ { "groupProperty":"Tests", "groupLabels":[ { "groupId":"29697", "groupLabel":"http://jackli.design" }, { "groupId":"1580", "groupLabel":"OLD Periodic Failure Example" } ] } ], } }

For error responses, see the response status codes documentation.

POST /v6/reports/{reportId}/delete Deleting a report

Deletes the specified report in ThousandEyes, based on the reportId provided in the API request. Users with the Edit reports for all users in account group permission (Account Admin) can delete any report. Users with Edit own reports permission (Regular User) can only delete the reports they have created.

Parameters

  • format=json|xml optional, specifies the format of output requested. See Output Formats for more information
  • aid={aid} optional and requires the user to be assigned to the target account group, specifies the account group context of the request, obtained from the /account-groups endpoint. Specifying this parameter without the user being assigned to the target account will result in an error response. See Account group context for more information
  • {reportId} the ID of the report you would like to delete

Response

If the report is successfully deleted, an HTTP 204 NO CONTENT response will be returned. If user lacks the permissions to delete the report, an HTTP 401 UNAUTHORIZED response will be returned.

Response has no body.

Example

Please note, report deletion is not allowed on the Sandbox API account, and will not work if attempted. The following example is presented for documentation and reference purposes only.

$ curl https://api.thousandeyes.com/v6/reports/58c9437149b02d5410fd06cd/delete \ -d '' \ -H "Content-Type: application/json" \ -H "Accept: application/json" \ -u noreply@thousandeyes.com:g351mw5xqhvkmh1vq6zfm51c62wyzib2

HTTP/1.1 204 No Content Server: nginx Date: Wed, 15 Mar 2017 13:47:45 GMT Content-Type: application/json;charset=UTF-8 Connection: keep-alive Cache-Control: no-store X-Organization-Rate-Limit-Limit: 970 X-Organization-Rate-Limit-Remaining: 968 X-Organization-Rate-Limit-Reset: 1489585680 Strict-Transport-Security: max-age=31536000 X-Server-Name: 1-3

For error responses, see the response status codes documentation.

GET /v6/report-snapshots Report snapshots list

This endpoint returns a list of report snapshots configured in ThousandEyes in the context of the user’s current account group. This endpoint requires the View Reports permission be assigned to the role of the user accessing this endpoint. Use this data to find a report snapshot in your account, which is then used in other endpoint to access aggregated data.

Parameters

  • format=json|xml optional, specifies the format of output requested. See Output Formats for more information
  • aid={aid} optional and requires the user to be assigned to the target account group, specifies the account group context of the request, obtained from the /account-groups endpoint. Specifying this parameter without the user being assigned to the target account will result in an error response. See Account group context for more information

Request

  • no request body

Example

$ curl https://api.thousandeyes.com/v6/report-snapshots.json \ -u noreply@thousandeyes.com:g351mw5xqhvkmh1vq6zfm51c62wyzib2

Response

Sends back an array of report snapshots configured in the current account group. Each report snapshot object contains the following fields:

Field NameData TypeNotes
snapshotIdstringunique ID of the report snapshot
snapshotNamestringname of the report snapshot
createdDatedateTimethe date/time when report snapshot was created
scheduledboolean1 if report snapshot was generated from a schedule
sharedboolean1 if report snapshot is shared
reportobjectreport this report snapshot is based upon
report.reportIdstringunique ID of the report
report.reportNamestringname of the report
report.builtInboolean1 for built-in reports, 0 for user-created reports
report.apiLinksarray of apiLink objectsa list of links which can be followed to pull more information
timespan.startDatedateTimethe date/time of beginning of report snapshot
timespan.durationintegerduration of report snapshot in seconds
permalinkstringlink to report snapshot in ThousandEyes Application
apiLinksarray of apiLink objectsa list of links which can be followed to pull more information

HTTP/1.1 200 OK Server: nginx Date: Thu, 13 Apr 2017 09:38:58 GMT Content-Type: application/json;charset=UTF-8 Transfer-Encoding: chunked Connection: keep-alive Cache-Control: no-store X-Organization-Rate-Limit-Limit: 970 X-Organization-Rate-Limit-Remaining: 968 X-Organization-Rate-Limit-Reset: 1492076340 Strict-Transport-Security: max-age=31536000 X-Server-Name: 1-2

Body

{ "pages": { "current": 1 }, "reportSnapshots": [ { "apiLinks": [...], "createdDate": "2017-05-02 14:42:49", "permalink": "https://app.thousandeyes.com/reports/snapshots/60886ebb-2466-444d-bbd8-74d5ea1402d2?__a=75", "report": { "apiLinks": [...], "builtIn": 1, "reportId": "2", "reportName": "ThousandEyes Built-in: HTTP Server" }, "scheduled": 0, "shared": 0, "snapshotId": "60886ebb-2466-444d-bbd8-74d5ea1402d2", "snapshotName": "HTTP Server Report Snapshot", "timeSpan": { "duration": 604800, "startDate": "2017-03-15 00:00:00" } }, ... ] }

For error responses, see the response status codes documentation.

GET /v6/report-snapshots/{snapshotId} Report snapshot detail

This endpoint returns a list of widgets configured in reports configured in ThousandEyes. Seed this endpoint with a reportId found from the /reports endpoint. This endpoint requires the View Reports permission be assigned to the role of the user accessing this endpoint.

Parameters

  • format=json|xml optional, specifies the format of output requested. See Output Formats for more information
  • aid={aid} optional and requires the user to be assigned to the target account group, specifies the account group context of the request, obtained from the /account-groups endpoint. Specifying this parameter without the user being assigned to the target account will result in an error response. See Account group context for more information
  • {snapshotId} the ID of the report snapshot you’re interested in.

Request

  • no request body

Example

$ curl https://api.thousandeyes.com/v6/report-snapshots/60886ebb-2466-444d-bbd8-74d5ea1402d2.json \ -u noreply@thousandeyes.com:g351mw5xqhvkmh1vq6zfm51c62wyzib2

Response

Returns details information about report snapshot including the list and configuration of the widgets.

Field NameData TypeNotes
snapshotIdstringunique ID of the report snapshot
snapshotNamestringname of the report snapshot
createdDatedateTimethe date/time when report snapshot was created
scheduledboolean1 if report snapshot was generated from a schedule
sharedboolean1 if report snapshot is shared
reportobjectreport this report snapshot is based upon
report.reportIdstringunique ID of the report
report.reportNamestringname of the report
report.builtInboolean1 for built-in reports, 0 for user-created reports
report.apiLinksarray of apiLink objectsa list of links which can be followed to pull more information
timespan.startDatedateTimethe date/time of beginning of report snapshot
timespan.durationintegerduration of report snapshot in seconds
permalinkstringlink to report snapshot in ThousandEyes Application
apiLinksarray of apiLink objectsa list of links which can be followed to pull more information
widgetsarrayan array of widget objects

Each widget object has the following fields:

Field NameData TypeNotes
titlestringwidget title
typestringwidget type; table, multi-metric-table, geomap, numbers, pie-chart, timeseries, stacked-areachart, box-and-whiskers, …
dataComponentsarrayarray of widget data components
embedUrlstringif widget is marked as embedded, embedUrl is provided

Each widget is comprised of one or more data components, fields represented by the following table:

Field NameData TypeNotes
dataComponentIdstringunique ID of the data component
metricstringthe metric being tabulated in the report: defined by the layer, test type and metric.
measurestringstatistical measure shown, i.e. Minimum, Maximum, …
groupByarrayarray of groupBy strings, i.e. Tests, Agents, …
filtersarray of filter objects(optional) where the widget is filtered, filters property is shown. Each filter object represents one selected item and contains filterProperty and filterValue properties. filterProperty can be Agents, Agent Groups, Tests, Monitors, etc. filterValue holds the Id of the property, i.e. test, agent, monitor Id.
apiLinksarray of apiLink objectsa list of links which can be followed to pull more information

HTTP/1.1 200 OK Server: nginx Date: Thu, 13 Apr 2017 09:41:13 GMT Content-Type: application/json;charset=UTF-8 Transfer-Encoding: chunked Connection: keep-alive Cache-Control: no-store X-Organization-Rate-Limit-Limit: 970 X-Organization-Rate-Limit-Remaining: 969 X-Organization-Rate-Limit-Reset: 1492076520 Strict-Transport-Security: max-age=31536000 X-Server-Name: 1-2

Body

{ "reportSnapshots": [ { "apiLinks": [...], "createdDate": "2017-05-02 14:42:49", "permalink": "https://app.thousandeyes.com/reports/snapshots/60886ebb-2466-444d-bbd8-74d5ea1402d2?__a=75", "report": { "apiLinks": [...], "builtIn": 1, "reportId": "2", "reportName": "ThousandEyes Built-in: HTTP Server" }, "scheduled": 0, "shared": 0, "snapshotId": "60886ebb-2466-444d-bbd8-74d5ea1402d2", "snapshotName": "HTTP Server Report Snapshot", "timeSpan": { "duration": 604800, "startDate": "2017-03-15 00:00:00" }, "widgets": [ { "dataComponents": [ { "apiLinks": [...], "dataComponentId": "59089917755cb04ee9944e44", "description": "Average Availability", "groupBy": [], "measure": "Mean", "metric": "Web - HTTP Server \u2014 Availability" }, { "apiLinks": [...], "dataComponentId": "59089ae6755cb04ee977703b", "description": "Average Response Time", "groupBy": [], "measure": "Mean", "metric": "Web - HTTP Server \u2014 Response Time" }, ... ], "title": "HTTP Server Overview", "type": "numbers" }, { "dataComponents": [ { "apiLinks": [...], "dataComponentId": "590897e4755cb04ee9776f5b", "groupBy": [], "measure": "Mean", "metric": "Web - HTTP Server \u2014 Availability" } ], "title": "Overall Average Availability", "type": "timeseries" }, ... ] } ] }

For error responses, see the response status codes documentation.

GET /v6/report-snapshots/{snapshotId}/{dataComponentId} Report snapshot data

This endpoint returns actual metrics used in the generation of the report snapshot shown.

Parameters

  • format=json|xml optional, specifies the format of output requested. See Output Formats for more information
  • aid={aid} optional, changes the account group context of the current request. If an invalid account group ID is specified as a parameter, the response will come back as an HTTP/400 error.
  • {snapshotId} the ID of the report snapshot you’re interested in.
  • {dataComponentId} the ID of the data component for which to retrieve data.

Request

  • no request body

Example

$ curl https://api.thousandeyes.com/v6/report-snapshots/60886ebb-2466-444d-bbd8-74d5ea1402d2/59089917755cb04ee9944e44.json \ -u noreply@thousandeyes.com:g351mw5xqhvkmh1vq6zfm51c62wyzib2

Response

Sends back a list of data elements associated with the report snapshot. The data components are aggregated by our services, then reported back in bins: each bin represents a point on the chart: the granularity of the points shown in the chart is based on the data range shown in the report snapshot. Bin sizes are based on the table below:

Report time rangeBin size
1 hour - 7 days5 minutes
7 days - 30 days1 hour
30 days - 50 days2 hours
50 days - 80 days4 hours
80 days - 93 days6 hours

If your data is grouped, a value will be shown for each data grouping for each bin.

Corresponding data is returned according to the following fields:

Field NameData TypeNotes
fromdateTimethe start of the data shown in the API output
todateTimeend of the data window shown in the API output
reportDataComponentDataobjectobject represents report data component data

reportDataComponentData object has the following fields:

Field NameData TypeNotes
data.binIdintegercorresponds to the start time for the bin
data.countintegernumber of datapoints shown in the round
data.valuefloatvalue of the datapoint
data.groupsarray of group objectsthis corresponds to how the data is labelled in the widget. Match the groupProperty and groupId o retrieve the label as represented in the widget.
groupLabelMapsarray of groupLabelMap objectssee groupLabelMap fields below
groupLabelMap.groupPropertystringmatches the groupProperty listed in the data.groups object
groupLabelMap.groupLabelsarray of groupLabel objectssee individual fields below
groupLabel.groupIdintegerlookup value of the group
groupLabel.groupLabelstringvalue of the legend
binSizeintegerduration of each bin

HTTP/1.1 200 OK Server: nginx Date: Thu, 13 Apr 2017 14:29:51 GMT Content-Type: application/json;charset=UTF-8 Transfer-Encoding: chunked Connection: keep-alive Cache-Control: no-store X-Organization-Rate-Limit-Limit: 970 X-Organization-Rate-Limit-Remaining: 969 X-Organization-Rate-Limit-Reset: 1492093800 Strict-Transport-Security: max-age=31536000 X-Server-Name: 1-2

Body

{ "from": "2017-03-15 00:00:00", "to": "2017-03-22 00:00:00", "reportDataComponentData": { "binSize": 3600, "data": [ { "binId": 1492002000, "count": 10042, "groups": [ { "groupProperty": "Continents", "groupValue": "APNIC" } ], "value": 4236.95 }, { "binId": 1492002000, "count": 16112, "groups": [ { "groupProperty": "Continents", "groupValue": "ARIN" } ], "value": 3801.1 }, ... ], "groupLabelMaps": [] }, }

For error responses, see the response status codes documentation.

POST /v6/report-snapshots/{snapshotId}/delete Deleting a report snapshot

Deletes the specified report snapshot in ThousandEyes, based on the snapshotId provided in the API request. Users with the Edit reports for all users in account group permission (Account Admin) can delete any report snapshot. Users with Edit own reports permission (Regular User) can only delete the report snapshots for reports they have created.

Parameters

  • format=json|xml optional, specifies the format of output requested. See Output Formats for more information
  • aid={aid} optional and requires the user to be assigned to the target account group, specifies the account group context of the request, obtained from the /account-groups endpoint. Specifying this parameter without the user being assigned to the target account will result in an error response. See Account group context for more information
  • {snapshotId} the ID of the report snapshot you would like to delete

Response

If the report snapshot is successfully deleted, an HTTP 204 NO CONTENT response will be returned. If user lacks the permissions to delete the report, an HTTP 401 UNAUTHORIZED response will be returned.

Response has no body.

Example

Please note, report snapshot deletion is not allowed on the Sandbox API account, and will not work if attempted. The following example is presented for documentation and reference purposes only.

$ curl https://api.thousandeyes.com/v6/report-snapshot/2bee381c-cc97-49f4-9ef5-1013c97f4124/delete \ -d '' \ -H "Content-Type: application/json" \ -H "Accept: application/json" \ -u noreply@thousandeyes.com:g351mw5xqhvkmh1vq6zfm51c62wyzib2

HTTP/1.1 204 No Content Server: nginx Date: Thu, 13 Apr 2017 09:43:28 GMT Content-Type: application/json;charset=UTF-8 Transfer-Encoding: chunked Connection: keep-alive Cache-Control: no-store X-Organization-Rate-Limit-Limit: 970 X-Organization-Rate-Limit-Remaining: 968 X-Organization-Rate-Limit-Reset: 1492076520 Strict-Transport-Security: max-age=31536000 X-Server-Name: 1-2

For error responses, see the response status codes documentation.