Dashboards

GET /v6/dashboards Dashboards list

This endpoint returns a list of dashboards configured in ThousandEyes in the context of the user’s current account group. Use this data to find a dashboard in your account, which is then used in other endpoints 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/dashboards.json \ -u noreply@thousandeyes.com:g351mw5xqhvkmh1vq6zfm51c62wyzib2

Response

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

Field NameData TypeNotes
idstringunique Id of the dashboard
namestringtitle of the dashboard
isBuiltInbooleantrue for built-in dashboards, false for user-created dashboards
createdByintegerID of the user that created the dashboard
modifiedByintegerID of the user that last modified the dashboard
modifiedDatedateTimethe date/time when the dashboard was last modified
accountIdintegerID of the account that the dashboard belongs to
isPrivatebooleantrue if this dashboard is private
isDefaultForUserbooleantrue if this dashboard is the default for the user, false otherwise
isDefaultForAccountbooleantrue if this dashboard 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: Tue, 01 Mar 2022 17:53:57 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

{ "dashboards": [ { "id": "620ecb8e0112131fa51e263e", "name": "Dashboard Title A", "isBuiltIn": false, "createdBy": 6699, "modifiedBy": 6699, "modifiedDate": "2022-02-22 18:10:04", "accountId": 11, "isPrivate": false, "isDefaultForUser": false, "isDefaultForAccount": false, "apiLinks": [...] }, ... ] }

For error responses, see the response status codes documentation.

GET /v6/dashboards/{dashboardId} Dashboards detail

This endpoint returns a list of widgets configured in dashboards configured in ThousandEyes. Seed this endpoint with an id found from the /dashboards 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
  • {dashboardId} the ID of the dashboard you’re interested in.

Request

  • no request body

Example

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

Response

Returns dashboard metadata information and associated widget list. Each widget will contain these properties in its configuration.

Field NameData TypeNotes
idstringunique ID of the dashboard
namestringtitle of the dashboard
isBuiltInbooleantrue for built-in dashboards, false for user-created dashboards
createdByintegerID of the user who created the dashboard, as returned by the /v6/users API endpoint
modifiedByintegerID of the user who last modified the dashboard, as returned by the /v6/users API endpoint
modifiedDatestringYYYY-MM-DD HH:mm:ss formatted date of last dashboard modification time, shown in UTC
apiLinksarray of apiLink objectsa list of links which can be followed to pull more information
widgetsarrayan array of widget objects

The data returned for every widget will depend on the widget type. For Report widgets, refer to the Reports section of the documentation. Dashboard widgets will contain the following common properties:

Field NameData TypeNotes
titlestringwidget title
typestringwidget type; Agent Status, Alert List, Alert Grid, Test Table
dataComponentsarrayarray of widget data components
embedUrlstringif widget is marked as embedded, embedUrl is provided

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

Field NameData TypeNotes
dataComponentIdstringunique ID of the data component. Use this value to retrieve dataComponent values.
apiLinksarray of apiLink objectsa list of links which can be followed to pull more information

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

Agent Status

Field NameData TypeNotes
agentsstringtype of agent: Enterprise or Endpoint
showstringownership of agents: Owned Agents or All Assigned Agents
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 properties can be Agents, Agent Labels, etc. The list for each key holds the IDs of the property, i.e. agentIds, agentLabelIds, etc.

Alert List

Field NameData TypeNotes
alertTypesarraylist of alert types configured in the widget. An empty list means all alert types.
limitTointegerlimit the number of alerts to be shown in the widget
activeWithinobjecttimespan during which alerts had to be active to be shown 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 properties can be Alert Rules, Monitors, Tests, Test Labels, etc. The list for each key holds the IDs of the property, i.e. agentIds, testIds, etc.

Test Table

Field NameData TypeNotes
filterobjectmultisearch filter (see below). Valid keys for filters: Anything, Test Name, Target, Test ID, Test Type, Label ID
excludeobjectmultisearch filter (see below)
shouldExcludeAlertSuppressionWindowsbooleantrue for excluding alert suppression windows

Alert Grid

Field NameData TypeNotes
alertTypestringtype of alert
filterobjectmultisearch filter (see below). Valid keys for filters: Anything, Test Name, Test Type, Agent Name
excludeobjectmultisearch filter (see below)

Multi Search Filter

Field NameData TypeNotes
filterslistlist of object pairs with a key and a value as shown in the app.
typestringstring that defines the logical operator to be applied to filters: all or any

HTTP/1.1 200 OK Server: nginx Date: Tue, 01 Mar 2022 22:50:32 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

{ "dashboards": [ { "id": "620b1511048612499a42ac98", "name": "Dashboard Demo A", "isBuiltIn": false, "createdBy": 6825, "modifiedBy": 6825, "modifiedDate": "2022-03-01 22:31:30", "accountId": 11, "isPrivate": false, "isDefaultForUser": false, "isDefaultForAccount": false, "widgets": [ { "type": "Agent Status", "title": "Agent Status", "dataComponents": [ { "dataComponentId": "ayear", "filters": [ { "filterProperty": "Agents", "filterValue": "11119789" }, { "filterProperty": "Agents", "filterValue": "6522" }, { "filterProperty": "Agents", "filterValue": "6381" } ], "apiLinks": [...], "agents": "Enterprise Agents", "show": "Owned Agents" } ] }, { "type": "Alert Grid", "title": "Alert Grid", "dataComponents": [ { "dataComponentId": "wvoqu", "apiLinks": [...], "alertType": "Agents", "filter": { "filters": [ { "value": "test", "key": "Anything" } ], "type": "all" }, "exclude": { "filters": [], "type": "all" } } ] }, { "type": "Tests", "title": "Tests", "dataComponents": [ { "dataComponentId": "vug1s", "apiLinks": [...], "shouldExcludeAlertSuppressionWindows": false, "filter": { "filters": [ { "value": "test", "key": "Anything" } ], "type": "all" }, "exclude": { "filters": [ { "value": "Some String", "key": "Test Name" } ], "type": "all" } } ] }, { "type": "Alert List", "title": "Alert List", "dataComponents": [ { "dataComponentId": "wvcii", "apiLinks": [...], "alertTypes": [ "Routing - BGP" ], "limitTo": 10, "activeWithin": { "value": 1, "unit": "Hours" } } ] }, ], "apiLinks": [...] } ] }

For error responses, see the response status codes documentation.

GET /v6/dashboards/{dashboardId}/{dataComponentId} Dashboard data

This endpoint returns the raw data shown in a particular widget of a given dashboard.

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.
  • {dashboardId} the ID of the dashboard 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/dashboards/2/vlvb1.json \ -u noreply@thousandeyes.com:g351mw5xqhvkmh1vq6zfm51c62wyzib2

Response

Sends back a list of data elements associated with the dashboard. For Report widgets refer to the Reports page in the documentation. For Dashboard widgets, the data is returned with 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
dataComponentDataarray of non-aggregated pointssee below for Test Table, Alert Grid, Alert List and Agent Status

The fields returned in dataComponentData are dependent on the widget:

Agent Status

Field NameData TypeNotes
summaryobjectobject with a summary of how many agents are online, offline and disabled
agentsarraylist of agents

Each agent in the agent status data response will contain these properties

Field NameData TypeNotes
agentIdstringID of the agent
statusstringONLINE, OFFLINE or DISABLED
ipInfoobjectinformation about the IP of the agent if Enterprise or operating system version for Endpoint
agentNamestringname of the agent
locationobjectcontains the latitude, longitude and locationName of the agent

Alert List

Field NameData TypeNotes
totalAlertsintegertotal number of alerts that were active within the timespan configured
activeAlertsintegernumber of the alerts that are still active
alertsarrayarray of alerts

Each alert in the alert list data response will contain these properties

Field NameData TypeNotes
activebooleantrue or false
alertIdintegerid of the alert
testIdintegerid of the test
sourceIdintegerid of the agent, monitor or device producing the alert
sourceNamestringname of the agent, monitor or device producing the alert
alertRulestringname of the alert rule that this alert belongs to
alertTypestringname of the alert type
startTimestringdate when the alert was first active
durationInSecondsintegernumber of seconds the alert was active. If it’s still active, this number will increase every second.

Alert Grid

Field NameData TypeNotes
alertTypestringtype of alerts: Agent or BGP
totalAlertsintegertotal number of alerts that were active in the last 24 hours
numActiveAlertsintegernumber of the alerts that are active
numClearedOrDisabledAlertsInLastDayintegernumber of alerts that were cleared or disabled in the last 24 hours
alertsarrayarray of source alerts

Each source alert in the alert grid data response will contain these properties

Field NameData TypeNotes
isActivebooleantrue or false
alertIdintegerid of the alert
testIdintegerid of the test
prefixIdintegerid of the monitor prefix
sourceIdintegerid of the agent or monitor or device producing the alert
alertTypestringname of the alert type
startTimestringdate when the alert was first active
durationintegernumber of seconds the alert was active. Max is 24 hours
locationstringname of the location of the agent or monitor producing the alert

Test Table

This widget accepts the following query params to paginate the response:

  • rows={integer} optional, the number of alerts in the response. The default value is 10.
  • page={integer} optional, specifies the page number for the data response. The default value is 1.
  • sortProperty={string} optional, specifies the property to sort by. The possible values are alertStatus, testName or testType. The ordering may differ from the web application. The default value is alertStatus.
Field NameData TypeNotes
testsarraylist of test

Each test in the test table data response will contain these properties

Field NameData TypeNotes
testIdintegerid of the test
testNamestringname of the test
targetstringtarget configured in the test
testTypestringtype of test
alertStatusintegernumber of active alerts for the test
isSharedbooleanflag set to true if the test has been shared
graphletsarraylist of timeseries points for test metrics in the last 12 hours

Each graphlet object will contain these properties

Field NameData TypeNotes
metricstringname of the metric
testIdintegerid of the test
pointsarraylist of x and y datapoints where x is the timestamp of the point and y is the value

HTTP/1.1 200 OK Server: nginx Date: Wed, 02 Mar 2022 00:00:10 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

Agent Status

{ "to": "2022-03-02 00:04:48", "reportDataComponentData": { "summary": { "online": 0, "offline": 2, "disabled": 1 }, "agents": [ { "agentId": "6522", "status": "OFFLINE", "ipInfo": { "publicIp": "172.58.92.31", "privateIp": "172.17.0.3" }, "agentName": "0c3898000117", "location": { "latitude": 37.77493, "longitude": -122.41942, "locationName": "San Francisco, California, US" } }, ... ] } }

Alert List

{ "from": "2022-03-01 23:09:21", "to": "2022-03-02 00:09:21", "reportDataComponentData": { "totalAlerts": 2539, "activeAlerts": 2334, "alerts": [ { "alertType": "Routing - BGP", "active": true, "isActive": true, "alertId": 6394171, "testId": 123266, "ruleId": 250, "alertSource": "BGP-Test", "alertRule": "Default BGP Alert Rule", "startTime": "2022-03-01 22:15:00", "durationInSeconds": 6861 }, ... ] } }

Alert Grid

{ "from": "2022-03-01 00:12:19", "to": "2022-03-02 00:12:19", "reportDataComponentData": { "alertType": "Agents", "alerts": [ { "testId": 148688, "sourceId": "2163", "alertId": 6390633, "isActive": true, "alertType": "Http", "location": "Dallas, TX NAT", "startTime": "2022-03-01 23:30:00", "duration": 240 }, ... ], "totalAlerts": 362, "numActiveAlerts": 305, "numClearedOrDisabledAlertsInLastDay": 57 } }

Test Table

{ "from": "2022-03-01 12:14:45", "to": "2022-03-02 00:14:45", "pages": { "next": "https://api.thousandeyes.com/v6/dashboards/620b1511048612499a42ac98/vug1s.json?pageId=2", "current": 1 }, "reportDataComponentData": { "tests": [ { "graphlets": [ { "points": [ { "x": 1646136000, "y": 0 }, ... ], "metric": "Path Changes", "testId": 123419 }, { "points": [ { "x": 1646136000, "y": 95.83333333333334 }, ... ], "metric": "Reachability", "testId": 123419 } ], "testId": 123419, "testName": "Bgp test 08/19/2020 only public monitors - 4", "target": "64.233.160.0/19", "testType": "Routing - BGP", "alertStatus": 296, "isShared": false }, ... ] } } For error responses, see the response status codes documentation.

POST /v6/dashboards/{dashboardId}/delete Deleting a dashboard

Deletes the specified dashboard in ThousandEyes, based on the dashboardId provided in the API request. Users with the Edit dashboard templates for all users in account group permission (Account Admin) can delete any dashboard. Users with Edit own dashboard templates permission (Regular User) can only delete the dashboards 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
  • {dashboardId} the ID of the dashboard you would like to delete

Response

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

Response has no body.

Example

Please note, dashboard 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 -i https://api.thousandeyes.com/v6/dashboards/58c9437149b02d5410fd06cd/delete.json \ -d '' \ -H "Content-Type: application/json" \ -H "Accept: application/json" \ -u noreply@thousandeyes.com:g351mw5xqhvkmh1vq6zfm51c62wyzib2

HTTP/1.1 204 No Content Server: nginx Date: Tue, 01 Mar 2022 22:50:32 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.