Programmatic Access to XTC

XTC 76 shipped with the first part of an API to get access to selected XTC resources and trigger selected operations from automated environments. This part provides remote access to load tests. This includes

  • listing and inspecting load tests,
  • duplicating and executing load tests, and
  • downloading result and report archives.

Administrators can manage API client credentials in both organization and projects. These credentials are used to obtain a temporary access token needed to make the actual API requests.

Managing API Client Credentials

To allow remote access to your load tests, you must first create client credentials. You can do this in your organization or in your projects.

To create client credentials in your organization, go to Configuration > Integrations > API Client Credentials and click the Add button. You will need to specify a name and an optional expiration date. You will also need to select an API version and the scopes (purposes) for which these credentials will be used. API credentials with an expiration date will expire at the end of the specified day (UTC).

Dialog to add new client credentials to an organization.

Submit the dialog and XTC will show you the generated client secret, which you can now copy to a safe place. You will not be able to access it again, so if you lose or forget the secret, fresh credentials have to be created.

The client credentials defined in your organization are valid for accessing resources in your organization and, by default, in all of your projects. However, org credentials can be disabled in your project(s). Go to Configuration > Integrations > API Client Credentials in a project and disable the org client credentials for that project if necessary.

Enabling/disabling org credentials in a project.

In the same location, you can also create project-level API client credentials, similar to the org-level credentials as described above. These credentials will only allow access to the resources of that project.

Whether you use org-level or project-level credentials, or a mix of both, depends on your security requirements.

Obtaining an Access Token

To actually use the API, you need an access token. To get one in an automated way, use the tool of your choice, but we will demonstrate this using curl:

curl -X POST \
     -d "client_id=<your-client-id>" \
     -d "client_secret=<your-client-secret>" \
     -d "grant_type=client_credentials" \

As you can see, you need to pass both the client ID and secret, but also the grant type client_credentials and the scopes for which this token will be used. The scope list may contain fewer scopes than defined in the credentials, but no more.

Now run the curl command. XTC will return a JSON response. Look for the access_token field. Note that this access token expires automatically after one hour, but you can create new tokens at any time.

Making API Calls

Now we are ready to make our first API call: listing all the load tests in a project. Don’t forget to provide the access token and the short names of your organization and project (you can find these in the org’s or project’s configuration):

curl -X GET \
     -H "Authorization: Bearer <your-jwt-access-token>" \

If all went well, you should see a JSON response with all your load tests printed to the console.

For your convenience, here is a list of current API endpoints and what they are used for:

Project API Endpoints

  • Retrieve the details of a project:
    GET /public/api/v1/orgs/<org-short-name>/projects/<project-short-name> (requires scope PROJECT_DETAILS)
  • List all the projects of an organization:
    GET /public/api/v1/orgs/<org-short-name>/projects (requires scope PROJECT_LIST)

Load Test API Endpoints

  • Copy the specified load test and run the copy:
    GET /public/api/v1/orgs/<org-short-name>/projects/<project-short-name>/loadTests/<load-test-number>/runCopy (requires scope LOADTEST_COPY_RUN)
  • List the details of a certain load test:
    GET /public/api/v1/orgs/<org-short-name>/projects/<project-short-name>/loadTests/<load-test-number> (requires scope LOADTEST_DETAILS)
  • List all load tests in a project:
    GET /public/api/v1/orgs/<org-short-name>/projects/<project-short-name>/loadTests(requires scope LOADTEST_LIST)
  • Download the specified report archive:
    GET /public/api/v1/orgs/<org-short-name>/projects/<project-short-name>/loadTests/<load-test-number>/reports/<report-number>/download(requires scope LOADTEST_REPORT_DOWNLOAD)
  • Download the specified result archive:
    GET /public/api/v1/orgs/<org-short-name>/projects/<project-short-name>/loadTests/<load-test-number>/results/<result-number>/download(requires scope LOADTEST_RESULT_DOWNLOAD)
  • List the status of a certain load test:
    GET /public/api/v1/orgs/<org-short-name>/projects/<project-short-name>/loadTests/<load-test-number>/status(requires scope LOADTEST_STATUS)

API Documentation and Explorer

For a complete formal documentation, visit https://xtc.xceptance.com/public/api/json or https://xtc.xceptance.com/public/api/yaml. There you will find the OpenAPI-compliant specification of all existing API endpoints, including their respective request and response types, in either JSON or YAML format.

In addition to the OpenApi specification in JSON or YAML format, XTC also presents the definition of its public APIs as a browsable documentation, the XTC API Explorer: this includes the help texts as well as the input and output data types for each API endpoint.

API Explorer displaying information about the load test details request.

You can also try API calls directly from the API Explorer. For this to work, you will need to configure authorization information. To do this, go to Authentication in the menu. You can then provide either a valid bearer access token or specify client ID and secret as well as the required scopes for XTC to create a new bearer access token on your behalf using the OAuth procedure.

Handling authentication in the API explorer: an access token has been created for the entered client ID and secret.

Last modified February 7, 2024