---
title: "Create and start a new test run with the given test run Id."
method: PATCH
path: "/test-runs/{testRunId}"
tags: ["TestRun"]
---

# Create and start a new test run with the given test run Id.

`PATCH /test-runs/{testRunId}`

Create and start a new test run with the given test run Id.

## Path parameters

- `testRunId` string, required

## Query parameters

- `api-version` string, required
- `oldTestRunId` string

## Response `200`

The request has succeeded.

- TestRun — Load test run model
  - `testRunId` string, required — Unique test run identifier for the load test run, must contain only lower-case alphabetic, numeric, underscore or hyphen characters.
  - `passFailCriteria` PassFailCriteria — Pass fail criteria for a test.
    - `passFailMetrics` object — Map of id and pass fail metrics { id : pass fail metrics }.
  - `secrets` object — Secrets can be stored in an Azure Key Vault or any other secret store. If the secret is stored in an Azure Key Vault, the value should be the secret identifier and the type should be AKV_SECRET_URI. If the secret is stored elsewhere, the secret value should be provided directly and the type should be SECRET_VALUE.
  - `certificate` CertificateMetadata — Certificates metadata
    - `value` string — The value of the certificate for respective type
    - `type` 'AKV_CERT_URI' — Types of certificates supported.
    - `name` string — Name of the certificate.
  - `environmentVariables` object — Environment variables which are defined as a set of <name,value> pairs.
  - `errorDetails` ErrorDetails[] — Error details if there is any failure in load test run
    - `message` string — Error details in case test run was not successfully run.
  - `testRunStatistics` object — Test run statistics. Key is the sampler name and value is the set of statistics for performance metrics like response time, throughput, etc. from the load test run. The sampler name is the same as the name mentioned in the test script. Sampler name "Total" represents the aggregated statistics of all the samplers.
  - `loadTestConfiguration` LoadTestConfiguration — Configurations for the load test.
    - `engineInstances` integer — The number of engine instances to execute load test. Supported values are in range of 1-400. Required for creating a new test.
    - `splitAllCSVs` boolean — If false, Azure Load Testing copies and processes your input files unmodified across all test engine instances. If true, Azure Load Testing splits the CSV input data evenly across all engine instances. If you provide multiple CSV files, each file will be split evenly.
    - `quickStartTest` boolean — If true, optionalLoadTestConfig is required and JMX script for the load test is not required to upload.
    - `optionalLoadTestConfig` OptionalLoadTestConfiguration — Configuration for quick load test
      - `endpointUrl` string — Test URL. Provide the complete HTTP URL. For example, https://contoso-app.azurewebsites.net/login
      - `virtualUsers` integer — No of concurrent virtual users.
      - `rampUpTime` integer — Ramp up time in seconds.
      - `duration` integer — Test run duration in seconds.
  - `testArtifacts` TestRunArtifacts — Collection of test run artifacts
    - `inputArtifacts` TestRunInputArtifacts — The input artifacts for the test run.
      - `configFileInfo` TestRunFileInfo — Test run file info.
        - `fileName` string, required — Name of the file.
        - `url` string, uri — File URL.
        - `fileType` 'JMX_FILE' | 'USER_PROPERTIES' | 'ADDITIONAL_ARTIFACTS' — Types of file supported.
        - `expireDateTime` string, date-time — Expiry time of the file (RFC 3339 literal format)
        - `validationStatus` 'NOT_VALIDATED' | 'VALIDATION_SUCCESS' | 'VALIDATION_FAILURE' | 'VALIDATION_INITIATED' | 'VALIDATION_NOT_REQUIRED' — File status.
        - `validationFailureDetails` string — Validation failure error details
      - `testScriptFileInfo` TestRunFileInfo — Test run file info.
        - `fileName` string, required — Name of the file.
        - `url` string, uri — File URL.
        - `fileType` 'JMX_FILE' | 'USER_PROPERTIES' | 'ADDITIONAL_ARTIFACTS' — Types of file supported.
        - `expireDateTime` string, date-time — Expiry time of the file (RFC 3339 literal format)
        - `validationStatus` 'NOT_VALIDATED' | 'VALIDATION_SUCCESS' | 'VALIDATION_FAILURE' | 'VALIDATION_INITIATED' | 'VALIDATION_NOT_REQUIRED' — File status.
        - `validationFailureDetails` string — Validation failure error details
      - `userPropFileInfo` TestRunFileInfo — Test run file info.
        - `fileName` string, required — Name of the file.
        - `url` string, uri — File URL.
        - `fileType` 'JMX_FILE' | 'USER_PROPERTIES' | 'ADDITIONAL_ARTIFACTS' — Types of file supported.
        - `expireDateTime` string, date-time — Expiry time of the file (RFC 3339 literal format)
        - `validationStatus` 'NOT_VALIDATED' | 'VALIDATION_SUCCESS' | 'VALIDATION_FAILURE' | 'VALIDATION_INITIATED' | 'VALIDATION_NOT_REQUIRED' — File status.
        - `validationFailureDetails` string — Validation failure error details
      - `inputArtifactsZipFileInfo` TestRunFileInfo — Test run file info.
        - `fileName` string, required — Name of the file.
        - `url` string, uri — File URL.
        - `fileType` 'JMX_FILE' | 'USER_PROPERTIES' | 'ADDITIONAL_ARTIFACTS' — Types of file supported.
        - `expireDateTime` string, date-time — Expiry time of the file (RFC 3339 literal format)
        - `validationStatus` 'NOT_VALIDATED' | 'VALIDATION_SUCCESS' | 'VALIDATION_FAILURE' | 'VALIDATION_INITIATED' | 'VALIDATION_NOT_REQUIRED' — File status.
        - `validationFailureDetails` string — Validation failure error details
      - `additionalFileInfo` TestRunFileInfo[] — Additional supported files for the test run
        - `fileName` string, required — Name of the file.
        - `url` string, uri — File URL.
        - `fileType` 'JMX_FILE' | 'USER_PROPERTIES' | 'ADDITIONAL_ARTIFACTS' — Types of file supported.
        - `expireDateTime` string, date-time — Expiry time of the file (RFC 3339 literal format)
        - `validationStatus` 'NOT_VALIDATED' | 'VALIDATION_SUCCESS' | 'VALIDATION_FAILURE' | 'VALIDATION_INITIATED' | 'VALIDATION_NOT_REQUIRED' — File status.
        - `validationFailureDetails` string — Validation failure error details
    - `outputArtifacts` TestRunOutputArtifacts — The output artifacts for the test run.
      - `resultFileInfo` TestRunFileInfo — Test run file info.
        - `fileName` string, required — Name of the file.
        - `url` string, uri — File URL.
        - `fileType` 'JMX_FILE' | 'USER_PROPERTIES' | 'ADDITIONAL_ARTIFACTS' — Types of file supported.
        - `expireDateTime` string, date-time — Expiry time of the file (RFC 3339 literal format)
        - `validationStatus` 'NOT_VALIDATED' | 'VALIDATION_SUCCESS' | 'VALIDATION_FAILURE' | 'VALIDATION_INITIATED' | 'VALIDATION_NOT_REQUIRED' — File status.
        - `validationFailureDetails` string — Validation failure error details
      - `logsFileInfo` TestRunFileInfo — Test run file info.
        - `fileName` string, required — Name of the file.
        - `url` string, uri — File URL.
        - `fileType` 'JMX_FILE' | 'USER_PROPERTIES' | 'ADDITIONAL_ARTIFACTS' — Types of file supported.
        - `expireDateTime` string, date-time — Expiry time of the file (RFC 3339 literal format)
        - `validationStatus` 'NOT_VALIDATED' | 'VALIDATION_SUCCESS' | 'VALIDATION_FAILURE' | 'VALIDATION_INITIATED' | 'VALIDATION_NOT_REQUIRED' — File status.
        - `validationFailureDetails` string — Validation failure error details
  - `testResult` 'PASSED' | 'NOT_APPLICABLE' | 'FAILED' — Test result based on pass/fail criteria.
  - `virtualUsers` integer — Number of virtual users, for which test has been run.
  - `displayName` string — Display name of a testRun.
  - `testId` string — Associated test Id.
  - `description` string — The test run description.
  - `status` 'ACCEPTED' | 'NOTSTARTED' | 'PROVISIONING' | 'PROVISIONED' | 'CONFIGURING' | 'CONFIGURED' | 'EXECUTING' | 'EXECUTED' | 'DEPROVISIONING' | 'DEPROVISIONED' | 'DONE' | 'CANCELLING' | 'CANCELLED' | 'FAILED' | 'VALIDATION_SUCCESS' | 'VALIDATION_FAILURE' — Test run status.
  - `startDateTime` string, date-time — The test run start DateTime(RFC 3339 literal format).
  - `endDateTime` string, date-time — The test run end DateTime(RFC 3339 literal format).
  - `executedDateTime` string, date-time — Test run initiated time.
  - `portalUrl` string — Portal url.
  - `duration` integer — Test run duration in milliseconds.
  - `subnetId` string — Subnet ID on which the load test instances should run.
  - `createdDateTime` string, date-time — The creation datetime(RFC 3339 literal format).
  - `createdBy` string — The user that created.
  - `lastModifiedDateTime` string, date-time — The last Modified datetime(RFC 3339 literal format).
  - `lastModifiedBy` string — The user that last modified.

## Other responses

- `201` — The request has succeeded and a new resource has been created as a result.
- `default` — An unexpected error response.

---

[API](https://skmtc.dev/azure/apis/loadtestservice-loadtesting.md) · [All operations](https://skmtc.dev/azure/apis/loadtestservice-loadtesting/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/azure/loadtestservice-loadtesting/revisions/e991fe514f8b/schema)