ThousandEyes Tests API

openapi: 3.2.0
info:
  version: 7.0.100
  title: Tests API
  description: '**Note:** The Page Load Tests, API Tests, and Web Transaction Tests APIs are not available for ThousandEyes for Government instance.


    This API allows you to list, create, edit, and delete Network and Application Synthetics tests.

    '
  x-provenance:
    method: harvested
    authored_by: Cisco ThousandEyes
    harvested_by: API Evangelist
    harvested_on: '2026-08-19'
    first_party: true
    provider_published: true
    source_host: pubhub.devnetcloud.com
    note: 27 OpenAPI 3.0 documents (26 per-area plus a unified 326-operation document) served anonymously from Cisco's DevNet CDN. api.thousandeyes.com itself 401s every path, so the contract is public while the API host is gated.
  x-evidence:
  - type: source
    url: https://pubhub.devnetcloud.com/media/000-v7-apis/docs/reference/
  - type: source
    url: https://developer.cisco.com/docs/thousandeyes/
servers:
- description: ThousandEyes API production URL
  url: https://api.thousandeyes.com/v7
security:
- BearerAuth: []
tags:
- name: Tests
  description: Get all tests
paths:
  /tests:
    get:
      tags:
      - Tests
      summary: List configured tests
      operationId: getTests
      description: 'Returns configured tests and saved events.


        **Note**: **Saved Events** are now called **Private Snapshots** in the user interface. This change does not affect API.

        '
      parameters:
      - $ref: '#/components/parameters/AccountGroupId'
      responses:
        '200':
          description: OK
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/Tests'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
        '429':
          $ref: '#/components/responses/429'
        '500':
          $ref: '#/components/responses/500'
        '502':
          $ref: '#/components/responses/502'
        default:
          $ref: '#/components/responses/GeneralError'
  /tests/{testId}/history:
    get:
      tags:
      - Tests
      summary: Get test version history
      operationId: getTestVersionHistory
      description: Retrieve the version history of a specific test.
      parameters:
      - $ref: '#/components/parameters/TestIdPath'
      - $ref: '#/components/parameters/AccountGroupId'
      - name: limit
        in: query
        description: The maximum number of version history entries to return. If not specified, the default is 50 or the total number of available versions, whichever is fewer.
        required: false
        schema:
          type: integer
          default: 50
          maximum: 500
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TestVersionHistoryResponse'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
        '500':
          $ref: '#/components/responses/500'
components:
  parameters:
    TestIdPath:
      name: testId
      description: Test ID
      required: true
      in: path
      schema:
        type: string
        example: '202701'
    AccountGroupId:
      name: aid
      in: query
      description: A unique identifier associated with your account group. You can retrieve your `AccountGroupId` from the `/account-groups` endpoint. Note that you must be assigned to the target account group. Specifying this parameter without being assigned to the target account group will result in an error response.
      required: false
      schema:
        type: string
        example: '1234'
  schemas:
    TestCreatedDate:
      type: string
      format: date-time
      description: UTC created date (ISO date-time format).
      example: '2022-07-17T22:00:54Z'
      readOnly: true
    TestCreatedBy:
      type: string
      description: User that created the test.
      example: user@user.com
      readOnly: true
    TestLinks:
      type: object
      description: A list of links that can be accessed to get more information
      properties:
        self:
          $ref: '#/components/schemas/TestSelfLink'
        testResults:
          $ref: '#/components/schemas/TestResults'
      readOnly: true
    SimpleTest:
      description: Each test includes additional fields depending on its `type`. Refer `/tests/{type}` endpoint to know the set of fields returned by a given `type`.
      additionalProperties: true
      type: object
      properties:
        interval:
          $ref: '#/components/schemas/TestInterval'
        alertsEnabled:
          type: boolean
          description: Indicates if alerts are enabled.
          example: true
        enabled:
          $ref: '#/components/schemas/Enabled'
        createdBy:
          $ref: '#/components/schemas/TestCreatedBy'
        createdDate:
          $ref: '#/components/schemas/TestCreatedDate'
        description:
          type: string
          description: A description of the test.
          example: ThousandEyes Test
        liveShare:
          type: boolean
          description: Indicates if the test is shared with the account group.
          example: false
          readOnly: true
        modifiedBy:
          type: string
          description: User that modified the test.
          example: user@user.com
          readOnly: true
        modifiedDate:
          type: string
          format: date-time
          description: UTC last modification date (ISO date-time format).
          readOnly: true
          example: '2022-07-17T22:00:54Z'
        savedEvent:
          type: boolean
          description: 'Indicates if the test is a saved event.


            **Note**: **Saved Events** are now called **Private Snapshots** in the user interface. This change does not affect API.

            '
          readOnly: true
        testId:
          type: string
          description: Each test is assigned an unique ID; this is used to access test information and results from other endpoints.
          readOnly: true
          example: '281474976710706'
        testName:
          type: string
          description: The name of the test. Test name must be unique.
          example: ThousandEyes Test
        type:
          $ref: '#/components/schemas/TestType'
        _links:
          $ref: '#/components/schemas/TestLinks'
    Enabled:
      type: boolean
      description: Test is enabled.
      example: true
      default: true
    TestType:
      type: string
      enum:
      - api
      - agent-to-agent
      - agent-to-server
      - bgp
      - http-server
      - page-load
      - web-transactions
      - ftp-server
      - dns-trace
      - dns-server
      - dnssec
      - sip-server
      - voice
      description: This is a read only value, as test type is implicit in the test creation url.
      readOnly: true
      example: agent-to-server
    UnauthorizedError:
      type: object
      properties:
        error:
          type: string
          example: invalid_token
        error_description:
          type: string
          example: Invalid access token
    Link:
      type: object
      description: A hyperlink from the containing resource to a URI.
      required:
      - href
      properties:
        href:
          type: string
          description: Its value is either a URI [RFC3986] or a URI template [RFC6570].
          example: https://api.thousandeyes.com/v7/link/to/resource/id
        templated:
          type: boolean
          description: Should be true when the link object's "href" property is a URI template.
        type:
          type: string
          description: Used as a hint to indicate the media type expected when dereferencing the target resource.
        deprecation:
          type: string
          description: Its presence indicates that the link is to be deprecated at a future date. Its value is a URL that should provide further information about the deprecation.
        name:
          type: string
          description: Its value may be used as a secondary key for selecting link objects that share the same relation type.
        profile:
          type: string
          description: A URI that hints about the profile of the target resource.
        title:
          type: string
          description: Intended for labelling the link with a human-readable identifier
        hreflang:
          type: string
          description: Indicates the language of the target resource
    TestResults:
      type: array
      description: Reference to the test results.
      items:
        $ref: '#/components/schemas/Link'
      example:
      - href: https://api.thousandeyes.com/v7/test-results/281474976710706/network
      - href: https://api.thousandeyes.com/v7/test-results/281474976710706/path-vis
    TestVersionHistory:
      type: object
      properties:
        versionTimestamp:
          type: string
          format: date-time
          description: Timestamp when this version was created.
          example: '2022-07-17T22:00:54Z'
        testId:
          type: string
          description: The unique identifier of the test.
          example: '474276'
        createdBy:
          type: string
          description: The user who created the version.
          example: user (user@user.com)
        versionId:
          type: string
          description: The unique identifier for a specific version of the test settings.
          example: '1234'
    Tests:
      type: object
      properties:
        tests:
          type: array
          items:
            $ref: '#/components/schemas/SimpleTest'
        _links:
          $ref: '#/components/schemas/SelfLinks'
    TestInterval:
      type: integer
      enum:
      - 60
      - 120
      - 300
      - 600
      - 900
      - 1800
      - 3600
      description: Interval between test runs in seconds.
      default: 60
      example: 60
    Error:
      type: object
      properties:
        type:
          type: string
          description: A URI reference that identifies the problem type. When this member is not present, its value is assumed to be "about:blank".
        title:
          type: string
          description: A short, human-readable summary of the problem type.
        status:
          type: integer
          description: The HTTP status code generated by the origin server for this occurrence of the problem.
        detail:
          type: string
          description: A human-readable explanation specific to this occurrence of the problem.
        instance:
          type: string
          description: A URI reference that identifies the specific occurrence of the problem.
    TestSelfLink:
      allOf:
      - $ref: '#/components/schemas/Link'
      - description: Reference to the test.
        example:
          href: https://api.thousandeyes.com/v7/tests/{type}/281474976710706
    SelfLinks:
      type: object
      description: A links object containing the self link.
      readOnly: true
      properties:
        self:
          $ref: '#/components/schemas/Link'
    TestVersionHistoryResponse:
      type: object
      properties:
        _links:
          $ref: '#/components/schemas/SelfLinks'
        testVersionHistory:
          type: array
          items:
            $ref: '#/components/schemas/TestVersionHistory'
      additionalProperties: false
  responses:
    '502':
      description: Bad Gateway
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Error'
    GeneralError:
      description: An error occurred
    '429':
      description: Exhausted rate limit for the organization
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Error'
    '404':
      description: Not found
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            type: about:blank
            title: URI Resource Not Found
            status: 404
            detail: Details explaining if the 404 error is related to an invalid URI or a wrong ID
            instance: /v7
    '500':
      description: Internal server error
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            type: about:blank
            title: Internal server error
            status: 500
            detail: Optional detail about the internal error message.
            instance: /v7
    '403':
      description: Insufficient permissions to query endpoint
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Error'
    '401':
      description: Unauthorized
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/UnauthorizedError'
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: Bearer authentication token
externalDocs:
  description: Find out more about Network and Application Synthetics tests
  url: https://docs.thousandeyes.com/product-documentation/internet-and-wan-monitoring/tests#cloud-and-enterprise-agent-based-tests