# REST API

Before getting started you’ll need to generate an API token, take a look how to generate it [here](https://docs.loadmill.com/integrations/api-tokens).

## Run Test Suite

<mark style="color:green;">`POST`</mark> `https://app.loadmill.com/api/v1/test-suites/:id/run`

Run a predefined test suite

#### Path Parameters

| Name | Type   | Description                    |
| ---- | ------ | ------------------------------ |
| id   | string | UUID of the Test Suite to run. |

#### Query Parameters

| Name          | Type    | Description                                                                                              |
| ------------- | ------- | -------------------------------------------------------------------------------------------------------- |
| forceAllFlows | boolean | Default = false - running only flows marked for execution with CI toggle. If true - executing all flows. |

#### Headers

| Name                                            | Type   | Description                                                                             |
| ----------------------------------------------- | ------ | --------------------------------------------------------------------------------------- |
| Authorization<mark style="color:red;">\*</mark> | string | Authentication token - you can generate it in the "User menu"> "Settings" > "Security". |

#### Request Body

| Name                  | Type   | Description                                                                                                                                                           |
| --------------------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| additionalDescription | string | Add an additional description at the end of the current suite's description                                                                                           |
| overrideParameters    | object | <p><code>name: value</code></p><p>pairs to override the default parameters values of this specific run. i.e.</p><p><code>{{"paramName1":"paramVal1"}, ...}</code></p> |

{% tabs %}
{% tab title="200 Test suite has launched successfully." %}

```
{testSuiteRunId: "running-uuid"}
```

{% endtab %}
{% endtabs %}

## Get Test Suite Run (Test Suite results)

<mark style="color:blue;">`GET`</mark> `https://app.loadmill.com/api/v1/test-suites-runs/:id`

Get a launched Test Suite results

#### Path Parameters

| Name | Type   | Description                                                                   |
| ---- | ------ | ----------------------------------------------------------------------------- |
| id   | string | The running uuid. You get this ID in the response when launching a Test Suite |

#### Headers

| Name          | Type   | Description                                                                            |
| ------------- | ------ | -------------------------------------------------------------------------------------- |
| Authorization | string | Authentication token - you can generate it in the "User menu"> "Settings" > "Security" |

{% tabs %}
{% tab title="200 " %}

```
{
  "id": "test suite run uuid,
  "description": "test suite run description",
  "startTime": timestamp,
  "endTime": timestamp | null,
  "conf": {
    "useCookies": true
  },
  "status": "PASSED" | "FAILED" | "RUNNING",
  "displayName": "Display name of the executing user",
  "testSuiteId": "origin test suite uuid" | null (if deleted),
  "testSuiteFlowRuns": [
    {
      "id": "test suite flow run uuid",
      "startTime": timestamp,
      "endTime": timestamp | null,
      "conf": {}, // executed flow conf 
      "description": "Flow description",
      "status": "PASSED" | "FAILED" | "RUNNING",
      "numOfRequests": number of requests in this flow conf,
      "avgResTime": 199, // in ms
      "duration": "422 ms"
    }
  ],
  "progress": "1/1", // flows progress
  "successRate": "100%", // flows success rate
  "avgResTime": "422 ms"
} 
```

{% endtab %}
{% endtabs %}

## Get Test Suite Flow Run

<mark style="color:blue;">`GET`</mark> `https://app.loadmill.com/api/v1/test-suites-runs/flows/:id`

Get Test Suite Flow results

#### Path Parameters

| Name | Type   | Description                                                                    |
| ---- | ------ | ------------------------------------------------------------------------------ |
| id   | string | The flow running uuid. You get this ID when fetching the Test Suite Run entity |

#### Headers

| Name          | Type   | Description                                                                            |
| ------------- | ------ | -------------------------------------------------------------------------------------- |
| Authorization | string | Authentication token - you can generate it in the "User menu"> "Settings" > "Security" |

{% tabs %}
{% tab title="200 " %}

```
{
  "id": "test suite flow run uuid",
  "description": "Flow description",
  "conf": {...}, // the executed flow conf
  "status": "PASSED" | "FAILED" | "RUNNING",
  "startTime": timestamp,
  "testSuiteFlowId": "origin test suite flow uuid" | null (if deleted),
  "testSuiteId": "origin test suite uuid" | null (if deleted)
}
```

{% endtab %}
{% endtabs %}

## Stop Test Suite Run

<mark style="color:orange;">`PUT`</mark> `https://app.loadmill.com/api/v1/test-suites-runs/:id`

Stop a launched Test Suite

#### Path Parameters

| Name | Type   | Description                                                                                                                                                                                                |
| ---- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| id   | string | <p>The Test Suite Run uuid. You can get this ID in the response when getting the Test Suite Run (<https://docs.loadmill.com/integrations/rest-api#get-test-suite-run-test-suite-results>).</p><p>\</p></p> |

#### Query Parameters

| Name           | Type   | Description                                                                                |
| -------------- | ------ | ------------------------------------------------------------------------------------------ |
| forceFail=true | string | Using this filter option the user can stop the Test Suite Run and put its status to FAILED |

#### Headers

| Name          | Type   | Description                                                                            |
| ------------- | ------ | -------------------------------------------------------------------------------------- |
| Authorization | string | Authentication token - you can generate it in the "User menu"> "Settings" > "Security" |

#### Request Body

| Name                  | Type   | Description                                                |
| --------------------- | ------ | ---------------------------------------------------------- |
| additionalDescription | string | Will be added at the end of the Test Suite Run description |

{% tabs %}
{% tab title="200 Test Suite Run has been successfully stopped." %}

```
```

{% endtab %}
{% endtabs %}

## Create Load Test

<mark style="color:green;">`POST`</mark> `https://app.loadmill.com/api/v1/tests`

Create a load test from load test configuration

#### Headers

| Name          | Type   | Description                                                                            |
| ------------- | ------ | -------------------------------------------------------------------------------------- |
| Authorization | string | Authentication token - you can generate it in the "User menu"> "Settings" > "Security" |

#### Request Body

| Name   | Type   | Description                                                                                                                                                                                                            |
| ------ | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| config | object | A load test configuration. The JSON test configuration may be exported from the Loadmill test editor or from an old test run. See a config example here - <https://docs.loadmill.com/load-testing/configuration-files> |

{% tabs %}
{% tab title="200 " %}

```
{ testId: "load test id" }
```

{% endtab %}
{% endtabs %}

## Create Load from Test Suite Flow

<mark style="color:green;">`POST`</mark> `https://app.loadmill.com/api/v1/test-suites/:suiteId/flows/:flowId/loads`

Create a draft load test from a test suite flow

#### Path Parameters

| Name    | Type   | Description                                            |
| ------- | ------ | ------------------------------------------------------ |
| suiteId | string | The suite UUID in which the flow resides               |
| flowId  | string | The flow UUID. The load will be created from this flow |

#### Headers

| Name          | Type   | Description                                                                            |
| ------------- | ------ | -------------------------------------------------------------------------------------- |
| Authorization | string | Authentication token - you can generate it in the "User menu"> "Settings" > "Security" |

#### Request Body

| Name            | Type   | Description                                                                                                                        |
| --------------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------- |
| loadTestOptions | object | Optional load test configuration options. If not provided, default values will be used. See the table below for available options. |

#### Load Test Option

| Name              | Type    | Description                                                        |
| ----------------- | ------- | ------------------------------------------------------------------ |
| targetedCountries | array   | Array of country codes for targeted geographic distribution.       |
| monitoredEnv      | string  | Environment identifier for monitoring purposes                     |
| rampUp            | number  | Ramp-up time in seconds. Default value is used if not specified    |
| alwaysDistributed | boolean | Whether to always use distributed load testing. Default: `false`   |
| useStaticIp       | boolean | Whether to use static IP addresses. Default: `false`               |
| sensitiveData     | boolean | Whether the test contains sensitive data. Default: `false`         |
| duration          | number  | Test duration in seconds. Default value is used if not specified   |
| concurrency       | number  | Number of concurrent users. Default value is used if not specified |
| rps               | number  | Requests per second. Default value is used if not specified        |

{% tabs %}
{% tab title="200 " %}

```
{ testId: "load test id" }
```

{% endtab %}
{% endtabs %}

## Set Flow

<mark style="color:purple;">`PATCH`</mark> `https://app.loadmill.com/api/v1/test-suites/:suiteId/flows/:flowId/pools`

Create a parameter pool and attach it to a flow

#### Path Parameters

| Name    | Type   | Description                                                     |
| ------- | ------ | --------------------------------------------------------------- |
| suiteId | string | The suite UUID in which the flow resides                        |
| flowId  | string | The flow UUID. The parameter pool will be attached to this flow |

#### Query Parameters

| Name | Type   | Description                     |
| ---- | ------ | ------------------------------- |
| name | string | name of the parameter pool data |

#### Headers

| Name          | Type   | Description                                                                            |
| ------------- | ------ | -------------------------------------------------------------------------------------- |
| content-type  | string | must be text/csv                                                                       |
| Authorization | string | Authentication token - you can generate it in the "User menu"> "Settings" > "Security" |

#### Request Body

| Name | Type   | Description                 |
| ---- | ------ | --------------------------- |
| body | string | The CSV data in CSV format. |

{% tabs %}
{% tab title="200 " %}

```
```

{% endtab %}
{% endtabs %}

## Run Load Test

<mark style="color:orange;">`PUT`</mark> `https://app.loadmill.com/api/v1/tests/:id/load`

Run an existing load test. Be aware that a given load test can be run only once. In order to rerun it you will have to recreate it.

#### Path Parameters

| Name | Type   | Description  |
| ---- | ------ | ------------ |
| id   | string | Load test ID |

#### Headers

| Name          | Type   | Description                                                                            |
| ------------- | ------ | -------------------------------------------------------------------------------------- |
| Authorization | string | Authentication token - you can generate it in the "User menu"> "Settings" > "Security" |

{% tabs %}
{% tab title="200 " %}

```
```

{% endtab %}
{% endtabs %}

## Get Load Test

<mark style="color:blue;">`GET`</mark> `https://app.loadmill.com/api/v1/tests/:id`

Returns the Load Test data. If the Load Test has ended it would contain its result.

#### Path Parameters

| Name | Type   | Description  |
| ---- | ------ | ------------ |
| id   | string | Load test ID |

#### Headers

| Name          | Type   | Description                                                                            |
| ------------- | ------ | -------------------------------------------------------------------------------------- |
| Authorization | string | Authentication token - you can generate it in the "User menu"> "Settings" > "Security" |

{% tabs %}
{% tab title="200 " %}

```
{
  "id": "load test id",
  "startTime": timestamp,
  "endTime": timestamp,
  "usedSeconds": "total seconds used by all sessions",
  "description": "load description",
  "conf": {}, // load test configuraion
  "result": "aborted" | "done" | "failed",
  "failedIterations": number,
  "successfulIterations": number
}
```

{% endtab %}
{% endtabs %}

## Labels

<mark style="color:blue;">`GET`</mark> `https://app.loadmill.com/api/v1/labels`

Returns all user's team's labels

#### Query Parameters

| Name                             | Type   | Description                                                                                                 |
| -------------------------------- | ------ | ----------------------------------------------------------------------------------------------------------- |
| filter=active\&filter=evaluating | string | Using this filter option the user can get only the labels who are attached to flows with a specific status. |

#### Headers

| Name          | Type   | Description                                                                             |
| ------------- | ------ | --------------------------------------------------------------------------------------- |
| Authorization | string | Authentication token - you can generate it in the "User menu"> "Settings" > "Security". |

{% tabs %}
{% tab title="200 " %}

```
{
  "teamLabels": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174001",
      "description": "my label",
    },
    {
      "id": "123e4567-e89b-12d3-a456-426614174002",
      "description": "another label",
    }
  ]
}
```

{% endtab %}
{% endtabs %}

## Run Test Plan

<mark style="color:green;">`POST`</mark> `https://app.loadmill.com/api/v1/test-plans/:test-plan-id/run`

Run a predefined test plan

#### Path Parameters

| Name                                           | Type   | Description                  |
| ---------------------------------------------- | ------ | ---------------------------- |
| test-plan-id<mark style="color:red;">\*</mark> | String | UUID of the Test Plan to run |

#### Headers

| Name                                            | Type   | Description                                                                             |
| ----------------------------------------------- | ------ | --------------------------------------------------------------------------------------- |
| Authorization<mark style="color:red;">\*</mark> | String | Authentication token - you can generate it in the "User menu"> "Settings" > "Security". |

#### Request Body

| Name                  | Type   | Description                                                                                                                                                                                             |
| --------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| additionalDescription | String | Add an additional description at the end of the current plan's description                                                                                                                              |
| labels                | Array  | <p>An array of strings representing labels to filter the test plan execution. i.e. <code>\["label1", "label2"]</code></p><p>Only test flows with matching labels will be included in the execution.</p> |
| labelsExpression      | String | String representing of labels expression to filter the test plan execution. i.e. `(label1 \| label2) & !label3` An expression may contain the characters `( ) & \| ! (`                                 |
| overrideParameters    | Object | `name:value` pairs to override the default parameters values of this specific run. i.e. `{{"paramName1":"paramVal1"}, ...}`                                                                             |
| pool                  | String | Execute tests from a dedicated agent's pool (when using private agent)                                                                                                                                  |
| parallel              | String | Set the concurrency of a running test suites in a test plan. Max concurrency is 10                                                                                                                      |
| maxFlakyFlowRetries   | String | The maximum number of retries for flaky test flows. If a test flow fails due to flakiness, it will be retried up to the specified number of times                                                       |

{% tabs %}
{% tab title="200: OK return the an object with testPlanRunId property in it" %}

{% endtab %}
{% endtabs %}

## Get Test Plan Run

<mark style="color:blue;">`GET`</mark> `https://app.loadmill.com/api/v1/test-plans-runs/:plan-run-id`

Get the Test Plan Run result

#### Path Parameters

| Name                                               | Type   | Description                                           |
| -------------------------------------------------- | ------ | ----------------------------------------------------- |
| test-plan-run-id<mark style="color:red;">\*</mark> | String | test plan run id - given when launching the test plan |

#### Headers

| Name          | Type   | Description                                                                             |
| ------------- | ------ | --------------------------------------------------------------------------------------- |
| Authorization | String | Authentication token - you can generate it in the "User menu"> "Settings" > "Security". |

{% tabs %}
{% tab title="200: OK " %}

{% endtab %}
{% endtabs %}

## Re-run Test Plan

<mark style="color:green;">`POST`</mark> `https://app.loadmill.com/api/v1/test-plans-runs/:test-plan-run-id/re-run`

Re-run a test plan run

#### Path Parameters

| Name                                               | Type   | Description                         |
| -------------------------------------------------- | ------ | ----------------------------------- |
| test-run-plan-id<mark style="color:red;">\*</mark> | String | UUID of the Test Plan Run to re-run |

#### Query Parameters

| Name       | Type    | Description                                                                 |
| ---------- | ------- | --------------------------------------------------------------------------- |
| onlyFailed | boolean | Default = false. When set to true only failed or stopped suites will re-run |

#### Headers

| Name                                            | Type   | Description                                                                             |
| ----------------------------------------------- | ------ | --------------------------------------------------------------------------------------- |
| Authorization<mark style="color:red;">\*</mark> | String | Authentication token - you can generate it in the "User menu"> "Settings" > "Security". |

{% tabs %}
{% tab title="200: OK return an object with testPlanRunId property in it" %}

{% endtab %}
{% endtabs %}

## Get test suites

<mark style="color:blue;">`GET`</mark> `https://app.loadmill.com/api/v1/test-suites`

Returns a list of test suites

#### Query Parameters

| Name        | Type   | Description                                                                |
| ----------- | ------ | -------------------------------------------------------------------------- |
| search      | String | filter test suites by the given search phrase                              |
| rowsPerPage | String | How many suites to return, Values might be `10, 25, 50, 100` default to 10 |

#### Headers

| Name                                            | Type   | Description                                                                             |
| ----------------------------------------------- | ------ | --------------------------------------------------------------------------------------- |
| Authorization<mark style="color:red;">\*</mark> | String | Authentication token - you can generate it in the "User menu"> "Settings" > "Security". |

{% tabs %}
{% tab title="200: OK Returns an object with an array property of testSuites" %}

{% endtab %}
{% endtabs %}

## Get Test Plans

<mark style="color:blue;">`GET`</mark> `https://app.loadmill.com/api/v1/test-plans`

Returns a list of test plans

#### Query Parameters

| Name        | Type   | Description                                                                |
| ----------- | ------ | -------------------------------------------------------------------------- |
| search      | String | filter test suites by the given search phrase                              |
| rowsPerPage | String | How many suites to return, Values might be `10, 25, 50, 100` default to 10 |

#### Headers

| Name                                            | Type   | Description                                                                             |
| ----------------------------------------------- | ------ | --------------------------------------------------------------------------------------- |
| Authorization<mark style="color:red;">\*</mark> | String | Authentication token - you can generate it in the "User menu"> "Settings" > "Security". |


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.loadmill.com/auth/rest-api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.