Test plans

Test plans help you to group, organize, and track linked test runs. Our REST API provides comprehensive endpoints for handling test plans, enabling you to automate and streamline your testing workflow. With these endpoints, in a project, you can create test plans and access list of test runs linked to a test plan.

Get the list of test plans

GET /api/v2/projects/{project_id}/test-plans

Invoking this API will fetch the list of test plans in a project. You will need the id of the project to access its list of test plans.

This list is paginated. For more information, see Pagination.

To return only the test plans that carry specific custom field values, pass the q[tp_custom_fields] query parameter. Its value is a JSON object keyed by the custom field id, with an array of values for each field. For dropdown and multi_dropdown fields, pass the option labels. Get the field id from the custom fields API with entity_type=TestPlan.

A test plan matches when it carries any of the values listed for a field. When you list more than one field, a test plan must match every field. Without the parameter, the response lists all test plans.

Request parameters

Request

curl -u "YOUR_USERNAME:YOUR_ACCESS_KEY" \
https://test-management.browserstack.com/api/v2/projects/PR-1/test-plans

Request with a custom field filter

curl -u "YOUR_USERNAME:YOUR_ACCESS_KEY" \
-G https://test-management.browserstack.com/api/v2/projects/PR-1/test-plans \
--data-urlencode 'q[tp_custom_fields]={"5678":["High","Medium"]}'

project_id^* String

Identifier of the project.
q[tp_custom_fields] String

JSON object keyed by custom field id, with an array of values for each field, for example {"5678":["High"]}. For dropdown and multi_dropdown fields, pass option labels. Returns only the test plans that match every listed field.

Response attributes `200 OK` `json`

Response

{
  "success": true,
  "test_plans": [
    {
      "active_state": "active",
      "description": "testing of high-risk modules with potential for significant impact on functionality.",
      "identifier": "TP-174",
      "test_runs_count": {
        "active": 4,
        "closed": 3
      },
      "name": "TP_46",
      "project_id": "PR-1",
      "start_date": "2024-02-19T00:00:00.000Z",
      "end_date": null,
      "created_at": "2024-02-27T11:47:44.000Z",
      "owner": "owner@example.com",
      "custom_fields": [
        {
          "id": 5678,
          "field_type": "field_dropdown",
          "field_name": "severity",
          "field_user_name": "Severity",
          "optional": true,
          "value": 900,
          "option": {
            "id": 900,
            "option_value": "High"
          },
          "options": []
        }
      ]
    },
    {
      "active_state": "active",
      "description": "Tests designed to validate core user login functionality.",
      "identifier": "TP-173",
      "test_runs_count": {
        "active": 10,
        "closed": 2
      },
      "name": "TP-23",
      "project_id": "PR-1",
      "start_date": "2024-02-08T00:00:00.000Z",
      "end_date": null,
      "created_at": "2024-02-27T11:47:33.000Z",
      "owner": "owner@example.com",
      "custom_fields": []
    }
  ],
  "info": {
    "page": 1,
    "page_size": 30,
    "count": 2,
    "prev": null,
    "next": null
  }
}

success Boolean

API call is executed successfully.
test_plans Array

This list has information about a specific test plan.

▶ SHOW VALUES
- active_state String
  
  Status of the test plan.
- description String
  
  Brief information about the test plan.
- identifier String
  
  Unique identifier of the test plan.
- test_runs_count Integer
  
  Gives the count of active test runs and closed test runs.
- name String
  
  Name of the test plan.
- project_id String
  
  Unique identifier of the Project.
- start_date String
  
  The date when the test plan begins.
- end_date String
  
  The date when the test plan ends.
- created_at String
  
  The time when the test plan is created on BrowserStack servers.
- owner String
  
  Email of the test plan owner. null when the owner is not a user in your group.
- custom_fields Array
  
  Custom field values set on the test plan. Empty when no value is set.
  
  ▶ SHOW VALUES
  - id Integer
    
    Unique identifier of the custom field.
  - field_type String
    
    Data type of the custom field, prefixed with field_, such as field_dropdown or field_string.
  - field_name String
    
    System name of the custom field.
  - field_user_name String
    
    Name of the custom field as shown in Test Management. Use this name as the key when you set the value.
  - optional Boolean
    
    true when the field is not required.
  - value String
    
    Stored value of the field. For dropdown fields, the identifier of the selected option.
  - option Object
    
    The selected option of a dropdown field, with its id and option_value. null for other field types.
  - options Array
    
    The selected options of a multi_dropdown field. Empty for other field types.

Create test plan

POST /api/v2/projects/{project_id}/test-plans

Invoking this API will create a test plan programmatically. To create a test plan, you will need the id of the project in which the test plan should be created.

To assign an owner, pass the email of a user in your group in owner. Without owner, the test plan is owned by the user whose credentials made the request. An email that does not belong to a user in your group returns 400 Bad Request and names the email.

To set custom field values, pass a custom_fields object keyed by the custom field name. For dropdown fields, pass the option label. For multi_dropdown fields, pass an array of option labels. A name that is not defined for test plans in the project returns 400 Bad Request and names the field.

Request parameters

Request

curl -u "YOUR_USERNAME:YOUR_ACCESS_KEY" \
-X POST https://test-management.browserstack.com/api/v2/projects/PR-127/test-plans

project_id^* String

Identifier of the project.

Request body

Request Body

{
  "test_plan": {
    "name": "Data Migration",
    "plan_status": "completed",
    "description": "Data Migration test plan outlines the steps and criteria for verifying accurate and complete data transfer between systems, ensuring a smooth and reliable transition.",
    "start_date": "2024-02-02T00:00:00.000Z",
    "end_date": "2024-02-02T00:00:00.000Z",
    "owner": "owner@example.com",
    "custom_fields": {
      "Severity": "High",
      "Release": "2026.10"
    }
  }
}

name^* String

Name of the test plan.
plan_status String

The status of the test plan.
description String

Brief information about the test plan.
start_date String

The date when the test plan begins.
end_date String

The date when the test plan ends.
owner String

Email of the user who owns the test plan. Must be a user in your group. Without it, the user who made the request owns the test plan.
custom_fields Object

Custom field values keyed by custom field name, for example {"Severity": "High"}. Pass option labels for dropdown fields and an array of option labels for multi_dropdown fields. A name that is not defined for test plans in the project returns 400.

Response attributes `200 OK` `json`

Response

{
  "success": true,
  "test_plan": {
    "active_state": "active",
    "description": "Data Migration test plan outlines the steps and criteria for verifying accurate and complete data transfer between systems, ensuring a smooth and reliable transition.",
    "identifier": "TP-25",
    "test_runs_count": {
      "active": 0,
      "closed": 0
    },
    "name": "Data Migration",
    "project_id": "PR-127",
    "start_date": "2023-12-30T00:00:00.000Z",
    "end_date": "2023-12-31T00:00:00.000Z",
    "created_at": "2024-01-05T14:12:43.722Z",
    "owner": "owner@example.com",
    "custom_fields": [
      {
        "id": 5678,
        "field_type": "field_dropdown",
        "field_name": "severity",
        "field_user_name": "Severity",
        "optional": true,
        "value": 900,
        "option": {
          "id": 900,
          "option_value": "High"
        },
        "options": []
      },
      {
        "id": 5679,
        "field_type": "field_string",
        "field_name": "release",
        "field_user_name": "Release",
        "optional": true,
        "value": "2026.10",
        "option": null,
        "options": []
      }
    ]
  }
}

success Boolean

API call is executed successfully.
test_plan JSON Object

This list has information about a specific test plan.

▶ SHOW VALUES
- active_state String
  
  Status of the test plan.
- description String
  
  Brief information about the test plan.
- identifier String
  
  Unique identifier of the test plan.
- test_runs_count Integer
  
  Gives the count of active test runs and closed test runs.
- name String
  
  Name of the test plan.
- project_id String
  
  Unique identifier of the Project.
- start_date String
  
  The date when the test plan begins.
- end_date String
  
  The date when the test plan ends.
- created_at String
  
  The time at which the test plan was created on BrowserStack servers.
- owner String
  
  Email of the test plan owner. null when the owner is not a user in your group.
- custom_fields Array
  
  Custom field values set on the test plan. Empty when no value is set.
  
  ▶ SHOW VALUES
  - id Integer
    
    Unique identifier of the custom field.
  - field_type String
    
    Data type of the custom field, prefixed with field_, such as field_dropdown or field_string.
  - field_name String
    
    System name of the custom field.
  - field_user_name String
    
    Name of the custom field as shown in Test Management. Use this name as the key when you set the value.
  - optional Boolean
    
    true when the field is not required.
  - value String
    
    Stored value of the field. For dropdown fields, the identifier of the selected option.
  - option Object
    
    The selected option of a dropdown field, with its id and option_value. null for other field types.
  - options Array
    
    The selected options of a multi_dropdown field. Empty for other field types.

Update test plan

POST /api/v2/projects/{project_id}/test-plans/{test_plan_id}/update

Use this API to update a test plan in a project. To update a test plan, you need the project id, for example PR-2134, and the test plan id.

To change the owner, pass the email of a user in your group in owner. To change custom field values, pass a custom_fields object keyed by the custom field name. Use the same shape as the create request. When you leave out owner or custom_fields, the existing values stay unchanged. An unknown owner email or an undefined custom field name returns 400 Bad Request.

Request parameters

Request

curl -u "YOUR_USERNAME:YOUR_ACCESS_KEY" \
-X POST https://test-management.browserstack.com/api/v2/projects/{project_id}/test-plans/{test_plan_id}/update

project_id^* String

Identifier of the project.

Request body

Request Body

{
  "test_plan": {
    "name": "Test Plan - 25/01/2024",
    "plan_status": "completed",
    "description": "Worked Upon",
    "start_date": "2024-02-02T00:00:00.000Z",
    "end_date": "2024-02-02T00:00:00.000Z",
    "owner": "owner@example.com",
    "custom_fields": {
      "Severity": "Medium"
    }
  }
}

name String

Name of the test plan.
plan_status String

State of the test plan.
description String

Brief information about the test plan.
start_date String

The date when the test plan begins. The start date is optional. If you do not specify, the current date is considered.
end_date String

The date when the test plan ends. If you do not specify, the current date is considered.
owner String

Email of the user who owns the test plan. Must be a user in your group. Without it, the owner stays unchanged.
custom_fields Object

Custom field values keyed by custom field name, for example {"Severity": "High"}. Pass option labels for dropdown fields and an array of option labels for multi_dropdown fields. Without it, the existing values stay unchanged. A name that is not defined for test plans in the project returns 400.

Response attributes `200 OK` `json`

Response

{
  "success": true,
  "test_plan": {
    "active_state": "completed",
    "plan_status": "completed",
    "description": "Worked Upon",
    "identifier": "TP-25",
    "test_runs_count": {
      "active": 0,
      "closed": 0
    },
    "name": "Test Plan - 25/01/2024",
    "project_id": "PR-127",
    "start_date": "2023-12-30T00:00:00.000Z",
    "end_date": "2023-12-31T00:00:00.000Z",
    "created_at": "2024-01-05T14:12:43.722Z",
    "owner": "owner@example.com",
    "custom_fields": [
      {
        "id": 5678,
        "field_type": "field_dropdown",
        "field_name": "severity",
        "field_user_name": "Severity",
        "optional": true,
        "value": 901,
        "option": {
          "id": 901,
          "option_value": "Medium"
        },
        "options": []
      }
    ]
  }
}

active_state String

State of the test plan.
plan_status String

State of the test plan.
description String

Brief information about the test plan.
identifier String

Identifier of the test plan.
test_runs_count Integer

Count of number of test runs.
Show 5 more
name String

Name of the test plan.
project_id String

Identifier of the project.
start_date String

The time when the test plan begins.
end_date String

The time when the test plan has to end.
created_at String

The time the test plan was created on BrowserStack servers.

Get test runs linked to a test plan

GET /api/v2/projects/{project_id}/test-plans/{testplan_id}/test-runs

Invoking this API will fetch the list of test runs linked to a test plan. You will need the id of the project and id of the test plan to access its list of test runs. The sample request has PR-127 and TP-25 as placeholders representing project ID and test plan ID respectively.

This list is paginated. For more information, see Pagination.

Request parameters

Request

curl -u "YOUR_USERNAME:YOUR_ACCESS_KEY" \
https://test-management.browserstack.com/api/v2/projects/PR-127/test-plans/TP-25/test-runs

project_id^* String

Identifier of the project.
test_plan_id^* String

Identifier of the test plan.

Response attributes `200 OK` `json`

Response

{
  "success": true,
  "test_runs": [
    {
      "active_state": "active",
      "run_state": "new_run",
      "created_at": "2024-01-05T14:13:58.000Z",
      "description": "Test Run created",
      "identifier": "TR-26",
      "name": "Automated UI testing",
      "assignee": "john@email.com",
      "project_id": "PR-127",
      "test_cases_count": 0
    },
    {
      "active_state": "active",
      "run_state": "new_run",
      "created_at": "2024-01-04T11:13:16.000Z",
      "description": "Test Run created",
      "identifier": "TR-23",
      "name": "Performance test plan",
      "assignee": "brown@email.com",
      "project_id": "PR-127",
      "test_cases_count": 0
    },
    {
      "active_state": "active",
      "run_state": "new_run",
      "created_at": "2024-01-04T07:43:13.000Z",
      "description": "Regression test plan",
      "identifier": "TR-12",
      "name": "Test Run-03/01/2024",
      "assignee": "selva@email.com",
      "project_id": "PR-127",
      "test_cases_count": 0
    }
  ],
  "info": {
    "page": 1,
    "page_size": 30,
    "count": 2,
    "prev": null,
    "next": null
  }
}

success Boolean

API call is executed successfully.
test_runs Array

List of test runs linked to a test plan.

▶ SHOW VALUES
- active_state String
  
  Status of the test run.
- run_state String
  
  State of the test run. The valid states are new_run, in_progress, under_review, rejected, done, and closed.
- created_at String
  
  The time at which the test run was created on BrowserStack servers.
- description String
  
  Brief information about the test run.
- identifier String
  
  Unique identifier of the test run.
- name String
  
  Name of the test run.
- assignee String
  
  Email of the test run assignee.
- project_id String
  
  Unique identifier of the Project.
- test_cases_count Integer
  
  Count of number of test cases.

Get test plan details

GET /api/v2/projects/{project_id}/test-plans/{test_plan_id}

Invoking this API will fetch the test plan details. You will need the id of the project and the id of that test plan to access it’s details.

Request parameters

Request

curl -u "YOUR_USERNAME:YOUR_ACCESS_KEY" \
https://test-management.browserstack.com/api/v2/projects/PR-1/test-plans/TP-2

project_id^* String

Identifier of the project.
test_plan_id^* String

Identifier of the test plan.

Response attributes `200 OK` `json`

Response

{
  "success": true,
  "test_plan": {
    "active_state": "active",
    "plan_status": "new",
    "description": "",
    "identifier": "TP-2",
    "test_runs_count": {
      "active": 1,
      "closed": 0
    },
    "name": "Test Plan - 25/01/2024",
    "project_id": "PR-1",
    "start_date": "2024-01-25T00:00:00.000Z",
    "end_date": null,
    "created_at": "2024-01-25T11:35:40.000Z",
    "test_runs": [
      {
        "identifier": "TR-1",
        "name": "Test Run-29/11/2023"
      },
      {
        "identifier": "TR-2",
        "name": "Test Run-30/11/2023"
      }
    ],
    "links": {
      "test_runs": "/api/v2/projects/PR-2/test-plans/TP-2/test-runs"
    },
    "owner": "owner@example.com",
    "custom_fields": [
      {
        "id": 5678,
        "field_type": "field_dropdown",
        "field_name": "severity",
        "field_user_name": "Severity",
        "optional": true,
        "value": 900,
        "option": {
          "id": 900,
          "option_value": "High"
        },
        "options": []
      }
    ]
  }
}

active_state String

State of the test plan.
plan_status String

State of the test plan.
description String

Brief information about the test plan.
identifier String

Identifier of the test plan.
test_runs_count Integer

Count of number of test runs.
Show 9 more
name String

Name of the test plan.
project_id String

Identifier of the project.
start_date String

The time when the test plan starts.
end_date String

The time when the test plan has to stop
created_at String

The time the test plan was created on BrowserStack servers.
test_runs Array

This list has information about a specific test run.

▶ SHOW VALUES
- identifier String
  
  Unique identifier of the test run.
- name String
  
  Name of the test runs.
links String

API endpoint url of the test run.
owner String

Email of the test plan owner. null when the owner is not a user in your group.
custom_fields Array

Custom field values set on the test plan. Empty when no value is set.

▶ SHOW VALUES
- id Integer
  
  Unique identifier of the custom field.
- field_type String
  
  Data type of the custom field, prefixed with field_, such as field_dropdown or field_string.
- field_name String
  
  System name of the custom field.
- field_user_name String
  
  Name of the custom field as shown in Test Management. Use this name as the key when you set the value.
- optional Boolean
  
  true when the field is not required.
- value String
  
  Stored value of the field. For dropdown fields, the identifier of the selected option.
- option Object
  
  The selected option of a dropdown field, with its id and option_value. null for other field types.
- options Array
  
  The selected options of a multi_dropdown field. Empty for other field types.

Get attachments linked to a test plan

GET /api/v2/projects/{project_id}/test-plans/{test_plan_id}/attachments

Invoking this API will fetch the list of attachments linked to a test plan. You will need the id of the project and the id of the test plan to access its attachments. The sample request has PR-3602 and TP-170 as placeholders representing project ID and test plan ID respectively.

This list is paginated. For more information, see Pagination.

Request parameters

Request

curl -u "YOUR_USERNAME:YOUR_ACCESS_KEY" \
https://test-management.browserstack.com/api/v2/projects/PR-3602/test-plans/TP-170/attachments

project_id^* String

Unique identifier of the project.
test_plan_id^* String

Unique identifier of the test plan.

Response attributes `200 OK` `json`

Response

{
  "success": true,
  "attachments": [
    {
      "id": 10854405,
      "name": "image (3).png",
      "size": 86053,
      "created_at": "2026-06-15T20:21:16.000Z",
      "url": "https://teststack-stage.s3.amazonaws.com/media/genric/3/10334/MExLQocx2ag99PI"
    },
    {
      "id": 10854404,
      "name": "image (2).png",
      "size": 83633,
      "created_at": "2026-06-15T20:21:16.000Z",
      "url": "https://teststack-stage.s3.amazonaws.com/media/genric/3/10334/ExLQocx2ag99PI"
    },
    {
      "id": 10854403,
      "name": "image (1).png",
      "size": 236032,
      "created_at": "2026-06-15T20:21:16.000Z",
      "url": "https://teststack-stage.s3.amazonaws.com/media/genric/3/10334/x2ag99PI"
    }
  ],
  "info": {
    "page": 1,
    "page_size": 30,
    "count": 3,
    "prev": null,
    "next": null
  }
}

success Boolean

API call is executed successfully.
attachments Array

List of attachments linked to the test plan.

▶ SHOW VALUES
- id Integer
  
  Unique identifier of the attachment.
- name String
  
  File name of the attachment.
- size Integer
  
  File size of the attachment in bytes.
- created_at String
  
  The time at which the attachment was uploaded on BrowserStack servers.
- url String
  
  Download URL of the attachment.

Did this page help you?

We're sorry to hear that. Please share your feedback so we can do better

Contact our Support team for immediate help while we work on improving our docs.

We're continuously improving our docs. We'd love to know what you liked

This page has exactly what I am looking for
This content & code samples are accurate and up-to-date
The content on this page is easy to understand
Other (please tell us more below)

Any additional feedback?

Thank you for your valuable feedback

Test plans

Get the list of test plans

Request parameters

project_id* String

q[tp_custom_fields] String

Response attributes 200 OK json

success Boolean

test_plans Array

active_state String

description String

identifier String

test_runs_count Integer

name String

project_id String

start_date String

end_date String

created_at String

owner String

custom_fields Array

id Integer

field_type String

field_name String

field_user_name String

optional Boolean

value String

option Object

options Array

Create test plan

Request parameters

project_id* String

Request body

name* String

plan_status String

description String

start_date String

end_date String

owner String

custom_fields Object

Response attributes 200 OK json

success Boolean

test_plan JSON Object

active_state String

description String

identifier String

test_runs_count Integer

name String

project_id String

start_date String

end_date String

created_at String

owner String

custom_fields Array

id Integer

field_type String

field_name String

field_user_name String

optional Boolean

value String

option Object

options Array

Update test plan

Request parameters

project_id* String

Request body

name String

plan_status String

description String

start_date String

end_date String

owner String

custom_fields Object

Response attributes 200 OK json

active_state String

plan_status String

description String

identifier String

test_runs_count Integer

name String

project_id String

start_date String

project_id^* String

Response attributes `200 OK` `json`

project_id^* String

name^* String

Response attributes `200 OK` `json`

project_id^* String

Response attributes `200 OK` `json`

project_id^* String

test_plan_id^* String

Response attributes `200 OK` `json`

project_id^* String

test_plan_id^* String

Response attributes `200 OK` `json`

project_id^* String

test_plan_id^* String

Response attributes `200 OK` `json`