Agent & Test Groups

GET /groups Groups List

Returns a list of all groups configured in ThousandEyes. This includes both Agent and Test groups.

Optional Parameters

  • format=json|xml optional, specifies the format of output requested. See Output Formats for more information
  • aid={aid} optional, specifies the account group context for the request.

Request

  • no request body

Response

Sends back an array of groups configured in the platform. Metadata of the response is returned according to the following table:

FieldData TypeUnitsNotes
namestringn/aName of the group
groupIdintegern/aUnique ID of the group; this number is negative for built-in groups. Query the /groups/{id} endpoint to see a list of group members
typestringn/aeither “tests” or “agents”, indicates the type of group. To show only this group type, query the /groups/{type} endpoint.
builtinintegern/a1 for built-in groups, and 0 for user-created groups. Note that built-in groups are read-only.

Example

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

HTTP/1.1 200 OK Server: nginx Date: Tue, 15 Mar 2016 00:20:26 GMT Content-Type: application/json;charset=UTF-8 Transfer-Encoding: chunked Connection: keep-alive Strict-Transport-Security: max-age=31536000 X-Server-Name: 1-5

Body

{ "groups": [ { "name": "Shared", "groupId": -8, "type": "tests", "builtin": 1 }, { "name": "Saved Event", "groupId": -9, "type": "tests", "builtin": 1 }, { "name": "Infrastructure tests", "groupId": 961, "type": "tests", "builtin": 0 }, { "name": "IPv6", "groupId": -4, "type": "agents", "builtin": 1 }, { "name": "Proxied", "groupId": -5, "type": "agents", "builtin": 1 }, { "name": "My group", "groupId": 714, "type": "agents", "builtin": 0 } ] }

For error responses, see the response status codes documentation.

GET /groups/{groupType} Groups List by Type

Returns a list of all tests of the type specified, configured in ThousandEyes.

Optional Parameters

  • format=json|xml optional, specifies the format of output requested. See Output Formats for more information
  • aid={aid} optional, specifies the account group context for the request.

Request

  • {groupType} corresponds to the following options:

    • agents
    • tests
  • no request body

Response

Sends back an array of groups configured for the type specified in the platform. Metadata of the response is returned according to the following table:

FieldData TypeUnitsNotes
namestringn/aName of the group
groupIdintegern/aUnique ID of the group; this number is negative for built-in groups. Query the /groups/{id} endpoint to see a list of group members
typestringn/aeither “tests” or “agents”, indicates the type of group.
builtinintegern/a1 for built-in groups, and 0 for user-created groups. Note that built-in groups are read-only.

Example

$curl https://api.thousandeyes.com/groups/tests.json \ -u noreply@thousandeyes.com:g351mw5xqhvkmh1vq6zfm51c62wyzib2

HTTP/1.1 200 OK Server: nginx Date: Tue, 15 Mar 2016 00:20:26 GMT Content-Type: application/json;charset=UTF-8 Transfer-Encoding: chunked Connection: keep-alive Strict-Transport-Security: max-age=31536000 X-Server-Name: 1-5

Body

{ "groups": [ { "name": "Shared", "groupId": -8, "type": "tests", "builtin": 1 }, { "name": "Saved Event", "groupId": -9, "type": "tests", "builtin": 1 }, { "name": "Dave's tests", "groupId": 958, "type": "tests", "builtin": 0 }, { "name": "Infrastructure tests", "groupId": 961, "type": "tests", "builtin": 0 } ] }

For error responses, see the response status codes documentation.

GET /groups/{groupId} Group Details

Returns details for a group configured in ThousandEyes.

Optional Parameters

  • format=json|xml optional, specifies the format of output requested. See Output Formats for more information
  • aid={aid} optional, specifies the account group context for the request.

Request

  • {type} the group type (either agents or tests)
  • {groupId} the ID of the group to retrieve
  • no request body

Response

Returns the group details. Metadata of the response is returned according to the following table:

FieldData TypeUnitsNotes
namestringn/aName of the group
groupIdintegern/aUnique ID of the group; this number is negative for built-in groups. Query the /groups/{id} endpoint to see a list of group members
typestringn/aeither “tests” or “agents”, indicates the type of group.
builtinintegern/a1 for built-in groups, and 0 for user-created groups. Note that built-in groups are read-only.
agentsarray of agent objectsn/aAgent objects are shown for a group of agents type only. See Agent Metadata for more details on agent objects.
testsarray of test objectsn/aTest objects are shown for a group of tests type only. See Test Metadata for more detail on test objects.

Example

$curl https://api.thousandeyes.com/groups/-2.json \ -u noreply@thousandeyes.com:g351mw5xqhvkmh1vq6zfm51c62wyzib2

HTTP/1.1 200 OK Server: nginx Date: Tue, 15 Mar 2016 00:20:26 GMT Content-Type: application/json;charset=UTF-8 Transfer-Encoding: chunked Connection: keep-alive Strict-Transport-Security: max-age=31536000 X-Server-Name: 1-5

Body

{ "groups": [ { "name": "Cloud", "groupId": -2, "type": "agents", "builtin": 1, "agents": [ { "agentId": 6, "agentName": "Fremont, CA (v6)", "location": "San Francisco Bay Area", "countryId": "US", "ipAddresses": [ "2600:3c01::f03c:91ff:feae:4f96" ], "agentType": "Cloud" }, { "agentId": 11, "agentName": "London, UK", "location": "City of London, United Kingdom", "countryId": "GB", "ipAddresses": [ "176.58.99.46", "178.79.138.106" ], "agentType": "Cloud" }, { "agentId": 19, "agentName": "Amsterdam, Netherlands", "location": "Netherlands", "countryId": "NL", "ipAddresses": [ "95.85.55.177" ], "agentType": "Cloud" } ] } ] }

For error responses, see the response status codes documentation.

GET /groups/{groupType}/{groupId} Group Details (by group type)

Returns a list of all groups configured in ThousandEyes. This includes both Agent and Test groups.

Optional Parameters

  • format=json|xml optional, specifies the format of output requested. See Output Formats for more information
  • aid={aid} optional, specifies the account group context for the request.

Request

  • {groupType} corresponds to the following options:

    • agents
    • tests
  • {groupId} the ID of the group to retrieve

  • no request body

Response

Returns the group details. Metadata of the response is returned according to the following table:

FieldData TypeUnitsNotes
namestringn/aName of the group
groupIdintegern/aUnique ID of the group; this number is negative for built-in groups. Query the /groups/{id} endpoint to see a list of group members
typestringn/aeither “tests” or “agents”, indicates the type of group requested.
builtinintegern/a1 for built-in groups, and 0 for user-created groups. Note that built-in groups are read-only.
agentsarray of agent objectsn/aAgent objects are shown for a group of agents type only. See Agent Metadata for more details on agent objects.
testsarray of test objectsn/aTest objects are shown for a group of tests type only. See Test Metadata for more detail on test objects.

Example

$curl https://api.thousandeyes.com/groups/tests/958.json \ -u noreply@thousandeyes.com:g351mw5xqhvkmh1vq6zfm51c62wyzib2

HTTP/1.1 200 OK Server: nginx Date: Tue, 15 Mar 2016 00:20:26 GMT Content-Type: application/json;charset=UTF-8 Transfer-Encoding: chunked Connection: keep-alive Strict-Transport-Security: max-age=31536000 X-Server-Name: 1-5

Body

{ "groups": [ { "name": "Dave's tests", "groupId": 958, "type": "tests", "builtin": 0, "tests": [ { "createdDate": "2014-06-13 04:01:07", "modifiedDate": "2015-01-06 19:27:03", "createdBy": "Dave Fraleigh (dave@thousandeyes.com)", "modifiedBy": "Dave Fraleigh (dave@thousandeyes.com)", "enabled": 1, "savedEvent": 0, "testId": 6600, "testName": "Bozo BGP test 1", "type": "bgp", "prefix": "38.122.0.0/16", "alertsEnabled": 0, "liveShare": 0, "includeCoveredPrefixes": 0, "apiLinks": [ { "rel": "self", "href": "https://api.thousandeyes.com/v5/tests/6600" }, { "rel": "data", "href": "https://api.thousandeyes.com/v5/net/bgp-metrics/6600" } ] } ] } ] }

For error responses, see the response status codes documentation.

POST /groups/{groupType}/new Creating a Group

Creates a new group in ThousandEyes, based on properties provided in the POST data. In order to create a new group, the user attempting the creation must have sufficient privileges to create groups.

Regular users are blocked from using any of the POST-based methods.

Note: When creating or updating a group and assigning agents or tests, the user needs permission to modify the objects being added.

Optional Parameters

  • format=json|xml optional, specifies the format of output requested. See Output Formats for more information
  • aid={aid} optional, specifies the account group context for the request.

Request

  • {groupType} corresponds to the following options:

    • agents
    • tests
  • POST body includes the following:

    • name: the name of the new group - this must be unique.
    • tests: an array of testId objects, if the groupType specified is tests
    • agents: an array of agentId objects, if the groupType specified is agents

See the example below for POST body syntax

Response

If successful, sends back an HTTP/201 CREATED response code, and the new object metadata (just as if you’d called /groups/{id} with the new group ID). Metadata per the following table:

FieldData TypeUnitsNotes
namestringn/aName of the group
groupIdintegern/aUnique ID of the group; this number is negative for built-in groups. Query the /groups/{id} endpoint to see a list of group members
typestringn/aeither “tests” or “agents”, indicates the type of group.
builtinintegern/a1 for built-in groups, and 0 for user-created groups. Note that built-in groups are read-only.
agentsarray of agent objectsn/aAgent objects are shown for a group of agents type only. See Agent Metadata for more details on agent objects.
testsarray of test objectsn/aTest objects are shown for a group of tests type only. See Test Metadata for more detail on test objects.

Example

$curl https://api.thousandeyes.com/groups/tests/new \ -d '{ "name": "Dave's new group", "tests": [{"testId": 5048},{"testId": 6600}]}' \ -H "Content-Type: application/json" \ -u noreply@thousandeyes.com:g351mw5xqhvkmh1vq6zfm51c62wyzib2

HTTP/1.1 201 CREATED Server: nginx Date: Tue, 15 Mar 2016 00:20:26 GMT Content-Type: application/json;charset=UTF-8 Transfer-Encoding: chunked Connection: keep-alive Strict-Transport-Security: max-age=31536000 X-Server-Name: 1-5

Body

{ "groups": [ { "name": "Dave's new group", "groupId": 1374, "type": "tests", "builtin": 0, "tests": [ { "createdDate": "2014-06-13 04:01:07", "modifiedDate": "2015-01-06 19:27:03", "createdBy": "Dave Fraleigh (dave@thousandeyes.com)", "modifiedBy": "Dave Fraleigh (dave@thousandeyes.com)", "enabled": 1, "savedEvent": 0, "testId": 6600, "testName": "Bozo BGP test 1", "type": "bgp", "prefix": "38.122.0.0/16", "alertsEnabled": 0, "liveShare": 0, "includeCoveredPrefixes": 0, "apiLinks": [...] }, { "createdDate": "2014-03-18 20:05:03", "modifiedDate": "2015-07-31 17:20:54", "createdBy": "Dave Fraleigh (dave@thousandeyes.com)", "modifiedBy": "Dave Fraleigh (dave@thousandeyes.com)", "enabled": 0, "savedEvent": 0, "testId": 5048, "testName": "www.yahoo.com A", "type": "dns-server", "interval": 300, "domain": "www.yahoo.com A", "networkMeasurements": 1, "mtuMeasurements": 1, "bandwidthMeasurements": 0, "bgpMeasurements": 1, "alertsEnabled": 0, "liveShare": 0, "recursiveQueries": 1, "dnsServers": [...], "apiLinks": [...] } ] } ] }

For error responses, see the response status codes documentation.

POST /groups/{groupId}/update Updating a Group

Updates a group in ThousandEyes, based on properties provided in the POST data. In order to edit a group, the user must have access to the target group, and have access to modify the objectst that the group contains. For example, to update an agent group, the user needs the Edit Agents permission assigned to their role.

Regular users are blocked from using any of the POST-based methods.

Optional Parameters

  • format=json|xml optional, specifies the format of output requested. See Output Formats for more information
  • aid={aid} optional, specifies the account group context for the request.

Request

  • groupId the group that you wish to update, found in either the /groups or the /groups/{groupType} endpoint.

Response

Returns the group details, following update. Metadata of the response is returned according to the following table:

FieldData TypeUnitsNotes
namestringn/aName of the group
groupIdintegern/aUnique ID of the group; this number is negative for built-in groups. Query the /groups/{id} endpoint to see a list of group members
typestringn/aeither “tests” or “agents”, indicates the type of group.
builtinintegern/a1 for built-in groups, and 0 for user-created groups. Note that built-in groups are read-only.
agentsarray of agent objectsn/aAgent objects are shown for a group of agents type only. See Agent Metadata for more details on agent objects.
testsarray of test objectsn/aTest objects are shown for a group of tests type only. See Test Metadata for more detail on test objects.

Example

$curl https://api.thousandeyes.com/groups/1356/update \ -d '{ "name": "Dave's new group", "tests": [{"testId": 5048 },{"testId": 6600 }]}' \ -H "Content-Type: application/json" \ -u noreply@thousandeyes.com:g351mw5xqhvkmh1vq6zfm51c62wyzib2

HTTP/1.1 200 OK Server: nginx Date: Tue, 23 Mar 2016 00:20:26 GMT Content-Type: application/json;charset=UTF-8 Transfer-Encoding: chunked Connection: keep-alive Strict-Transport-Security: max-age=31536000 X-Server-Name: 1-5

Body

{ "groups": [ { "name": "Dave's new group", "groupId": 1356, "type": "tests", "builtin": 0, "tests": [ { "createdDate": "2014-06-13 04:01:07", "modifiedDate": "2015-01-06 19:27:03", "createdBy": "Dave Fraleigh (dave@thousandeyes.com)", "modifiedBy": "Dave Fraleigh (dave@thousandeyes.com)", "enabled": 1, "savedEvent": 0, "testId": 6600, "testName": "Bozo BGP test 1", "type": "bgp", "prefix": "38.122.0.0/16", "alertsEnabled": 0, "liveShare": 0, "includeCoveredPrefixes": 0, "apiLinks": [...] }, { "createdDate": "2014-03-18 20:05:03", "modifiedDate": "2015-07-31 17:20:54", "createdBy": "Dave Fraleigh (dave@thousandeyes.com)", "modifiedBy": "Dave Fraleigh (dave@thousandeyes.com)", "enabled": 0, "savedEvent": 0, "testId": 5048, "testName": "www.yahoo.com A", "type": "dns-server", "interval": 300, "domain": "www.yahoo.com A", "networkMeasurements": 1, "mtuMeasurements": 1, "bandwidthMeasurements": 0, "bgpMeasurements": 1, "alertsEnabled": 0, "liveShare": 0, "recursiveQueries": 1, "dnsServers": [...], "apiLinks": [...] } ] } ] }

For error responses, see the response status codes documentation.

POST /groups/{groupId}/delete Deleting a Group

Deletes a group currently configured in ThousandEyes. Note that built-in (negative groupId numbers) are not eligible for deletion.

Optional Parameters

  • format=json|xml optional, specifies the format of output requested. See Output Formats for more information
  • aid={aid} optional, specifies the account group context for the request.

Request

  • groupId the group that you wish to delete, found in either the /groups or the /groups/{groupType} endpoint.
  • No request body

Response

Returns an HTTP/204 NO CONTENT response.

Example

$curl https://api.thousandeyes.com/groups/1356/delete \ -d '' \ -H "Content-Type: application/json" \ -u noreply@thousandeyes.com:g351mw5xqhvkmh1vq6zfm51c62wyzib2

HTTP/1.1 204 NO CONTENT Server: nginx Date: Tue, 22 Mar 2016 20:02:42 GMT Content-Type: application/json;charset=UTF-8 Transfer-Encoding: chunked Connection: keep-alive Strict-Transport-Security: max-age=31536000 X-Server-Name: 1-5

Body

  • The body of a delete request will be empty.

For error responses, see the response status codes documentation.