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.

This is a preview of our upcoming API version 7, subject to change without notice.

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
  • Administrative API

    • Administrative API
  • Alerts & Notifications

    • Active alerts
    • Alert details
  • BGP Monitors

    • BGP Monitors
  • Dashboards

    • Dashboard list
    • Dashboard detail
    • Dashboard widget data
    • Creating a dashboard
    • Updating a dashboard
    • Deleting a dashboard
    • Dashboard snapshots list
    • Dashboard snapshot detail
    • Dashboard snapshot data
    • Creating a dashboard snapshot
    • Deleting a dashboard snapshot
    • Update a snapshot
  • Internet Insights

    • Outages
  • Tags

    • Tags
  • Test Data

    • (Network) Path visualization
  • Test Template

    • Test Template
  • ThousandEyes for OpenTelemetry

    • ThousandEyes for OpenTelemetry

  • APIv6  |  Showing APIv7 (preview)

  • Product Documentation
  • Customer Success Center
  • Public GitHub Repository

Try ThousandEyes Now! Sign Up

Dashboards

GET /v7/dashboards Dashboard list

This endpoint returns a list of dashboards configured in ThousandEyes in the context of the user’s login account group. Use this response to find a dashboard in your account group, which can be used to pull data of the specific dashboard.

Optional (Querystring) 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

Response

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

Field NameData TypeNotes
dashboardIdstringUnique ID of the dashboard
titlestringTitle 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
accountIdintegerID of the account that the dashboard belongs to
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
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
apiLinkstringLink to the dashboard

defaultTimespan object:

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

Example

$ curl https://api.thousandeyes.com/v7/dashboards.json \ -u {email}:{authToken}

Header

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: 240 X-Organization-Rate-Limit-Remaining: 225 X-Organization-Rate-Limit-Reset: 1492076520 Strict-Transport-Security: max-age=31536000 X-Server-Name: 1-2

Body

[ { "dashboardId": "5e20da3b72fce8003257bcba", "title": "Dashboard Title A", "description": "Test Dashboard", "isBuiltIn": false, "accountId": 11, "createdBy": 6828, "modifiedBy": 6828, "modifiedDate": "2020-01-16 22:06:38", "isPrivate": false, "isDefaultForUser": false, "isDefaultForAccount": false, "defaultTimespan": { "timespanDuration": 86400 }, "globalOverride": false, "isMigratedReport": false, "apiLink": "https://api.thousandeyes.com/v7/dashboards/5e20da3b72fce8003257bcba" }, ... ]

For error responses, see the response status codes documentation.

GET /v7/dashboards/{dashboardId} Dashboard detail

This endpoint returns a list of widgets configured in a ThousandEyes dashboard in addition to the dashboard’s metadata.

Optional (Querystring) 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

  • {dashboardId} the ID of the desired dashboard which can be found from the /dashboards endpoint.
  • no request body

Response

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

Field NameData TypeNotes
dashboardIdstringUnique ID of the dashboard
titlestringTitle of the dashboard
createdByintegerID of the user who created the dashboard, as returned by the /v7/users API endpoint
modifiedByintegerID of the user who last modified the dashboard, as returned by the /v7/users API endpoint
modifiedDatestringYYYY-MM-DD HH:mm:ss formatted date of last dashboard modification time, shown in UTC
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 reports, false for user-created reports
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
widgetsarrayAn array of widget objects
apiLinkstringLink to the dashboard

defaultTimespan object:

FieldData TypeNotes
timespanDurationlongRelative timespan in seconds. For example, 3600 (Last 1 hour).
timespanStartstringStart of the timespan in UTC for timespan range in yyyy-MM-dd HH:mm:ss format. For example 2022-07-17 22:00:54.
timespanEndstringEnd of the timespan in UTC for timespan range in 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. All widgets contain the following common properties:

Field NameData TypeNotes
idstringunique widget identifier inside the report. Note: Only unique within the same report, not across all reports
typestringwidget type: Agent Status, Alert List, Color Grid, Test Table, Table, Multi Metric Table, Map, Number Card, Pie Chart, Time Series, Stacked Area Chart, or Box and Whiskers
visualModestring(optional, defaults to Full) Visual mode in the UI: Full or Half screen
fixedTimespanobject(optional) fixed timespan to do aggregation over. Specified with a value and unit (Days, Hours, or Minutes).
titlestring(optional, defaults to widget type string) widget title
isEmbeddedbooleantrue if widget is marked as embedded, false otherwise
embedUrlstringif widget is marked as embedded, embedUrl is provided
apiLinkstringlink to the data of the widget

Unless otherwise indicated below, most Dashboard widgets will have the following fields:

Field NameData TypeNotes
dataSourcestringdata source of widget. Can be Alerts, Cloud & Enterprise Agents, Devices, Endpoint Agents, etc.
metricGroupstringmetric group of widget as it appears in the UI. Can be Web - HTTP Server, Voice - SIP Server, Network - Agent to Agent, etc. Note: May not be required in some cases
metricstringthe metric being tabulated in the report: defined by the layer, test type and metric.
directionstringdirection of agent to agent metric: Source to Target, Target to Source, or Both Directions. (Required for some metrics)
measurestringstatistical measure shown, i.e. Minimum, Maximum, …
groupByarray of groupBy objectsarray of groupBy strings, i.e. Tests, Agents, …
filtersarray of filter mappings(optional) where the widget is filtered, filters property is shown. Each filter object represents one selected item and contains filterProperty and filterValue properties. filterProperty can be Agents, Agent Groups, Tests, Monitors, etc. filterValue holds the Id of the property, i.e. test, agent, monitor Id.

Agent Status

Field NameData TypeNotes
agentsstringtype of agent: Enterprise or Endpoint
showstringownership of agents: Owned Agents or All Assigned Agents

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

Color Grid

Field NameData TypeNotes
dataSourcestringdata source of widget. Can be Alerts, Cloud & Enterprise Agents, Devices, Endpoint Agents, etc.
metricGroupstringmetric group of widget as it appears in the UI. Can be Web - HTTP Server, Voice - SIP Server, Network - Agent to Agent, etc. Note: May not be required in some cases
metricstringmetric of widget. Can be Response Time, Total Error Count, Page Load Time, Marker Time, Packet Loss, Throughput, etc.
directionstringdirection of agent to agent metric: Source to Target, Target to Source, or Both Directions. (Required for some metrics)
measureobjectmeasure configuration of the widget
cardsstringProperty name to aggregate by. Can be Tests, Test Labels, Continents, Countries, etc.
groupCardsBystringProperty name to group cards by. Can be Tests, Test Labels, Continents, Countries, etc.
minScalefloat(optional) minimum scale configured in the widget
maxScalefloat(optional) maximum scale configured in the widget
unitstring(optional) Typically this is automatically configured. Possible options: Kbps, Mbps, Gbps, Kpps, Mpps, Gpps
columnsinteger(optional) number of columns: 1 or 2
limitinteger(optional) limit configured in the widget
sortBystringProperty to sort by: Value or Alphabetical. Exception: Multi-metric table widget
sortDirectionstringDirection to sort by: Ascending or Descending
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 Labels, Tests, Monitors, etc. The list for each key holds the IDs of the property, i.e. testIds, agentIds, 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)

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

Example

$ curl https://api.thousandeyes.com/v7/dashboards/1.json \ -u {email}:{authToken}

Header

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: 240 X-Organization-Rate-Limit-Remaining: 232 X-Organization-Rate-Limit-Reset: 1492076520 Strict-Transport-Security: max-age=31536000 X-Server-Name: 1-2

Body

{ "dashboardId": "5e1f7a99143ae6004fdc3bb4", "title": "Dashboard API", "description": "Test Dashboard", "isBuiltIn": false, "accountId": 11, "createdBy": 6103, "modifiedBy": 6103, "modifiedDate": "2020-01-16 21:09:09", "isPrivate": false, "isDefaultForUser": true, "isDefaultForAccount": false, "defaultTimespan": { "timespanDuration": 86400 }, "globalOverride": false, "isMigratedReport": false, "widgets": [ { "id": "xtzbr", "type": "Color Grid", "title": "Color Grid", "visualMode": "Full", "dataSource": "Cloud & Enterprise Agents", "metricGroup": "Web - HTTP Server", "metric": "Response Time", "measure": { "type": "Mean" }, "fixedTimespan": { "value": 1, "unit": "Hours" }, "apiLink": "https://api.thousandeyes.com/v7/dashboards/5e1f7a99143ae6004fdc3bb4/xtzbr", "cards": "Tests", "groupCardsBy": "Agents", "columns": 1, "sortBy": "Value", "sortDirection": "Ascending" }, { "id": "vxqve", "type": "Agent Status", "title": "Agent Status", "visualMode": "Full", "apiLink": "https://api.thousandeyes.com/v7/dashboards/5e1f7a99143ae6004fdc3bb4/vxqve", "agents": "Enterprise Agents", "show": "Owned Agents" }, { "id": "o6mjm", "type": "Test Table", "title": "Tests", "visualMode": "Full", "fixedTimespan": { "value": 12, "unit": "Hours" }, "apiLink": "https://api.thousandeyes.com/v7/dashboards/5e1f7a99143ae6004fdc3bb4/o6mjm", "filter": { "filters": [ { "key": "Test Name", "value": "123" } ], "type": "all" }, "exclude": { "filters": [ { "key": "Label ID", "value": "25236" } ], "type": "all" } } ], "apiLink": "https://api.thousandeyes.com/v7/dashboards/5e1f7a99143ae6004fdc3bb4" }

For error responses, see the response status codes documentation.

GET /v7/dashboards/{dashboardId}/{widgetId} Dashboard widget data

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

Optional (Querystring) 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.
  • rows={integer} optional, the number of elements to receive per page. Only available for Alert List and Test Table Widget.
  • page={integer} optional, specifies the page number for the data response. Only available in Test Table widget.
  • sortProperty={string} optional, specifies the property to sort by. Only available for Alert List and Test Table Widget. See below for accepted values for each widget.
  • sortDirection={string} optional, specifies the direction to sort by. Only available for Alert List and Test Table Widget. The possible values are Ascending or Descending. The default value is Descending.

Request

  • {dashboardId} the ID of the dashboard you’re interested in.

  • {widgetId} the ID of the widget for which to retrieve data.

  • no request body

Response

For most widgets, 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
up to 1 day5 minutes
1 day - 14 days1 hour
15 days - 30 days2 hours
31 days - 50 days4 hours
51 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

Multi 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

Some widgets, such as Agent Status, Alert List, and Test Table, return more specialized data elements. Their fields are described below.

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 (if applicable)
groupLabelsarray of group labelssee groupLabel fields below (if widget groups by any property)
data.pointsarray of data pointssee data point below
dataarray of non-aggregated pointssee below for Test Table, Alert List and Agent Status
statusstringMessage for not fully configured widget or no data

The fields in data.point are the following:

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

The fields returned in data 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

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 the limitBy configured for the widget.
  • sortProperty={string} optional, specifies the property to sort by. The possible values are alertStatus or startTime. The default value is alertStatus
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

Example

$ curl https://api.thousandeyes.com/v7/dashboards/2/vlvb1.json \ -u {email}:{authToken}

Header

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: 240 X-Organization-Rate-Limit-Remaining: 235 X-Organization-Rate-Limit-Reset: 1492076520 Strict-Transport-Security: max-age=31536000 X-Server-Name: 1-2

Body

Most 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" } ] } ] } }

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": [] } ] } ] } }

Color Grid

{ "dateFrom": "2020-01-16 22:15:00", "dateTo": "2020-01-16 23:15:00", "groupLabels": [], "binSize": 300, "data": { "points": [ { "timestamp": 1579216200, "numberOfDataPoints": 3270, "value": 344.00582535755046, "groups": [ { "groupProperty": "Continents", "groupValue": "AS" } ] }, { "timestamp": 1579216200, "numberOfDataPoints": 5082, "value": 156.37737466049668, "groups": [ { "groupProperty": "Continents", "groupValue": "EU" } ] }, ... ] } }

Alert List

{ "dateFrom": "2020-01-16 22:28:52", "dateTo": "2020-01-16 23:28:52", "data": { "alertsData": { "totalAlerts": 590, "activeAlerts": 483, "alerts": [ { "alertId": 2004945, "testId": 56512, "ruleId": 281724, "alertSource": "AI Team Web Http Test 2", "alertRule": "AI dynamic baseline verification 11-21", "alertType": "Web - HTTP Server", "startTime": "2020-01-16 23:28:05", "durationInSeconds": 47, "active": true }, { "alertId": 2004941, "testId": 67035, "ruleId": 202156, "alertSource": "A2A uni CEA-13201 T10 Copy", "alertRule": "Delay always on", "alertType": "Network - Path Trace", "startTime": "2020-01-16 23:26:07", "durationInSeconds": 165, "active": true }, ... ] } } }

Test Table

{ "pages": { "next": "https://api.thousandeyes.com/v7/dashboards/5e2f669636256d0053617499/cogto?page=2" }, "dateFrom": "2020-01-30 17:04:10", "dateTo": "2020-01-31 05:04:10", "binSize": 300, "data": { "tests": [ { "testId": 68256, "testName": "$$$", "target": "https://www.google.com", "testType": "Web - HTTP Server", "alertStatus": 24, "isShared": true, "graphlets": [ { "metric": "Availability", "testId": 68256, "points": [ { "x": 1580403900, "y": 0.0 }, ... ] }, { "metric": "Response Time", "testId": 68256, "points": [ { "x": 1580406780, "y": 128.249 }, ... ] } ] }, ... ] } }

Agent Status

{ "dateTo": "2020-01-31 05:07:18", "binSize": 300, "data": { "summary": { "online": 10, "offline": 2, "disabled": 3 }, "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" } }, ... ] } }

For error responses, see the response status codes documentation.

POST /v7/dashboards/create Creating a dashboard

This endpoint creates a new dashboard for the Login Account Group. User must have the Edit dashboard templates for all users in account group permission (Account Admin) or Edit own dashboard templates permission (Regular User) to create dashboards.

Optional (Querystring) 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 Dashboard object with or without Widgets. See Dashboard Detail for reference.

Response

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

Field NameData TypeNotes
dashboardIdstringUnique ID of the dashboard
titlestringTitle of the dashboard
isBuiltInbooleanTrue for built-in dashboards, false for user-created dashboards
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.
accountIdintegerID of the account that the dashboard belongs to
createdByintegerID of the user that created the dashboard
modifiedDatedateTimeThe date/time when the dashboard was last modified
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
defaultTimespanobjectDefault timespan value to override widget timespans, see defaultTimespan below for details
globalOverridebooleanTrue to override widget timespans and use defaultTimespan
widgetsarray of widget objectsAn array of widget objects
apiLinkstringLink to the dashboard

defaultTimespan can be relative or fixed with start and end. It can not be both. defaultTimespan object:

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

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

Example

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

Header

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: 240 X-Organization-Rate-Limit-Remaining: 237 X-Organization-Rate-Limit-Reset: 1492076520 Strict-Transport-Security: max-age=31536000 X-Server-Name: 1-2

Body

{ "dashboardId": "5e1f7a99143ae6004fdc3bb4", "title": "HTTP Server Widgets", "description": "HTTP Server Widgets", "isBuiltIn": false, "accountId": 1, "createdBy": 1, "isPrivate": false, "isDefaultForUser": false, "isDefaultForAccount": false, "defaultTimespan": { "timespanDuration": "7200" }, "globalOverride": false, "widgets": [...], "apiLink": "https://api.thousandeyes.com/v7/dashboards/5e1f7a99143ae6004fdc3bb4" }

For error responses, see the response status codes documentation.

POST /v7/dashboards/{dashboardId}/update Updating a dashboard

This endpoint updates an existing dashboard for the account group that the user belongs to. Users with the Edit dashboard templates for all users in account group permission (Account Admin) can update any dashboard. Users with Edit own dashboard templates permission (Regular User) can only update the dashboards they have created.

  • Note: This endpoint will do a FULL update, replacing the existing dashboard template with the object sent in the request. If a partial update is required, it’s recommended to first retrieve the dashboard, modify the dashboard object and then send it on the update.

Optional (Querystring) 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

  • {dashboardId} the ID of the dashboard you’re interested in.

A Dashboard object with or without Widgets.

Response

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

Field NameData TypeNotes
dashboardIdstringUnique ID of the dashboard
titlestringTitle of the dashboard
descriptionstringDescription of the dashboard
isBuiltInbooleanTrue for built-in dashboards, false for user-created dashboards
accountIdintegerID of the account that the dashboard belongs to
createdByintegerID of the user that created the dashboard
modifiedDatedateTimeThe date/time when the dashboard was last modified
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
defaultTimespanobjectDefault timespan value to override widget timespans, see defaultTimespan below for details
globalOverridebooleanTrue to override widget timespans and use defaultTimespan
widgetsarray of widget objectsAn array of widget objects
apiLinkstringLink to the dashboard

defaultTimespan can be relative or fixed with start and end. It can not be both. defaultTimespan object:

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

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 dashboard. Alternatively, the widgetIds will be generated for them.

Example

$ curl https://api.thousandeyes.com/v7/dashboards/1/update \ -d '{ "title": "New Dashboard Updated" }' \ -H "Content-Type: application/json" \ -H "Accept: application/json" \ -u {email}:{authToken}

Header

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: 240 X-Organization-Rate-Limit-Remaining: 238 X-Organization-Rate-Limit-Reset: 1492076520 Strict-Transport-Security: max-age=31536000 X-Server-Name: 1-2

Body

[ { "dashboardId": "5e1f7a99143ae6004fdc3bb4", "title": "HTTP Server Widgets", "description": "HTTP Server Widgets", "isBuiltIn": false, "accountId": 1, "createdBy": 1, "isPrivate": false, "isDefaultForUser": false, "isDefaultForAccount": false, "defaultTimespan": { "timespanDuration": "7200" }, "globalOverride": false, "widgets": [...], "apiLink": "https://api.thousandeyes.com/v7/dashboards/5e1f7a99143ae6004fdc3bb4" }, ... ]

For error responses, see the response status codes documentation.

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

Optional (Querystring) 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

  • {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 https://api.thousandeyes.com/v7/dashboards/1/delete \ -u {email}:{authToken}

Header

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

  • 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={dashboardId} Optional parameter to filter the list of snapshots by dashboard ID.

Request

  • No request body.

Example

$ curl https://api.thousandeyes.com/v7/dashboard-snapshots.json \ -u {email}:{authToken}

$ curl https://api.thousandeyes.com/v7/dashboard-snapshots.json\?dashboardId\=1 \ -u {email}:{authToken}

Response

Sends back an array of dashboard 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
dashboardSnapshotsarray of dashboard snapshot objectsSee below

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
isScheduledbooleanTrue if dashboard snapshot was generated from a schedule
isSharedbooleanTrue if dashboard snapshot is shared
accountIdintegerID of the account group that the snapshot belongs to
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
dashboardobjectDashboard upon which this dashboard snapshot is based upon.
permalinkstringLink to dashboard snapshot in ThousandEyes Application

Header

HTTP/1.1 200 OK Server: nginx Date: Wed, 27 Jul 2022 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 }, "dashboardSnapshots": [ { "apiLinks": [...], "permalink": "https://api.thousandeyes.com/dashboard/?snapshotId=123", "createdDate": "2022-07-27 18:00:00", "dashboard": { "apiLinks": [...], "id": "1", "title": "Dashboard", "isBuiltIn": false, "accountId": 1, "createdBy": 2, "modifiedBy": 3, ... }, "isScheduled": true, "isShared": false, "snapshotId": "123", "accountId": 1, "snapshotName": "HTTP Server Dashboard Snapshot", "timeSpan": { "duration": 604800, "startDate": "2019-09-01 00:00:00" } }, ... ] }

For error responses, see the response status codes documentation.

GET /v7/dashboard-snapshots/{snapshotId} Dashboard 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

  • 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/v7/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
isScheduledbooleanTrue if dashboard snapshot was generated from a schedule
isSharedbooleanTrue if dashboard snapshot is shared
accountIdintegerID of the account group that the snapshot belongs to
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
dashboardobjectDashboard this dashboard snapshot is based upon.
widgetsobjectWidgets in the snapshot. Refer to the Widget object description.
permalinkstringLink to dashboard snapshot in ThousandEyes Application

Header

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

{ "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-23 00:00:00" }, "widgets": [ { "id": "abcd1", "type": "Multi Metric Table", "title": "Multi Metric Table", "visualMode": "Full", "apiLink": "https://api.thousandeyes.com/v7/dashboard-snapshots/60886ebb-2466-444d-bbd8-74d5ea1402d2/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" } } ] }, ... ] }

For error responses, see the response status codes documentation.

GET /v7/dashboard-snapshots/{snapshotId}/{widgetId} Dashboard snapshot data

This endpoint returns actual metrics used in the generation of the dashboard 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 dashboard 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/dashboard-snapshots/60886ebb-2466-444d-bbd8-74d5ea1402d2/1234f.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 in 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
51 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.

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

{ "dateFrom": "2022-07-24 16:00:00", "dateTo": "2022-07-25 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/dashboard-snapshots/create Creating a dashboard snapshot

This endpoint creates a new dashboard 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
dashboardIdstringThe ID of the dashboard to generate a snapshot from
expirationDatestringExpiration date for this snapshot. If not provided, snapshot will be created with an expiration date of 1 year from creation date. The expiration date should be a future date and must not exceed 5 years from the current date.

Example

$ curl https://api.thousandeyes.com/v7/dashboard-snapshots/create \ -d '{ "displayName": "snapshot from API", "from": "2022-07-26 18:00:00", "to": "2022-07-26 19:00:00", "dashboardId": "123", "expirationDate":"2025-07-26 18:00:00" }' \ -H "Content-Type: application/json" \ -H "Accept: application/json" \ -u {email}:{authToken}

Response

Sends back the id of the created dashboard snapshot:

Field NameData TypeNotes
snapshotIdstringUnique ID of the dashboard snapshot that is being generated

Header

HTTP/1.1 200 OK Server: nginx Date: Wed, 27 Jul 2022 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": "1234" } For error responses, see the response status codes documentation.

POST /v7/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 reports for all users in account group permission (Account Admin) can delete any dashboard snapshot.

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 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 https://api.thousandeyes.com/v7/dashboard-snapshots/2bee381c-cc97-49f4-9ef5-1013c97f4124/delete \ -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.

PATCH /v7/dashboard-snapshots/{snapshotId} Update a snapshot

Updates expiration date of snapshot. To update expiration date of a snapshot, the user accessing this endpoint must have Edit snapshots permission assigned to their role.

Parameters

  • {snapshotId} The ID of dashboard snapshot you’re interested in.

Request

The endpoint expects a JSON object with the following mandatory filed:

Field NameData TypeNotes
expirationDateStringThe expiration date should be a future date and must not exceed 5 years from the current date.

Response

If snapshot is successfully updated HTTP 20O OK and body of response will be empty. If user lacks the permissions to delete the dashboard, an HTTP 403 FORBIDDEN response will be returned.

Example

$ curl -X PATCH -i https://api.thousandeyes.com/v7/dashboard-snapshots/123 \ -d '{ "expirationDate": "2024-07-26 00:00:00", }' \ -H "Content-Type: application/json" \ -H "Accept: application/json" \ -u {email}:{authToken}

Header

HTTP/1.1 200 OK Server: nginx Date: Mon, 09 May 2016 16:04:24 GMT Content-Type: application/json;charset=UTF-8 Transfer-Encoding: chunked Connection: keep-alive X-Organization-Rate-Limit-Limit: 240 X-Organization-Rate-Limit-Remaining: 228 X-Organization-Rate-Limit-Reset: 1492608660 Strict-Transport-Security: max-age=31536000 X-Server-Name: 1-2

For more information on our HTTP response status codes, see the response status codes documentation.

© 2023 ThousandEyes. All rights reserved.