Consent Manager

  • Your Privacy

  • Strictly Necessary Cookies

  • Performance Cookies

  • Targeting Cookies

  • Functional Cookies

Your Privacy

When you visit any website, it may store or retrieve information on your browser, mostly in the form of cookies. This information might be about you, your preferences or your device and is mostly used to make the site work as you expect it to. The information does not usually directly identify you, but it can give you a more personalized web experience. Because we respect your right to privacy, you can choose not to allow some types of cookies. Click on the different category headings to find out more and change our default settings. However, blocking some types of cookies may impact your experience of the site and the services we are able to offer. For more information on the information we collect and how we use it see the Website Privacy Statement.

Strictly Necessary Cookies

Always Active

These cookies are necessary for the website to function and cannot be switched off in our systems. They are usually only set in response to actions made by you which amount to a request for services, such as setting your privacy preferences, logging in or filling in forms. You can set your browser to block or alert you about these cookies, but some parts of the site will not then work. These cookies do not store any personally identifiable information.

Performance Cookies

Off On

These cookies allow us to count visits and traffic sources so we can measure and improve the performance of our site. They help us to know which pages are the most and least popular and see how visitors move around the site. All information these cookies collect is aggregated and therefore anonymous. If you do not allow these cookies we will not know when you have visited our site, and will not be able to monitor its performance.

Targeting Cookies

Off On

These cookies may be set through our site by our advertising partners. They may be used by those companies to build a profile of your interests and show you relevant adverts on other sites. They do not store directly personal information, but are based on uniquely identifying your browser and internet device. If you do not allow these cookies, you will experience less targeted advertising.

Functional Cookies

These cookies enable the website to provide enhanced functionality and personalization. They may be set by us or by third party providers whose services we have added to our pages. If you do not allow these cookies then some or all of these services may not function properly.

Your Privacy [`dialog closed`]

By continuing to use our website, you acknowledge the use of cookies. Privacy Statement | Change Settings

Cookies allow us to optimise your use of our website. We also use third-party cookies for advertising and analytics. Please read our Privacy Statement and Website Privacy Statement for more information on how we use cookies.

DEVELOPER REFERENCE

Search Results

×Clear
  • Overview

    • Welcome
    • Authentication
    • Account group context
    • Response formats
    • Time ranges
    • Response status codes
    • Rate limits
    • Pagination
    • Change policy
    • API change summary
  • Instant tests

    • Instant test
    • Instant test rerun
  • Tests

    • Test list
    • Test list by type
    • Test details
    • Test metadata
    • Creating a test
    • Updating a test
    • Deleting a test
    • Saved events
    • Path vis interface group list
    • Creating path vis interface group
    • Updating path vis interface group
    • Deleting path vis interface group
  • Test Data

    • (Network) End-to-End metrics
    • (Network) Path visualization
    • (Network) Detailed path trace
    • (Network) BGP metrics
    • (Network) BGP route information
    • (Web) HTTP server
    • (Web) Page load
    • (Web) Page load component detail
    • (Web) Web Transactions
    • (Web) Web Transaction detail
    • (Web) Web Transaction component detail
    • (Web) FTP server
    • (DNS) Domain trace
    • (DNS) Server metrics
    • (DNS) DNSSEC
    • (Voice) SIP server
    • (Voice) RTP stream
  • Credentials

    • Credential list
    • Credential details
    • Creating a credential
    • Updating a credential
    • Deleting a credential
  • Endpoint Agents

    • Listing all agents
    • Getting an agent by id
    • Updating an agent
    • Enabling an agent
    • Disabling an agent
    • Transferring an agent
    • Deleting an agent
  • Endpoint Data

    • Endpoint user session list
    • Endpoint user session details
    • Endpoint web pages list
    • Endpoint web page details
    • Endpoint network sessions list
    • Endpoint network topology list
    • Endpoint network topology details
    • Endpoint data filtering
    • Endpoint networks
  • Endpoint Tests

    • Scheduled Test List
    • Scheduled Test List by Type
    • Scheduled Test Details
    • Scheduled Test Metadata
    • Creating a Scheduled Test
    • Automated Session Test List
    • Automated Session Test Details
    • Automated Session Test Metadata
    • Creating an Automated Session Test
  • Endpoint Instant Tests

    • Creating instant test
    • Rerunning instant test
  • Endpoint Test Data

    • Scheduled Tests (Network) End-to-End metrics
    • Scheduled Tests (Network) Path visualization
    • Scheduled Tests (Network) Detailed path trace
    • Scheduled Tests (Web) HTTP server
    • Automated Session Tests End-to-End metrics
    • Automated Session Tests Path visualization
    • Automated Session Tests Detailed path trace
  • Snapshots

    • Create a new snapshot
  • Agents & Monitors

    • Agent list
    • Agent detail
    • Updating an agent
    • Deleting an Agent
    • Agent cluster - Creating
    • Agent cluster - Adding members
    • Agent cluster - Removing members
    • Agent cluster - Converting to an agent
    • BGP Monitor list
    • Agent Notification Rules
    • Agent Notification Rule Detail
  • Alerts & Notifications

    • Active alerts
    • Alert detail
    • Alert rules
    • Alert rule detail
    • Alert rule metadata
    • Creating an alert rule
    • Updating an alert rule
    • Deleting an alert rule
    • Alert notification integrations
    • Alert suppression windows
    • Alert suppression window detail
    • Creating an alert suppression window
    • Updating an alert suppression window
    • Deleting an alert suppression window
    • Creating an advanced Alert Rule
  • Labels

    • Labels list
    • Labels list by type
    • Label details
    • Label details (by label type)
    • Creating a label
    • Updating a label
    • Deleting a label
  • Reports

    • Reports list
    • Report detail
    • Report data
    • Deleting a report
    • Report snapshots list
    • Report snapshot detail
    • Report snapshot data
    • Deleting a report snapshot
  • Dashboards

    • Dashboards list
    • Dashboards detail
    • Dashboard data
    • Deleting a dashboard
    • Dashboard snapshots list
    • Dashboards snapshot detail
    • Dashboard snapshot data
    • Deleting a dashboard snapshot
  • Administrative endpoints

    • Account group list
    • Account group detail
    • Creating an account group
    • Updating an account group
    • Deleting an account group
    • User list
    • User detail
    • Adding a user
    • Updating a user
    • Deleting a user
    • Role list
    • Role detail
    • Creating a role
    • Updating a role
    • Permission list
    • Activity log
    • Obtaining usage quota
    • Updating usage quotas
  • Usage

    • Obtaining usage details
    • Usage metadata

  • Showing APIv6  |  APIv7 (preview)

  • Product Documentation
  • Customer Success Center
  • Public GitHub Repository

Try ThousandEyes Now! Sign Up

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 {email}:{authToken}

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
descriptionstringA longer text explanation of what the dashboard does intended for the user. This field will be shown as text only. It may be used as help for other users but is not typically displayed when showing 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
isPrivatebooleanThe dashboard can be viewed by other users in the account. If true, only the creator of the dashboard may view it. If false, all users in the same account may view it.
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
defaultTimespanobjectDefault timespan value to override widget timespans. See defaultTimespan below for details.
globalOverridebooleanTrue to override widget timespans and use defaultTimespan
isMigratedReportbooleanTrue if this dashboard was previously a report
apiLinksarray of apiLink objectsA list of links which can be followed to pull more information

defaultTimespan object:

FieldData TypeNotes
timespanDurationlongRelative timespan in seconds. For example, 3600 (Last 1 hour).
timespanStartstringStart of the timespan, in UTC, for timespan range. Use yyyy-MM-dd HH:mm:ss format. For example 2022-07-17 22:00:54.
timespanEndstringEnd of the timespan, in UTC, for timespan range. Use yyyy-MM-dd HH:mm:ss format. For example 2022-07-19 22:00:54.

Header

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", "description": "Test Dashboard", "isBuiltIn": false, "createdBy": 6699, "modifiedBy": 6699, "modifiedDate": "2022-02-22 18:10:04", "accountId": 11, "isPrivate": false, "isDefaultForUser": false, "isDefaultForAccount": false, "defaultTimespan": { "timespanDuration": 86400 }, "globalOverride": false, "isMigratedReport": 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 {email}:{authToken}

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
descriptionstringA longer text explanation of what the dashboard does intended for the user. This field will be shown as text only. It may be used as help for other users but is not typically displayed when showing 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
accountIdintegerID of the account that the dashboard belongs to
isPrivatebooleanThe dashboard can be viewed by other users in the account. If true, only the creator of the dashboard may view it. If false, all users in the same account may view it.
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
defaultTimespanobjectDefault timespan value to override widget timespans. See defaultTimespan below for details
globalOverridebooleanSet to true in order to override widget timespans and use defaultTimespan
isMigratedReportbooleanTrue if this dashboard was previously a report
apiLinksarray of apiLink objectsa list of links which can be followed to pull more information
widgetsarrayan array of widget objects

defaultTimespan object:

FieldData TypeNotes
timespanDurationlongRelative timespan in seconds. For example, 3600 (Last 1 hour).
timespanStartstringStart of the timespan, in UTC, for timespan range. Use yyyy-MM-dd HH:mm:ss format. For example 2022-07-17 22:00:54.
timespanEndstringEnd of the timespan, in UTC, for timespan range. Use yyyy-MM-dd HH:mm:ss format. For example 2022-07-19 22:00:54.

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, 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

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

Header

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", "description": "Test Dashboard", "isBuiltIn": false, "createdBy": 6825, "modifiedBy": 6825, "modifiedDate": "2022-03-01 22:31:30", "accountId": 11, "isPrivate": false, "isDefaultForUser": false, "isDefaultForAccount": false, "defaultTimespan": { "timespanDuration": 86400 }, "globalOverride": false, "isMigratedReport": 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": "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 {email}:{authToken}

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

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

Header

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 }, ... ] } }

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

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 {email}:{authToken}

Header

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.

GET /v6/dashboard-snapshots Dashboard snapshots list

This endpoint returns a list of dashboard 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 dashboard 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/dashboard-snapshots.json \ -u {email}:{authToken}

Response

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

Field NameData TypeNotes
snapshotIdstringunique ID of the dashboard snapshot
snapshotNamestringname of the dashboard snapshot
createdDatedateTimethe date/time when dashboard snapshot was created
scheduledboolean1 if dashboard snapshot was generated from a schedule
sharedboolean1 if dashboard snapshot is shared
dashboardobjectdashboard this dashboard snapshot is based upon.
timespan.startDatedateTimethe date/time of beginning of dashboard snapshot
timespan.durationintegerduration of dashboard snapshot in seconds
permalinkstringlink to dashboard snapshot in ThousandEyes Application
apiLinksarray of apiLink objectsa list of links which can be followed to pull more information

Header

HTTP/1.1 200 OK Server: nginx Date: Wed, 27 Jul 2022 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 }, "dashboardSnapshots": [ { "apiLinks": [...], "createdDate": "2022-07-27 14:42:49", "permalink": "https://app.thousandeyes.com/dashboard/?snapshotId=60886ebb-2466-444d-bbd8-74d5ea1402d2", "dashboard": { "apiLinks": [...], "builtIn": 1, "id": "0", "name": "ThousandEyes Built-in" }, "scheduled": 0, "shared": 0, "snapshotId": "60886ebb-2466-444d-bbd8-74d5ea1402d2", "snapshotName": "Dashboard Snapshot", "timeSpan": { "duration": 604800, "startDate": "2022-07-01 00:00:00" } }, ... ] }

For error responses, see the response status codes documentation.

GET /v6/dashboard-snapshots/{snapshotId} Dashboards snapshot detail

This endpoint returns a list of widgets configured in dashboard snapshot configured in ThousandEyes. Seed this endpoint with a snapshotId found from the /dashboard-snapshots endpoint. This endpoint requires the View Snapshots 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 dashboard snapshot you’re interested in.

Request

  • No request body.

Example

$ curl https://api.thousandeyes.com/v6/dashboard-snapshots/60886ebb-2466-444d-bbd8-74d5ea1402d2.json \ -u {email}:{authToken}

Response

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

Field NameData TypeNotes
snapshotIdstringUnique ID of the dashboard snapshot
snapshotNamestringName of the dashboard snapshot
createdDatedateTimeThe date/time when dashboard snapshot was created
scheduledboolean1 if dashboard snapshot was generated from a schedule
sharedboolean1 if dashboard snapshot is shared
dashboardobjectDashboard upon which this dashboard snapshot is based.
timespan.startDatedateTimeThe date/time of beginning of dashboard snapshot
timespan.durationintegerDuration of dashboard snapshot in seconds
permalinkstringLink to dashboard snapshot in ThousandEyes Application
apiLinksarray of apiLink objectsA list of links which can be followed to pull more information
widgetsarrayAn array of widget objects

Sends back a list of data elements associated with the dashboard snapshot. 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
titlestringWidget title
typestringWidget type; Agent Status, Alert List, 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-snapshot 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, the filter’s 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, the filter’s 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

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

Header

HTTP/1.1 200 OK Server: nginx Date: Wed, 22 Jul 2022 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

{ "dashboardSnapshots": [ { "apiLinks": [...], "createdDate": "2022-07-27 14:42:49", "permalink": "https://app.thousandeyes.com/dashboard/?snapshotId=60886ebb-2466-444d-bbd8-74d5ea1402d2", "dashboard": { "apiLinks": [...], "builtIn": 1, "id": "2", "name": "ThousandEyes Built-in" }, "scheduled": 0, "shared": 0, "snapshotId": "60886ebb-2466-444d-bbd8-74d5ea1402d2", "snapshotName": "Dashboard Snapshot", "timeSpan": { "duration": 604800, "startDate": "2022-07-01 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/dashboard-snapshots/{snapshotId}/{dataComponentId} Dashboard snapshot data

This endpoint returns actual metrics used in the generation of the dashboard 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 dashboard 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/dashboard-snapshots/60886ebb-2466-444d-bbd8-74d5ea1402d2/59089917755cb04ee9944e44.json \ -u {email}:{authToken}

Response

Sends back a list of data elements associated with the dashboard 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 on the chart is based on the data range shown in the dashboard snapshot. Bin sizes are based on the table below:

Dashboard time rangeBin size
up to 1 day5 minutes
1 day - 14 days1 hour
15 days - 30 days2 hours
31 days - 50 days4 hours
50 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
fromdateTimeStart date of the timespan for the data shown in the API output
todateTimeEnd date of the timespan for the data shown in the API output
reportDataComponentDataobjectobject represents dashboard widget data

reportDataComponentData object has the following fields for dashboard widgets:

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

reportDataComponentData object has the following fields for dashboard widgets:

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.

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

Header

HTTP/1.1 200 OK Server: nginx Date: Wed, 27 Jul 2022 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": "2022-07-23 00:00:00", "to": "2022-07-24 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/dashboard-snapshots/{snapshotId}/delete Deleting a dashboard snapshot

Deletes the specified dashboard snapshot in ThousandEyes, based on the snapshotId provided in the API request. Users with the Edit dashboards for all users in account group permission (Account Admin) can delete any dashboard snapshot.

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 dashboard snapshot you would like to delete

Response

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

Response has no body.

Example

The following example is presented for documentation and reference purposes only.

$ curl -i https://api.thousandeyes.com/v6/dashboard-snapshots/2bee381c-cc97-49f4-9ef5-1013c97f4124/delete.json \ -d '' \ -H "Content-Type: application/json" \ -H "Accept: application/json" \ -u {email}:{authToken}

Header

HTTP/1.1 204 No Content Server: nginx Date: Wed, 27 Jul 2022 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.

© 2023 ThousandEyes. All rights reserved.