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

Agents & Monitors

GET /v6/agents Agent list

Returns a list of all agents available to your account in ThousandEyes, including both Enterprise and Cloud agents.

Optional (Querystring) Parameters

  • agentTypes=CLOUD|ENTERPRISE|ENTERPRISE_CLUSTER optional, specifies the type of agents requested. Accepts either a single allowed value or a comma-separated list of allowed values
  • 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/agents.json \ -u {email}:{authToken}

Response

Sends back an array of agents, specifying agentId, which can be used by other areas of the API. The agent’s public IP addresses will be shown, along with last. If an agent is an Enterprise agent, the agent’s public and private IP addresses will be shown, as well as the public network in which the agent is located.

FieldData TypeUnitsNotes
agentIdintegern/aunique ID of agent
agentNamestringn/adisplay name of the agent
agentTypestringn/aCloud, Enterprise or Enterprise Cluster, shows the type of agent
countryIdstringn/aISO-3166-1 alpha-2 country code of the agent
clusterMembersarrayn/aif an enterprise agent is clustered, detailed information about each cluster member will be shown as array entries in the clusterMembers field. This field is not shown for Enterprise Agents in standalone mode, or for Cloud Agents.
ipAddressesarrayn/aarray of ipAddress entries
groupsarrayn/aarray of label objects - see Labels for more information.
locationstringn/alocation of the agent
errorDetailsarrayn/aif an enterprise agent or a cluster member presents at least one error, the errors will be shown as an array of entries in the errorDetails field (Enterprise Agents and Enterprise Cluster members only)
hostnamestringn/afully qualified domain name of the agent (Enterprise Agents only)
prefixstringn/aNetwork prefix, expressed in CIDR format (Enterprise Agents only)
enabledbooleann/a1 for enabled, 0 for disabled (Enterprise Agents only)
networkstringn/aname of the autonomous system in which the Agent is found (Enterprise Agents only)
createdDatedateTimen/ayyyy-MM-dd hh:mm:ss, expressed in UTC. For Enterprise Clusters, this equals to the createdDate value of the initial cluster member before the conversion to cluster was performed (Enterprise Agents and Enterprise Clusters only)
lastSeendateTimen/ayyyy-MM-dd hh:mm:ss, expressed in UTC (Enterprise Agents only)
agentStatestringn/aOnline, Offline or Disabled (standalone Enterprise Agents only)
keepBrowserCachebooleann/a1 for enabled, 0 for disabled (Enterprise Agents and Enterprise Clusters only)
utilizationintegerpercentageshows overall utilization percentage (online Enterprise Agents and Enterprise Clusters only)
ipv6Policystringn/aIP version policy, can be FORCE_IPV4, PREFER_IPV6 or FORCE_IPV6 (Enterprise Agents and Enterprise Clusters only)
targetForTestsstringn/atarget IP address or domain name representing test destination when agent is acting as a test target in an agent-to-agent test (Enterprise Agents only)

If the AgentType is Enterprise Cluster, a clusterMembers field will be available, which is an array of clusterMember objects, containing the following fields:

FieldData TypeUnitsNotes
memberIdintegern/aunique ID of the cluster member
namestringn/aname of the cluster member
ipAddressesarrayn/aarray of ipAddress entries
publicIpAddressesarrayn/aarray of ipAddress entries
prefixstringn/aNetwork prefix, expressed in CIDR format (Enterprise Agents only)
networkstringn/aname of the autonomous system in which the Agent is found (Enterprise Agents only)
lastSeendateTimen/ayyyy-MM-dd hh:mm:ss, expressed in UTC (Enterprise Agents only)
agentStatestringn/aOnline, Offline or Disabled
utilizationintegerpercentageshows overall utilization percentage of a cluster member
targetForTestsstringn/atarget IP address or domain name representing test destination when agent is acting as a test target in an agent-to-agent test

If an Enterprise Agent or a Cluster Member presents at least one error, an errorDetails field will be available, which is an array of errorDetail objects, containing the following fields:

FieldData TypeUnitsNotes
codestringn/aAGENT_VERSION_OUTDATED, APPLIANCE_VERSION_OUTDATED, BROWSERBOT_VERSION_OUTDATED, CLOCK_OFFSET, NAT_TRAVERSAL_ERROR, OS_END_OF_INSTALLATION_SUPPORT, OS_END_OF_SUPPORT, or OS_END_OF_LIFE
descriptionstringn/adetailed explanation of the error code

Header

HTTP/1.1 200 OK Server: nginx Date: Mon, 09 May 2016 16:04:24 GMT Content-Type: application/json Transfer-Encoding: chunked Connection: keep-alive Cache-Control: no-store X-Organization-Rate-Limit-Limit: 240 X-Organization-Rate-Limit-Remaining: 229 X-Organization-Rate-Limit-Reset: 1493294160 Strict-Transport-Security: max-age=31536000 X-Server-Name: 1-2

Body

{ "agents": [ { "agentId": 6, "agentName": "Fremont, CA (v6)", "agentType": "Cloud", "countryId": "US", "ipAddresses": [ "2600:3c01::f03c:91ff:feae:4f96" ], "location": "San Francisco Area" }, { "agentId": 11, "agentName": "London, UK", "agentType": "Cloud", "countryId": "GB", "ipAddresses": [ "176.58.99.46", "178.79.138.106" ], "location": "City of London, United Kingdom" }, { "agentId": 29, "agentName": "Sample Enterprise Agent", "location": "United States", "countryId": "US", "createdDate": "2015-02-05 21:23:33", "prefix": "38.0.0.0/8", "ipAddresses": [ "10.100.50.25" ], "publicIpAddresses": [ "38.122.6.66" ], "network": "Cogent Communications (AS 174)", "agentType": "Enterprise", "lastSeen": "2015-02-05 23:23:33", "agentState": "Online", "targetForTests": "1.1.1.1" }, { "agentId": 1975, "agentName": "Duke cluster", "location": "San Francisco Bay Area", "countryId": "US", "createdDate": "2015-02-05 21:23:33", "enabled": 1, "keepBrowserCache": 0, "clusterMembers": [ { "name": "duke_agent3.thousandeyes.net", "ipAddresses": [ "172.17.0.2" ], "publicIpAddresses": [ "38.122.6.66" ], "prefix": "38.0.0.0/8", "utilization": 1, "network": "Cogent Communications (AS 174)", "lastSeen": "2015-07-15 17:16:11", "agentState": "Online", "memberId": 1235, "targetForTests": "2.2.2.2" }, [...] ], "agentType": "Enterprise Cluster", "utilization": 1, "ipv6Policy": "FORCE_IPV4" } ] }

For error responses, see the response status codes documentation.

GET /v6/agents/{agentId} Agent detail

Returns details for an agent, including assigned tests. Enterprise agents show utilization data and assigned accounts.

Optional (Querystring) 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/agents/12.json \ -u {email}:{authToken}

Response

Sends back agent details for an agent. For Enterprise Agents, additional details, including a list of account groups to which the agent is assigned, and utilization details will be shown. Metadata is shown below:

FieldData TypeUnitsNotes
agentIdintegern/aunique ID of agent
agentNamestringn/adisplay name of the agent
locationstringn/alocation of the agent
countryIdstringn/aISO-3166-1 alpha-2 country code of the agent
clusterMembersarrayn/aif an enterprise agent is clustered, detailed information about each cluster member will be shown as array entries in the clusterMembers field. This field is not shown for Enterprise Agents in standalone mode, or for Cloud Agents.
prefixstringn/aNetwork prefix, expressed in CIDR format (Enterprise Agents only)
utilizationintegerpercentageshows overall utilization percentage (online Enterprise Agents and Enterprise Clusters only)
ipv6Policystringn/aIP version policy, can be FORCE_IPV4, PREFER_IPV6 or FORCE_IPV6 (Enterprise Agents and Enterprise Clusters only)
ipAddressesarrayn/aarray of ipAddress entries
groupsarrayn/aarray of label objects - see Labels for more information.
enabledbooleann/a1 for enabled, 0 for disabled
accountGroupsarrayn/alist of account groups to which the agent is assigned, showing aid and accountGroupName fields (Enterprise Agents and Enterprise Clusters only)
testsarrayn/alist of tests assigned to the agent, expressed in the same format as /tests endpoint
networkstringn/aname of the autonomous system in which the Agent is found
agentTypestringn/aeither Cloud, Enterprise, or Enterprise Cluster, shows the type of agent
errorDetailsarrayn/aif an enterprise agent or a cluster member presents at least one error, the errors will be shown as an array of entries in the errorDetails field (Enterprise Agents and Enterprise Cluster members only)
hostnamestringn/afully qualified domain name of the agent (Enterprise Agents only)
createdDatedateTimen/ayyyy-MM-dd hh:mm:ss, expressed in UTC. For Enterprise Clusters, this equals to the createdDate value of the initial cluster member before the conversion to cluster was performed (Enterprise Agents and Enterprise Clusters only)
lastSeendateTimen/ayyyy-MM-dd hh:mm:ss, expressed in UTC (Enterprise Agents only)
agentStatestringn/aOnline, Offline or Disabled (standalone Enterprise Agents only)
notificationRulesarrayn/aarray of notification rule objects configured on agent
keepBrowserCachebooleann/a1 for enabled, 0 for disabled (Enterprise Agents and Enterprise Clusters only)
targetForTestsstringn/atarget IP address or domain name representing test destination when agent is acting as a test target in an agent-to-agent test (Enterprise Agents only)

If the AgentType is Enterprise Cluster, a clusterMembers field will be available, which is an array of clusterMember objects, containing the following fields:

FieldData TypeUnitsNotes
memberIdintegern/aunique ID of the cluster member
namestringn/aname of the cluster member
ipAddressesarrayn/aarray of ipAddress entries
publicIpAddressesarrayn/aarray of ipAddress entries
prefixstringn/aNetwork prefix, expressed in CIDR format (Enterprise Agents only)
networkstringn/aname of the autonomous system in which the Agent is found (Enterprise Agents only)
lastSeendateTimen/ayyyy-MM-dd hh:mm:ss, expressed in UTC (Enterprise Agents only)
agentStatestringn/aOnline, Offline or Disabled
utilizationintegerpercentageshows overall utilization percentage of a cluster member
targetForTestsstringn/atarget IP address or domain name representing test destination when agent is acting as a test target in an agent-to-agent test

If an Enterprise Agent or a Cluster Member presents at least one error, an errorDetails field will be available, which is an array of errorDetail objects, containing the following fields:

FieldData TypeUnitsNotes
codestringn/aAGENT_VERSION_OUTDATED, APPLIANCE_VERSION_OUTDATED, BROWSERBOT_VERSION_OUTDATED, CLOCK_OFFSET, NAT_TRAVERSAL_ERROR, OS_END_OF_INSTALLATION_SUPPORT, OS_END_OF_SUPPORT, or OS_END_OF_LIFE
descriptionstringn/adetailed explanation of the error code

Header

HTTP/1.1 200 OK Server: nginx Date: Mon, 09 May 2016 16:04:24 GMT Content-Type: application/json Transfer-Encoding: chunked Connection: keep-alive Cache-Control: no-store X-Organization-Rate-Limit-Limit: 240 X-Organization-Rate-Limit-Remaining: 229 X-Organization-Rate-Limit-Reset: 1493294160 Strict-Transport-Security: max-age=31536000 X-Server-Name: 1-2

Body

{ "agents": [ { "agentId": 12, "agentName": "San Po Kong, Hong Kong", "agentType": "Cloud", "countryId": "HK", "groups": [ { "groupId": -2, "name": "Cloud" }, { "groupId": -3, "name": "IPv4 Compatible" } ], "location": "Hong Kong", "tests": [ { "alertsEnabled": 1, "apiLinks": [ { "href": "https://api.thousandeyes.com/v6/tests/822", "rel": "self" }, { "href": "https://api.thousandeyes.com/v6/dns/dnssec/822", "rel": "data" } ], "createdBy": "API Sandbox User (noreply@thousandeyes.com)", "createdDate": "2012-06-28 20:48:01", "domain": "thousandeyes.com A", "enabled": 1, "interval": 900, "liveShare": 0, "savedEvent": 0, "testId": 822, "testName": "thousandeyes.com A", "type": "dns-dnssec" }, ... ] } ] }

For error responses, see the response status codes documentation.

POST /v6/agents/{agentId}/update Updating an agent

Updates Enterprise Agent details. Users can update the agent parameters specified under Post Data section.

This endpoint can only be used for Enterprise Agents, and only for users in a role that permits modification of Enterprise Agents.

Important notes related to agent modification on tests:

  • if an agent is removed from a test, the modification date for tests using that agent at the time it was removed will be changed.
  • If an agent is removed from an entire account group, then all tests using this agent in the removed account group will be updated to reflect the removed agent.
  • If a removed agent is the final remaining agent on a test, then the test will be disabled when the agent is removed.

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

  • {agentId} corresponds the unique ID of an enterprise agent, obtained from the /agents endpoint

Post Data

When POSTing data to the /agents/{agentId}/update endpoint, users can update the following fields:

  • agentName string representation of an agent. No two agents can have the same display name.
  • enabled boolean representation of agent state. 0 to disable the agent, 1 to enable the agent.
  • accountGroups an array of accountGroup objects containing only an aid value, in the format { aid: integer }. See /accounts to pull a list of account IDs
  • tests an array of test objects containing only a testId value in the format { testId: integer }. See /tests to pull a list of tests available in the current account context.
  • ipv6Policy string representation of the IP version policy. Can be FORCE_IPV4, PREFER_IPV6 or FORCE_IPV6.
  • keepBrowserCache boolean representation of Keep browser cache state. 0 to disable, 1 to enable.
  • targetForTests string representation of target IP address or domain name, representing test destination when agent is acting as a test target in an agent-to-agent test

Example

$ curl https://api.thousandeyes.com/v6/agents/966/update.json \ -d '{ "agentName": "my updated agent name", "accountGroups": [ {"aid": 315}, {"aid": 362} ], "tests": [ {"testId": 12065} {"testId": 817}, ], "targetForTests":"1.2.3.4" }' \ -H "Content-Type: application/json" \ -u {email}:{authToken}

Response

If an agent is successfully edited, an HTTP/200 OK response will be returned, and the agent’s assigned accounts / tests will change; the newly updated agent data will be returned. See the example below:

FieldData TypeUnitsNotes
agentIdintegern/aunique ID of agent
agentNamestringn/adisplay name of the agent
locationstringn/alocation of the agent
countryIdstringn/aISO-3166-1 alpha-2 country code of the agent
prefixstringn/aNetwork prefix, expressed in CIDR format
keepBrowserCachebooleann/a1 for enabled, 0 for disabled
utilizationintegerpercentageshows overall utilization percentage
ipv6Policystringn/aIP version policy, can be FORCE_IPV4, PREFER_IPV6 or FORCE_IPV6
ipAddressesarrayn/aarray of ipAddress entries
groupsarrayn/aarray of label objects - see Labels for more information.
enabledbooleann/a1 for enabled, 0 for disabled
accountGroupsarrayn/alist of account groups to which the agent is assigned, expressed in the same format as /account-groups endpoint
testsarrayn/alist of tests assigned to the agent, expressed in the same format as /tests endpoint
networkstringn/aname of the autonomous system in which the Agent is found
agentTypestringn/aeither Cloud or Enterprise, shows the type of agent
lastSeendateTimen/ayyyy-MM-dd hh:mm:ss, expressed in UTC
agentStatestringn/aeither Online or Offline
targetForTestsstringn/atarget IP address or domain name representing test destination when agent is acting as a test target in an agent-to-agent test

Header

HTTP/1.1 200 OK Server: nginx Date: Mon, 09 May 2016 16:04:24 GMT Content-Type: application/json Transfer-Encoding: chunked Connection: keep-alive Cache-Control: no-store X-Organization-Rate-Limit-Limit: 240 X-Organization-Rate-Limit-Remaining: 229 X-Organization-Rate-Limit-Reset: 1493294160 Strict-Transport-Security: max-age=31536000 X-Server-Name: 1-2

Body

{ "agents": [ { "agentId": 966, "agentName": "ubuntu1404-x64", "location": "San Francisco Bay Area", "countryId": "US", "prefix": "50.128.0.0/9", "utilization": 1, "ipv6Policy": "FORCE_IPV4", "network": "Comcast Cable Communications, Inc. (AS 7922)", "agentType": "Enterprise", "lastSeen": "2015-05-14 23:18:00", "agentState": "Online", "keepBrowserCache": 1, "targetForTests": "1.1.1.1", "ipAddresses": [ "192.168.1.223" ], "publicIpAddresses": [ "50.184.189.59" ], "enabled": 1, "accountGroups": [ { "aid": 315, "accountGroupName": "Documentation" }, { "aid": 362, "accountGroupName": "Enterprise Agents Dashboard" } ], "tests": [ { "createdDate": "2015-02-03 21:55:13", "modifiedDate": "2015-05-14 23:18:03", "createdBy": "API Sandbox User (noreply@thousandeyes.com)", "modifiedBy": "API Sandbox User (noreply@thousandeyes.com)", "enabled": 1, "savedEvent": 0, "testId": 12065, "testName": "My Google DNS test", "type": "dns-server", "interval": 300, "domain": "google.com A", "networkMeasurements": 1, "mtuMeasurements": 1, "bandwidthMeasurements": 0, "bgpMeasurements": 1, "alertsEnabled": 0, "liveShare": 0, "recursiveQueries": 0, "dnsServers": [ { "serverId": 130, "serverName": "ns2.google.com." } ], "apiLinks": [...] }, { "enabled": 1, "testId": 817, "savedEvent": 0, "liveShare": 0, "testName": "http://www.thousandeyes.com", "type": "http-server", "interval": 900, "url": "http://www.thousandeyes.com", "networkMeasurements": 1, "createdBy": "API Sandbox User (noreply@thousandeyes.com)", "modifiedBy": "API Sandbox User (noreply@thousandeyes.com)", "createdDate": "2012-06-28 19:33:12", "modifiedDate": "2015-05-14 23:18:03", "apiLinks": [...] } ] } ] }

For error responses, see the response status codes documentation.

POST /v6/agents/{agentId}/delete Deleting an Agent

Deletes an Enterprise Agent from ThousandEyes. Note: this feature can only be used on Enterprise Agents.

Important notes related to agent removal:

  • if an agent is deleted, the modification date for tests using that agent at the time it was deleted will be changed.
  • If a deleted agent is the final remaining agent on a test, then the test will be disabled when the agent is removed.

Important note: if an agent is removed, it must be re-initialized to use the same machine again in different context. Virtual Appliances can be updated using the Reset State button in the Advanced tab of the agent management interface. Users running packaged versions of Linux will need to remove /var/lib/te-agent/\*.sqlite in order to reinitialize an agent.

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

  • {agentId} corresponds the unique ID of an enterprise agent, obtained from the /agents endpoint

Post Data

When POSTing data to the /agents/{agentId}/delete endpoint, users should specify an empty POST body.

Example

$ curl -i https://api.thousandeyes.com/v6/agents/966/delete.json \ -d '' \ -H "Content-Type: application/json" \ -u {email}:{authToken}

Response

If an agent is successfully deleted, an HTTP/204 No Content response will be returned, and an empty JSON response will be in the body of the response.

Header

HTTP/1.1 200 OK Server: nginx Date: Mon, 09 May 2016 16:04:24 GMT Content-Type: application/json Transfer-Encoding: chunked Connection: keep-alive Cache-Control: no-store X-Organization-Rate-Limit-Limit: 240 X-Organization-Rate-Limit-Remaining: 229 X-Organization-Rate-Limit-Reset: 1493294160 Strict-Transport-Security: max-age=31536000 X-Server-Name: 1-2

Body

  • The body of a delete request will be empty.

For error responses, see the response status codes documentation.

POST /v6/agents/{agentId}/add-to-cluster Agent cluster - Creating

Converts a standalone Enterprise Agent (or multiple) to an Enterprise Agent cluster.

This endpoint can only be used by users with the Edit agents in account group permission.

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

  • {agentId} in the request URL corresponds to the unique ID of an Enterprise Agent that is being converted to a cluster

Request notes:

  • {agentId} can be obtained from the /v6/agents endpoint

POST Data

  • The agentId present in the request URL must not be present in the POST body
  • Each agentId must represent an agent of the Enterprise type (as shown by the agentType field in agent details)

Example - converting a single agent

$ curl https://api.thousandeyes.com/v6/agents/64965/add-to-cluster.json \ -d '[]' \ -H "Content-Type: application/json" \ -u {email}:{authToken}

Example - converting multiple agents

$ curl https://api.thousandeyes.com/v6/agents/64965/add-to-cluster.json \ -d '[ 70002, 70003 ]' \ -H "Content-Type: application/json" \ -u {email}:{authToken}

Response

On successful cluster creation, the response will contain the following information:

  • An HTTP/200 OK status
  • The new cluster information will be provided in the response body
  • Each cluster member will get a unique ID within a cluster, called memberId
  • The memberId value is unrelated to the original agentId which was used in the request URL or POST body
  • The cluster name will be taken from the agent whole agentId is present in the request URL

Header

HTTP/1.1 200 OK Server: nginx Date: Mon, 09 May 2016 16:04:24 GMT Content-Type: application/json Transfer-Encoding: chunked Connection: keep-alive Cache-Control: no-store X-Organization-Rate-Limit-Limit: 240 X-Organization-Rate-Limit-Remaining: 229 X-Organization-Rate-Limit-Reset: 1493294160 Strict-Transport-Security: max-age=31536000 X-Server-Name: 1-2

Body

{ "agents": [ { "agentId": 64965, "agentName": "apidoc-cluster1", "agentType": "Enterprise Cluster", "clusterMembers": [ { "memberId": 80001, "name": "apidoc-cluster1-agent1", // ... }, { "memberId": 80002, "name": "apidoc-cluster1-agent2", // ... }, { "memberId": 80003, "name": "apidoc-cluster1-agent3", // ... } ], // ... } ] }

The example above is only showing contextually-relevant information. Full response metadata information is available in the agent details API endpoint description.

For error responses, see the response status codes documentation.

POST /v6/agents/{agentId}/add-to-cluster Agent cluster - Adding members

Adds a new member (or multiple members) to an Enterprise Agent cluster.

This endpoint can only be used by users with the Edit agents in account group permission.

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

  • {agentId} in the request URL corresponds to the unique ID of an Enterprise Agent cluster to which new agent(s) will be added.

Request notes:

  • {agentId} can be obtained from the /v6/agents endpoint.
  • If the agent represented by the {agentId} is not already a cluster, it is converted to a cluster.

POST Data

  • One or multiple (comma-separated) agentId values representing agents that should be added to the cluster, enclosed in square brackets.
  • Each agentId must represent an agent of the Enterprise type (as shown by the agentType field in agent details).

Example - adding one agent to a cluster

$ curl https://api.thousandeyes.com/v6/agents/64965/add-to-cluster.json \ -d '[ 80001 ]' \ -H "Content-Type: application/json" \ -u {email}:{authToken}

Example - adding multiple agents to a cluster

$ curl https://api.thousandeyes.com/v6/agents/64965/add-to-cluster.json \ -d '[ 80001, 80002, 80003 ]' \ -H "Content-Type: application/json" \ -u {email}:{authToken}

Response

On successful completion, the response will contain the following information:

  • An HTTP/200 OK status
  • The updated cluster information will be provided in the response body
  • Each new cluster member will get a unique ID within a cluster, called memberId
  • The memberId value is unrelated to the original agentId which was used in the request URL or POST body

Header

HTTP/1.1 200 OK Server: nginx Date: Mon, 09 May 2016 16:04:24 GMT Content-Type: application/json Transfer-Encoding: chunked Connection: keep-alive Cache-Control: no-store X-Organization-Rate-Limit-Limit: 240 X-Organization-Rate-Limit-Remaining: 229 X-Organization-Rate-Limit-Reset: 1493294160 Strict-Transport-Security: max-age=31536000 X-Server-Name: 1-2

Body

{ "agents": [ { "agentId": 64965, "agentName": "apidoc-cluster1", "agentType": "Enterprise Cluster", "clusterMembers": [ { "memberId": 80001, "name": "apidoc-cluster1-agent1", // ... }, { "memberId": 80002, "name": "apidoc-cluster1-agent2", // ... }, { "memberId": 80003, "name": "apidoc-cluster1-agent3", // ... } ], // ... } ] }

The example above is only showing contextually-relevant information. Full response metadata information is available in the agent details API endpoint description.

For error responses, see the response status codes documentation.

POST /v6/agents/{agentId}/remove-from-cluster Agent cluster - Removing members

Removes a member (or multiple members) from an Enterprise Agent cluster.

This endpoint can only be used for Enterprise Agent clusters, and only by users with the Edit agents in account group permission.

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

  • {agentId} in the request URL corresponds to the unique ID of an Enterprise Agent cluster from which agent(s) will being removed.

Request notes:

  • {agentId} can be obtained from the /v6/agents endpoint

POST Data

  • One or multiple (comma-separated) memberId values representing agents that should be removed from the cluster, enclosed in square brackets.
  • Cluster member IDs can be obtained from the /v6/agents API endpoint (the memberId field inside the clusterMembers array).

Example - removing a single member

$ curl https://api.thousandeyes.com/v6/agents/64965/remove-from-cluster.json \ -d '[ 80001 ]' \ -H "Content-Type: application/json" \ -u {email}:{authToken}

Example - removing multiple members

$ curl https://api.thousandeyes.com/v6/agents/64965/remove-from-cluster.json \ -d '[ 80002, 80003 ]' \ -H "Content-Type: application/json" \ -u {email}:{authToken}

Response

On successful completion, the response will contain the following information:

  • An HTTP/200 OK status
  • The updated cluster information will be provided in the response body, unless all members are removed from the cluster
  • Information about each removed member, now a standalone agent
  • Each non-last member that has been removed from the cluster will get a new agentId value, unrelated to the agentId value the agent held before joining the cluster. The new agentId value is unrelated to the memberId value the agent held while it was a member of the cluster.
  • If all members are removed from the cluster, the cluster itself is converted back to a standalone Enterprise Agent too. Such standalone agent inherits the old cluster’s agentId value. The last memberId listed in the POST body will be the one to inherit the cluster’s agentId value.

Header

HTTP/1.1 200 OK Server: nginx Date: Mon, 09 May 2016 16:04:24 GMT Content-Type: application/json Transfer-Encoding: chunked Connection: keep-alive Cache-Control: no-store X-Organization-Rate-Limit-Limit: 240 X-Organization-Rate-Limit-Remaining: 229 X-Organization-Rate-Limit-Reset: 1493294160 Strict-Transport-Security: max-age=31536000 X-Server-Name: 1-2

Body

{ "agents": [ { "agentId": 64965, "agentName": "apidoc-cluster1", "agentType": "Enterprise Cluster", "clusterMembers": [ { "memberId": 80001, "name": "apidoc-cluster1-agent1", } ], // ... }, { "agentId": 91112, "agentName": "apidoc-cluster1-agent2", "agentType": "Enterprise", // ... }, { "agentId": 91113, "agentName": "apidoc-cluster1-agent3", "agentType": "Enterprise", // ... } ] }

The example above is only showing contextually-relevant information. Full response metadata information is available in the agent details API endpoint description.

For error responses, see the response status codes documentation.

POST /v6/agents/{agentId}/remove-from-cluster Agent cluster - Converting to an agent

Converts a cluster with a single or multiple Enterprise Agent members back to a standalone Enterprise Agent(s).

This endpoint can only be used for Enterprise Agent clusters, and only by users with the Edit agents in account group permission.

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

  • {agentId} in the request URL corresponds to the unique ID of an Enterprise Agent cluster being converted to a standalone Enterprise Agent(s).

Request notes:

  • {agentId} can be obtained from the /v6/agents endpoint

POST Data

  • One or multiple (comma-separated) memberId values representing all the agents that belong to and will be removed from the cluster, enclosed in square brackets.
  • Cluster member IDs can be obtained from the /v6/agents API endpoint (the memberId field inside the clusterMembers array).

Example - a single remaining cluster member

$ curl https://api.thousandeyes.com/v6/agents/64965/remove-from-cluster.json \ -d '[ 80001 ]' \ -H "Content-Type: application/json" \ -u {email}:{authToken}

Example - disintegrating a cluster with multiple members

$ curl https://api.thousandeyes.com/v6/agents/64965/remove-from-cluster.json \ -d '[ 80001, 80002, 80003 ]' \ -H "Content-Type: application/json" \ -u {email}:{authToken}

Response

On successful completion, the response will contain the following information:

  • An HTTP/200 OK status
  • Information about each removed member, now a standalone agent
  • Each non-last member that has been removed from the cluster will get a new agentId value, unrelated to the agentId value the agent held before joining the cluster. The new agentId value is unrelated to the memberId value the agent held while it was a member of the cluster.
  • If all members are removed from the cluster, the cluster itself is converted back to a standalone Enterprise Agent too. Such standalone agent inherits the old cluster’s agentId value. The last memberId listed in the POST body will be the one to inherit the cluster’s agentId value.

Header

HTTP/1.1 200 OK Server: nginx Date: Mon, 09 May 2016 16:04:24 GMT Content-Type: application/json Transfer-Encoding: chunked Connection: keep-alive Cache-Control: no-store X-Organization-Rate-Limit-Limit: 240 X-Organization-Rate-Limit-Remaining: 229 X-Organization-Rate-Limit-Reset: 1493294160 Strict-Transport-Security: max-age=31536000 X-Server-Name: 1-2

Body

{ "agents": [ { "agentId": 91111, "agentName": "apidoc-cluster1-agent1", "agentType": "Enterprise", // ... }, { "agentId": 91112, "agentName": "apidoc-cluster1-agent2", "agentType": "Enterprise", // ... }, { "agentId": 64965, "agentName": "apidoc-cluster1", "agentType": "Enterprise", // ... } ] }

The example above is only showing contextually-relevant information. Full response metadata information is available in the agent details API endpoint description.

For error responses, see the response status codes documentation.

GET /v6/bgp-monitors BGP Monitor list

Returns a list of all BGP monitors available to your account in ThousandEyes, including both public and private feeds.

Optional (Querystring) 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/bgp-monitors.json \ -u {email}:{authToken}

Response

Sends back an array of BGP monitors, including monitorId, which can be used by other areas of the API. The example below shows both a public and private BGP monitor.

FieldData TypeUnitsNotes
monitorIdintegern/aunique ID of BGP monitor
ipAddressstringn/aIP address of the BGP monitor
networkstringn/aname of the autonomous system in which the monitor is found
monitorTypestringn/aeither Public or Private, shows the type of monitor
monitorNamestringn/adisplay name of the BGP monitor

Header

HTTP/1.1 200 OK Server: nginx Date: Mon, 09 May 2016 16:04:24 GMT Content-Type: application/json Transfer-Encoding: chunked Connection: keep-alive Cache-Control: no-store X-Organization-Rate-Limit-Limit: 240 X-Organization-Rate-Limit-Remaining: 229 X-Organization-Rate-Limit-Reset: 1493294160 Strict-Transport-Security: max-age=31536000 X-Server-Name: 1-2

Body

{ "bgpMonitors": [ { "ipAddress": "2001:240:100:ff::2497:2", "monitorId": 64, "monitorName": "Tokyo-3", "monitorType": "Public", "network": "Internet Initiative Japan Inc. (AS 2497)" }, { "ipAddress": "4.69.184.193", "monitorId": 1, "monitorName": "Seattle, WA", "monitorType": "Public", "network": "Level 3 Communications, Inc. (AS 3356)" }, ... ] }

For error responses, see the response status codes documentation.

GET /v6/agent-notification-rules Agent Notification Rules

Returns a list of all agent notification rules configured under your account in ThousandEyes.

Optional (Querystring) 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/agent-notification-rules.json \ -u {email}:{authToken}

Response

Sends back an object with one property. agentAlertRules is a collection of agent notification rule objects. Each object has the following properties:

FieldData TypeUnitsNotes
ruleIdintegern/aunique ID of the agent notification rule
ruleNamestringn/aname of the agent notification rule
expressionstringn/astring expression of agent notification rule
notifyOnClearbooleann/a1 to send notification when notification clears
defaultbooleann/awhen set to 1, agent notification rule will be automatically included on all new Enterprise agents

Header

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

Body

{ "agentAlertRules": [ { "default": 1, "expression": "((clockOffset >= 60 s))", "notifyOnClear": 0, "ruleId": 1234, "ruleName": "Default Agent Clock Offset Notification" }, { "default": 1, "expression": "((lastContact >= 30 min))", "notifyOnClear": 0, "ruleId": 1244, "ruleName": "Default Agent Offline Notification" } ] }

For error responses, see the response status codes documentation.

GET /v6/agent-notification-rules/{ruleId} Agent Notification Rule Detail

Returns details of an agent notification rule, including agents it is assigned to.

Optional (Querystring) 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/agent-notification-rules/1234.json \ -u {email}:{authToken}

Response

Sends back an object with one property. agentAlertRules is a collection of agent notification rule objects. Each object has the following properties:

FieldData TypeUnitsNotes
ruleIdintegern/aunique ID of the agent notification rule
ruleNamestringn/aname of the agent notification rule
expressionstringn/astring expression of agent notification rule
notifyOnClearbooleann/a1 to send notification when notification clears
defaultbooleann/awhen set to 1, agent notification rule will be automatically included on all new Enterprise agents
agentscollectionn/alist of agent objects this rule is assigned to
notificationsobjectn/aalert notification object; see Alert notification integrations.

Header

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

Body

{ "agentAlertRules": [ { "default": 1, "expression": "((lastContact >= 30 min))", "notifyOnClear": 0, "ruleId": 1234, "ruleName": "Default Agent Offline Notification", "notifications": { "email": { "message": "Test", "recipient": [ "noreply@thousandeyes.com" ] }, "thirdParty": [ { "channel": "@primoz", "integrationId": "sl-57", "integrationName": "Slack Primoz", "integrationType": "SLACK", "target": "https://hooks.slack.com/services/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" } ], "webhook": [ { "integrationId": "wb-41", "integrationName": "Test Hooks", "integrationType": "WEBHOOK", "target": "https://example.com/hook" } ] }, "agents": [ { "agentId": 3113, "agentName": "csc-statuspage", "agentState": "Disabled", "agentType": "Enterprise", "countryId": "US", "createdDate": "2017-03-31 04:33:52", "enabled": 0, "hostname": "csc-statuspage", "ipAddresses": [ "10.100.100.200" ], "ipv6Policy": "FORCE_IPV4", "keepBrowserCache": 0, "lastSeen": "2017-04-05 01:14:05", "location": "San Francisco Bay Area", "network": "Cogent Communications (AS 174)", "prefix": "38.0.0.0/8", "publicIpAddresses": [ "38.122.0.1" ], }, { "agentId": 3116, "agentName": "csc-ubuntu-docker", "agentState": "Disabled", "agentType": "Enterprise", "countryId": "US", "createdDate": "2017-03-31 04:34:11", "enabled": 0, "hostname": "csc-ubuntu-docker", "ipAddresses": [ "10.100.20.201" ], "ipv6Policy": "FORCE_IPV4", "keepBrowserCache": 0, "lastSeen": "2017-04-20 14:54:39", "location": "San Francisco Bay Area", "network": "Cogent Communications (AS 174)", "prefix": "38.0.0.0/8", "publicIpAddresses": [ "38.122.0.1" ], } ] } ] }

For error responses, see the response status codes documentation.

© 2023 ThousandEyes. All rights reserved.