API - Test runs

Scott Sherwood

Updated September 22, 2026 07:38

List

Description: Provides a paginated list of all test runs within a given project.

Endpoint: <base_url>/projects/{project_id}/runs.json

Request: GET

Formats supported: JSON

Params:

project_id - {Integer} The associated project ID (Required)
page - {Integer} of the page (Default: 1)
user_id - {Integer} Search for test runs that are associated with the given user id
status - {Integer} Search for runs with a given status (Default: Null)
- Options:
order - {Integer} of how to order the list (Default: 0)

Options:

0 - Created at
1 - Name

Response

{
  "pagination": { .... },
  "runs": [
    { .... },
    { .... }
  ]
}

Example ruby request

HTTParty.get('https://api.testlodge.com/v1/account/1/projects/1/runs.json', query: { order: 1 })

Example Response

Response code: 200

{
  "pagination": { 
    "total_entries":2,
    "total_pages":1,
    "current_page":1,
    "next_page":null,
    "previous_page":null,
    "per_page":20 
  },
  "runs":[{
    "id":1,
    "name":"Example run",
    "being_saved":false,
    "incomplete_number":20,
    "passed_number":10,
    "skipped_number":0,
    "failed_number":1,
    "user_id":null,
    "project_id":1,
    "executed_plan_id":null,
    "created_at":"2014-02-26T14:33:58Z",
    "updated_at":"2014-02-26T14:33:58Z"
  },
  { .... }]
}

Show

Description: Get the details for a test run.

Endpoint: <base_url>/projects/{project_id}/runs/{id}.json

Request: GET

Formats supported: JSON

Params:

project_id - {Integer} The associated project ID (Required)
id - {Integer} The test run ID (Required)

Response

{ .... }

Example ruby request

HTTParty.get('https://api.testlodge.com/v1/account/1/projects/1/runs/1.json')

Example Response

Response code: 200

{
  "id":1,
  "name":"Example run",
  "being_saved":false,
  "incomplete_number":20,
  "passed_number":10,
  "skipped_number":0,
  "failed_number":1,
  "user_id":null,
  "project_id":1,
  "executed_plan_id":null,
  "created_at":"2014-02-26T14:33:58Z",
  "updated_at":"2014-02-26T14:33:58Z"
}

Create

Description: Create a new test run.

Endpoint: <base_url>/projects/{project_id}/runs.json

Request: POST

Formats supported: JSON

Params:

project_id - {Integer} The associated project ID (Required)
run:

name - {String} The test run name (Required)
plan_id - {Integer} The test plan that you would like associated with this run
user_id - {Integer} The user who you would like to be assigned to the run
step_ids - {Array of integers} The test case ids that you would like to be included in the run (step_ids or suite_ids is Required)
suite_ids - {Array of integers} The test suite ids that you would like to be included in the run (step_ids or suite_ids is Required)
config_option_combinations - {Hash of arrays} Run configuration options that should be applied to a given test suite.
- {suite_id} - {Array of strings} run configuration option id, optionally separated by an '_' for a combination. (e.g. 12_14)

Response

{ .... }

Example ruby request

HTTParty.post('https://api.testlodge.com/v1/account/1/projects/1/runs.json', body: { 
  run: { 
    name: 'Example run', 
    plan_id: 1,
    step_ids: [1,2,4,5]
    suite_ids: [10],
    config_option_combinations: { 10: ['12_14', '12_15'] }
  } 
})

Example Response

Response code: 201

Notes: The being_saved attribute should be checked, and attributes such as incomplete_number will only be set once being_saved = false, and the run is fully created.

{
  "id":1,
  "name":"Example run",
  "being_saved":true,
  "incomplete_number":null,
  "passed_number":null,
  "skipped_number":null,
  "failed_number":null,
  "user_id":null,
  "project_id":1,
  "executed_plan_id":1,
  "created_at":"2014-02-26T14:33:58Z",
  "updated_at":"2014-02-26T14:33:58Z"
}

Update

Description: Update a new test run.

Endpoint: <base_url>/projects/{project_id}/runs/{id}.json

Request: PATCH

Formats supported: JSON

Params:

project_id - {Integer} The associated project ID (Required)
id - {Integer} The test run ID (Required)
run:

name - {String} The test test run
plan_id - {Integer} The test plan that you would like associated with this run
user_id - {Integer} The user who you would like to be assigned to the run

Response

{ .... }

Example ruby request

HTTParty.patch('https://api.testlodge.com/v1/account/1/projects/1/runs/1.json', body: { 
  run: { 
    name: 'New name'
  } 
})

Example Response

Response code: 200

{
  "id":1,
  "name":"New name",
  "being_saved":false,
  "incomplete_number":20,
  "passed_number":0,
  "skipped_number":0,
  "failed_number":0,
  "user_id":null,
  "project_id":1,
  "executed_plan_id":null,
  "created_at":"2014-02-26T14:33:58Z",
  "updated_at":"2014-02-26T14:33:58Z"
}

Delete

Description: Delete a test run.

Endpoint: <base_url>/projects/{project_id}/runs/{id}.json

Request: DELETE

Formats supported: JSON

Params:

project_id - {Integer} The associated project ID (Required)
id - {Integer} The test run ID (Required)

Response

empty

Example ruby request

HTTParty.delete('https://api.testlodge.com/v1/account/1/projects/1/runs/1.json')

Example Response

Response code: 204

empty