Reports

GET /v7/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

  • 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/v7/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
titlestringtitle of the report
descriptionstringdescription of the report
isBuiltInbooleantrue for built-in reports, false for user-created reports
accountIdintegerID of the account that the report belongs to
createdByintegerID of the user that created the report
modifiedByintegerID of the user that last modified the report
modifiedDatedateTimethe date/time when the report was last modified
isDefaultForUserbooleantrue if this report is the default for the user, false otherwise
isDefaultForAccountbooleantrue if this report is the default for the account group, false otherwise
apiLinksarray of apiLink objectsa list of links which can be followed to pull more information

HTTP/1.1 200 OK Server: nginx Date: Mon, 03 Sep 2019 18:00:00 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

[ { "reportId": "1", "title": "HTTP Server Widgets", "isBuiltIn": false, "accountId": 1, "createdBy": 1, "isDefaultForUser": false, "isDefaultForAccount": false, "apiLinks": [...] }, ... ]

For error responses, see the response status codes documentation.

GET /v7/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

  • 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/v7/reports/1.json \ -u noreply@thousandeyes.com:g351mw5xqhvkmh1vq6zfm51c62wyzib2

Response

Returns report metadata information and associated widget list. 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
titlestringtitle of the report
createdByintegerID of the user who created the report, as returned by the /v7/users API endpoint
modifiedByintegerID of the user who last modified the report, as returned by the /v7/users API endpoint
modifiedDatestringYYYY-MM-DD HH:mm:ss formatted date of last report modification time, shown in UTC
descriptionstringdescription of the report
isBuiltInbooleantrue for built-in reports, false for user-created reports
accountIdintegerID of the account that the report belongs to
isDefaultForUserbooleantrue if this report is the default for the user, false otherwise
isDefaultForAccountbooleantrue if this report is the default for the account group, false otherwise
widgetsarrayan array of widget objects
apiLinksarray of apiLink objectsa list of links which can be followed to pull more information

Each widget object has the following common fields (Except Number Widget):

Field NameData TypeNotes
idstringunique widget identifier inside the report
typestringwidget type: Table, Multi Metric Table, Map, Number, Pie Chart, Time Series: Line, Time Series: Stacked Area, Box and Whiskers, Bar Chart: Stacked, Bar Chart: Grouped
visualModestring(optional, defaults to Full) Visual mode in the UI: Full or Half Screen
fixedTimespanstring(optional) fixed timespan to do aggregation in seconds
titlestring(optional, defaults to widget type string) widget title
dataSourcestringdata source of widget
metricGroupstringmetric group of widget as it appears in the UI. Note: May not be required in some cases
metricstringmetric of widget
directionstringdirection of agent to agent metric (Required for some metrics)
measureobjectmeasure configuration of the widget
isEmbeddedbooleantrue if widget is marked as embedded, false otherwise
embedUrlstringif widget is marked as embedded, embedUrl is provided
filtersarray of filter mappings(optional) where the widget is filtered, filters property is shown. Each filter mapping will map a filter name to a list of filtered values. Filter keys can be Agents, Agent Groups, Tests, Monitors, etc. The list for each key holds the Ids of the property, i.e. test ids, agent ids, etc.
apiLinkstringlink to the data of the widget

Each widget object will have some of these fields, depending on the widget type as they appear in the UI.

Field NameData TypeNotes
groupBystringProperty name to group by
rowGroupBystringProperty name to group by on the rows
columnGroupBystringProperty name to group by on the columns
axisGroupBystringProperty name to group by on the axis
sortBystringProperty to sort by: Value or Alphabetical. Exception: Multi-metric table widget
sortDirectionstringDirection to sort by: Ascending or Descending
minScalefloat(optional) minimum scale configured in the widget
maxScalefloat(optional) maximum scale configured in the widget
isGeoMapPerTestboolean(optional) show only one test in each map for the Map widget
limitinteger(optional) limit configured in the widget
showLabelsboolean(optional, defaults to false) true if show labels checkbox is checked, false otherwise
isHorizontalBarChartboolean(optional, defaults to false) true if direction of barchart is horizontal, false otherwise
compareToPreviousValueboolean(optional, defaults to false) Compare next value with previous value
multiMetricColumnsarray of multrimetric column objectsarray of multimetric column objects only applicable to multimetric column widget
numberCardsarray of card objectsarray of card objects only applicable to number widget
showTimeseriesOverallBaselineboolean(optional, defaults to false) Should show baseline. Only applicable to timeseries widget
isTimeseriesOneChartPerLineboolean(optional, defaults to false) Should show only one line for every timeseries chart. Only applicable to the timeseries widget.

Each measure object has the following fields:

Field NameData TypeNotes
typestringmeasure type; Maximum, Mean, Median, Minimum, nth Percentile, Standard Deviation
percentileValuefloat(only for type nth Percentile) Percentile value

Each multimetric column object has the following fields:

Field NameData TypeNotes
idstringunique widget identifier inside the report
dataSourcestringdata source of widget
metricGroupstringmetric group of widget as it appears in the UI. Note: May not be required in some cases
metricstringmetric of widget
measureobjectmeasure configuration of the widget

Each card object has the following fields:

Field NameData TypeNotes
idstringunique widget identifier inside the report
descriptionstringdescription of the card
dataSourcestringdata source of widget
metricGroupstringmetric group of widget as it appears in the UI. Note: May not be required in some cases
metricstringmetric of widget
measureobjectmeasure configuration of the widget
compareToPreviousValueboolean(optional, defaults to false) Compare current value with previous value
fixedTimespanstring(optional) fixed timespan to do aggregation in seconds
minScalestring(optional) minimum scale configured in the widget
maxScalestring(optional) maximum scale configured in the widget
filtersarray of filter mappings(optional) where the widget is filtered, filters property is shown. Each filter mapping will map a filter name to a list of filtered values. Filter keys can be Agents, Agent Groups, Tests, Monitors, etc. The list for each key holds the Ids of the property, i.e. test ids, agent ids, etc.

HTTP/1.1 200 OK Server: nginx Date: Mon, 03 Sep 2019 18:00:00 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

{ "reportId": "1", "title": "API Report", "isBuiltIn": false, "accountId": 1, "createdBy": 2, "modifiedBy": 3, "modifiedDate": "2019-09-03 18:00:00", "isDefaultForUser": true, "isDefaultForAccount": false, "widgets": [ { "id": "abcd1", "type": "Multi Metric Table", "title": "Multi Metric Table", "visualMode": "Full", "apiLink": "https://api.thousandeyes.com/v7/reports/1/abcd1", "rowGroupBy": "Devices", "sortBy": "Default (Devices)", "sortDirection": "Ascending", "multiMetricColumns": [ { "id": "abcd2", "dataSource": "Devices", "metric": "Availability", "measure": { "type": "% Active" } }, { "id": "abcd3", "dataSource": "Devices", "metric": "Availability", "measure": { "type": "% Inactive" } } ] }, { "id": "zyxwb", "type": "Map", "title": "Map: Default", "visualMode": "Full", "dataSource": "Cloud & Enterprise Agents", "metricGroup": "Network - Agent to Server", "metric": "Available Bandwidth", "measure": { "type": "Maximum" }, "filters": { "Tests": [ 12345 ] }, "apiLink": "https://api.thousandeyes.com/v7/reports/1/zyxwb", "groupBy": "Agents", "sortBy": "Value", "sortDirection": "Ascending" }, { "id": "jv9wo", "type": "Time Series: Line", "title": "Time Series: Asia Pacific", "visualMode": "Full", "embedUrl": "https://embed.thousandeyes.com/e/icqzjuhdah", "isEmbedded": true, "dataSource": "Cloud & Enterprise Agents", "metricGroup": "Network - Agent to Server", "metric": "Latency", "measure": { "type": "Maximum" }, "filters": { "Tests": [ 12345, 12346 ] }, "apiLink": "https://api.thousandeyes.com/v7/reports/1/jv9wo", "groupBy": "Tests", "isTimeseriesOneChartPerLine": false } ], "apiLinks": [ { "rel": "self", "href": "https://api.thousandeyes.com/v7/reports/1" }, { "rel": "snapshots", "href": "https://api.thousandeyes.com/v7/report-snapshots?reportId=1" } ] }

For error responses, see the response status codes documentation.

GET /v7/reports/{reportId}/{widgedId} Report widget 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

  • 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.
  • {widgetId} the ID of the widget for which to retrieve data.

Request

  • no request body

Example

$ curl https://api.thousandeyes.com/v7/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
dateFromdateTimethe start of the data shown in the API output
dateTodateTimeend of the data window shown in the API output
binSizeintegerduration of each bin
groupLabelsarray of group labelssee groupLabel fields below
data.pointsarray of data pointssee data point below
data.cardsarray of card data pointssee card data point below (Only used for Number Widget)
data.columnsarray of multimetric column pointssee multimetric column point below (Only used for Multi Metric Table Widget)
statusstringMessage for not fully configured widget or no data

Data Point fields:

Field NameData TypeNotes
timestampintegertimestamp of the aggregated data point
numberOfDataPointsintegernumber of test data points aggregated into the widget data point
valueintegeraggregated value
groupsarray of group property and valuethis corresponds to the groups used for the aggregation

Card Data Point fields:

Field NameData TypeNotes
cardIdintegerunique ID of card
dateFromdateTimethe start of the data shown in the API output
dateTodateTimeend of the data window shown in the API output
previousValuedoubleprevious value if compareToPreviousValue was set to true in configuration
binSizeintegerduration of each bin
timestampintegertimestamp of the aggregated point
numberOfDataPointsintegernumber of points aggregated into the datapoint
valueintegeraggregated value
statusstringMessage for not fully configured card or no data

Multri Metric Column Data Point fields:

Field NameData TypeNotes
columnIdintegerunique ID of column
binSizeintegerduration of each bin
statusstringMessage for not fully configured card or no data
pointsarray of Data PointList of data points

HTTP/1.1 200 OK Server: nginx Date: Mon, 02 Sep 2019 18:00:00 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

Number Card Widget

{ "groupLabels": [], "data": { "cards": [ { "cardId": "lrxxr", "dateFrom": "2019-08-28 18:00:00", "dateTo": "2019-09-04 18:00:00", "binSize": 3600, "timestamp": 1567616400, "numberOfDataPoints": 24192, "value": 100.0 } ] } }

Multi Metric Column Widget

{ "dateFrom": "2019-08-28 19:00:00", "dateTo": "2019-09-04 19:00:00", "groupLabels": [], "data": { "columns": [ { "columnId": "938to", "binSize": 3600, "points": [ { "timestamp": 1567620000, "numberOfDataPoints": 456189, "value": 100.0, "groups": [] } ] }, { "columnId": "qqd2w", "binSize": 3600, "points": [ { "timestamp": 1567620000, "numberOfDataPoints": 4863654, "value": 4715.388999999999, "groups": [] } ] } ] } }

Other widgets

{ "dateFrom": "2019-08-28 19:00:00", "dateTo": "2019-09-04 19:00:00", "groupLabels": [ { "groupProperty": "Agents", "groupLabels": [ { "groupId": "1", "groupLabel": "Singapore" } ] } ], "binSize": 3600, "data": { "points": [ { "timestamp": 1567620000, "numberOfDataPoints": 23304, "value": 100.00000833068279, "groups": [ { "groupProperty": "Agents", "groupValue": "1" } ] } ] } }

For error responses, see the response status codes documentation.

POST /v7/reports/create Creating a report

This endpoint creates a new report for the account group that the user belongs to. This endpoint requires the Edit Reports permission be assigned to the role of the user accessing this endpoint.

Parameters

  • 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

A Report object with or without Widgets. See Report List for reference.

Example

$ curl https://api.thousandeyes.com/v7/reports/create \ -d '{ "title": "HTTP Server Widgets" }' \ -H "Content-Type: application/json" \ -H "Accept: application/json" \ -u noreply@thousandeyes.com:g351mw5xqhvkmh1vq6zfm51c62wyzib2

Response

Sends back the created report configured in the current account group. Each report contains the following fields:

Field NameData TypeNotes
reportIdstringunique ID of the report
titlestringtitle of the report
isBuiltInbooleantrue for built-in reports, false for user-created reports
accountIdintegerID of the account that the report belongs to
createdByintegerID of the user that created the report
modifiedDatedateTimethe date/time when the report was last modified
isDefaultForUserbooleantrue if this report is the default for the user, false otherwise
isDefaultForAccountbooleantrue if this report is the default for the account group, false otherwise
widgetsarray of widget objectsan array of widget objects
apiLinksarray of apiLink objectsa list of links which can be followed to pull more information

The user can specify custom widgetIds if they prefer to do so. These IDs have to match a 5 characters alphanumeric string and be unique across all widgets in the report. Alternatively, the widget Ids will be generated for them.

HTTP/1.1 200 OK Server: nginx Date: Mon, 03 Sep 2019 18:00:00 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

[ { "reportId": "1", "title": "HTTP Server Widgets", "isBuiltIn": false, "accountId": 1, "createdBy": 1, "isDefaultForUser": false, "isDefaultForAccount": false, "widgets": [...], "apiLinks": [...] }, ... ]

For error responses, see the response status codes documentation.

POST /v7/reports/{reportId}/update Updating a report

This endpoint updates an existing report for the account group that the user belongs to. This endpoint requires the Update Reports permission be assigned to the role of the user accessing this endpoint.

Parameters

  • 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

A Report object with or without Widgets. See Report List for reference.

Example

$ curl https://api.thousandeyes.com/v7/reports/1/update \ -d '{ "title": "New Report Updated" }' \ -H "Content-Type: application/json" \ -H "Accept: application/json" \ -u noreply@thousandeyes.com:g351mw5xqhvkmh1vq6zfm51c62wyzib2

Response

Sends back the updated report. Each report contains the following fields:

Field NameData TypeNotes
reportIdstringunique ID of the report
titlestringtitle of the report
isBuiltInbooleantrue for built-in reports, false for user-created reports
accountIdintegerID of the account that the report belongs to
createdByintegerID of the user that created the report
modifiedDatedateTimethe date/time when the report was last modified
isDefaultForUserbooleantrue if this report is the default for the user, false otherwise
isDefaultForAccountbooleantrue if this report is the default for the account group, false otherwise
widgetsarray of widget objectsan array of widget objects
apiLinksarray of apiLink objectsa list of links which can be followed to pull more information

The user can specify custom widgetIds if they prefer to do so. These IDs have to match a 5 characters alphanumeric string and be unique across all widgets in the report. Alternatively, the widget Ids will be generated for them.

HTTP/1.1 200 OK Server: nginx Date: Mon, 03 Sep 2019 18:00:00 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

[ { "reportId": "1", "title": "HTTP Server Widgets", "isBuiltIn": false, "accountId": 1, "createdBy": 1, "isDefaultForUser": false, "isDefaultForAccount": false, "widgets": [...], "apiLinks": [...] }, ... ]

For error responses, see the response status codes documentation.

POST /v7/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

  • 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/v7/reports/1/delete \ -u noreply@thousandeyes.com:g351mw5xqhvkmh1vq6zfm51c62wyzib2

HTTP/1.1 204 No Content Server: nginx Date: Mon, 03 Sep 2019 18:00:00 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 /v7/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 Snapshots 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

  • 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={reportId} optional parameter to filter the list of snapshots by report ID.

Request

  • no request body

Example

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

$ curl https://api.thousandeyes.com/v7/report-snapshots.json\?reportId\=1 \ -u noreply@thousandeyes.com:g351mw5xqhvkmh1vq6zfm51c62wyzib2

Response

Sends back an array of report snapshots configured in the current account group. The response has the following format:

Field NameData TypeNotes
pagespage objectObject containing a pagination link to the next page: next
reportSnapshotsarray of report snapshot objectsSee below

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
isScheduledbooleantrue if report snapshot was generated from a schedule
isSharedbooleantrue if report snapshot is shared
accountIdintegerID of the account group that the snapshot belongs to
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
reportobjectreport this report snapshot is based upon.
report.reportIdstringunique ID of the report
report.titlestringtitle of the report
report.isBuiltInbooleantrue for built-in reports, false for user-created reports
report.apiLinksarray of apiLink objectsa list of links which can be followed to pull more information
report.accountIdintegerID of the account group that the report belongs to
report.createdByintegerID of the user that created the report for which the snapshot was generated
report.modifiedByintegerID of the user that last modified the report at the time of snapshot creation
report.modifiedDatedateTimethe date/time when the report was last modified at the time the snapshot was created
permalinkstringlink to report snapshot in ThousandEyes Application

HTTP/1.1 200 OK Server: nginx Date: Mon, 02 Sep 2019 18:00:00 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": [...], "permalink": "https://api.thousandeyes.com/reports/snapshots/123__a=1", "createdDate": "2019-09-02 18:00:00", "report": { "apiLinks": [...], "reportId": "1", "title": "areport", "isBuiltIn": false, "accountId": 1, "createdBy": 2, "modifiedBy": 3, "modifiedDate": "2019-09-01 19:00:00", }, "isScheduled": true, "isShared": false, "snapshotId": "123", "accountId": 1, "snapshotName": "HTTP Server Report Snapshot", "timeSpan": { "duration": 604800, "startDate": "2019-09-01 00:00:00" } }, ... ] }

For error responses, see the response status codes documentation.

GET /v7/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

  • 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/v7/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
isScheduledbooleantrue if report snapshot was generated from a schedule
isSharedbooleantrue if report snapshot is shared
accountIdintegerID of the account group that the snapshot belongs to
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
reportobjectreport this report snapshot is based upon.
report.reportIdstringunique ID of the report
report.titlestringtitle of the report
report.isBuiltInbooleantrue for built-in reports, false for user-created reports
report.apiLinksarray of apiLink objectsa list of links which can be followed to pull more information
report.accountIdintegerID of the account group that the report belongs to
report.createdByintegerID of the user that created the report for which the snapshot was generated
report.modifiedByintegerID of the user that last modified the report at the time of snapshot creation
report.modifiedDatedateTimethe date/time when the report was last modified at the time the snapshot was created
widgetsobjectwidgets in the snapshot. Refer to the Widget object description.
permalinkstringlink to report snapshot in ThousandEyes Application

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=1", "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 /v7/report-snapshots/{snapshotId}/{widgetId} Report snapshot data

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

Parameters

  • 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.
  • {widgetId} the ID of the widget for which to retrieve data.

Request

  • no request body

Example

$ curl https://api.thousandeyes.com/v7/report-snapshots/60886ebb-2466-444d-bbd8-74d5ea1402d2/1234f.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 format for widget data. Check the endpoint to return widget data for reference.

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

{ "dateFrom": "2019-07-24 16:00:00", "dateTo": "2019-07-31 16:00:00", "groupLabels": [ { "groupProperty": "Countries", "groupLabels": [ { "groupId": "DE", "groupLabel": "Germany" }, { "groupId": "AU", "groupLabel": "Australia" }, ... ] } ], "binSize": 3600, "data": { "points": [ { "timestamp": 1563984000, "numberOfDataPoints": 62, "value": 569.0499070690524, "groups": [ { "groupProperty": "Countries", "groupValue": "AU" } ] }, ... ] } }

For error responses, see the response status codes documentation.

POST /v7/report-snapshots/create Creating a report snapshot

This endpoint creates a new report snapshot for the account group that the user belongs to. This endpoint requires the Edit Snapshots permission be assigned to the role of the user accessing this endpoint.

Parameters

  • 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

The endpoint expects a JSON object with the following fields:

Field NameData TypeNotes
displayNamestringThe name of the snapshot. Does not have to be unique.
fromdateTimeThe date and time to start aggregating data
tostringThe date and time to end aggregating data
reportIdstringThe ID of the report to generate a snapshot from

Example

$ curl https://api.thousandeyes.com/v7/report-snapshots/create \ -d '{ "displayName": "snapshot from API", "from": "2019-09-02 18:00:00", "to": "2019-09-03 18:00:00", "reportId": "123" }' \ -H "Content-Type: application/json" \ -H "Accept: application/json" \ -u noreply@thousandeyes.com:g351mw5xqhvkmh1vq6zfm51c62wyzib2

Response

Sends back the id of the created report snapshot:

Field NameData TypeNotes
snapshotIdstringunique ID of the report snapshot that is being generated

HTTP/1.1 200 OK Server: nginx Date: Mon, 02 Sep 2019 18:00:00 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

{ "snapshotId": "123" } For error responses, see the response status codes documentation.

POST /v7/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

  • 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/v7/report-snapshots/2bee381c-cc97-49f4-9ef5-1013c97f4124/delete \ -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.