List the test cases linked to an Advanced Test Plan and review their matching execution results for an iteration. Retrieve cases across the plan, or narrow the request to a Jira work item or Test Folder requirement.

Before you begin

Have a Vansah API token and your workspace’s Vansah API URL. The token account must be able to access the Jira space.
Copy the Advanced Test Plan key, such as DEMO-P12, from Vansah and choose an existing iteration.
For a requirement-specific request, have the linked Jira work item key or exact Test Folder path.

The examples use Bash and cURL. Set VANSAH_URL to your Vansah base URL without a trailing slash and VANSAH_TOKEN to your API token. Replace the sample keys, iteration, folder path, and filters with values from your own Jira space.

Endpoint and headers

GET /api/v2/testplan/testCases

Header	Value
Authorization	Your Vansah API token, without a `Bearer` prefix.
Accept	`application/json`

Send parameters in the query string. This GET request does not need a JSON body.

Plan, requirement, and pagination parameters

Parameter	How to use it
`projectKey`	The Jira space key, for example `DEMO`. Include it for API token requests. Use the space associated with the plan.
`testPlanKey`	The plan key, for example `DEMO-P12`. Include it on every request to scope the response to that plan.
`iterationNumber`	Optional. Existing iteration number. Defaults to `1`, rather than the latest iteration.
`eprIdentifier`	Optional alternative to `iterationNumber`: the iteration UUID. Do not send both.
`testPlanIssueKey`	Optional. The linked requirement’s Jira work item key, for example `DEMO-123`.
`testPlanFolderPath`	Optional. The exact path of a linked Test Folder requirement, for example `Regression/Checkout/`. Preserve folder names, capitalization, and slashes.
`testPlanAssetIdentifier`	Optional alternative requirement selector. Use the requirement’s Vansah UUID, rather than the plan UUID.
`startAt`	Optional record offset, default `0`. Use a whole number of zero or greater.
`limit`	Optional page size, default `50`. Use a positive whole number.
`sortBy` and `sortOrder`	Optional. Useful sort fields include `caseKey`, `headline`, `result`, `priority`, and `testedTime`. Order is `asc` or `desc`; default `asc`.

projectKey refers to the Jira space key; the API field name remains unchanged. Supply at most one of testPlanIssueKey, testPlanFolderPath, or testPlanAssetIdentifier. Leave all three out to retrieve cases across the plan. Do not combine testPlanKey with testFolderIdentifier.

Example: cases across the plan

curl --request GET --get \
  --url "$VANSAH_URL/api/v2/testplan/testCases" \
  --header "Authorization: $VANSAH_TOKEN" \
  --header "Accept: application/json" \
  --data-urlencode "projectKey=DEMO" \
  --data-urlencode "testPlanKey=DEMO-P12" \
  --data-urlencode "iterationNumber=1" \
  --data-urlencode "startAt=0" \
  --data-urlencode "limit=50" \
  --data-urlencode "sortBy=caseKey" \
  --data-urlencode "sortOrder=asc"

The response is a summary list of cases, rather than a separate execution record for every requirement. If the same case is linked to several requirements, use a requirement selector when you need the result for a particular work item or folder.

Example: a Jira work item requirement

This request selects iteration 2 and the requirement DEMO-123:

curl --request GET --get \
  --url "$VANSAH_URL/api/v2/testplan/testCases" \
  --header "Authorization: $VANSAH_TOKEN" \
  --header "Accept: application/json" \
  --data-urlencode "projectKey=DEMO" \
  --data-urlencode "testPlanKey=DEMO-P12" \
  --data-urlencode "testPlanIssueKey=DEMO-123" \
  --data-urlencode "iterationNumber=2" \
  --data-urlencode "startAt=0" \
  --data-urlencode "limit=50"

Example: a Test Folder requirement with filters

This request selects iteration 2, the Regression/Checkout/ requirement, the Smoke label, and failed results. Copy the exact folder path using Copying a Test Folder Path.

curl --request GET --get \
  --url "$VANSAH_URL/api/v2/testplan/testCases" \
  --header "Authorization: $VANSAH_TOKEN" \
  --header "Accept: application/json" \
  --data-urlencode "projectKey=DEMO" \
  --data-urlencode "testPlanKey=DEMO-P12" \
  --data-urlencode "testPlanFolderPath=Regression/Checkout/" \
  --data-urlencode "iterationNumber=2" \
  --data-urlencode "labelName=Smoke" \
  --data-urlencode "resultID=1" \
  --data-urlencode "startAt=0" \
  --data-urlencode "limit=50"

Filter the results

Filter	What it does
`caseKey` or `caseIdentifier`	Find a case by its exact readable key or UUID.
`headline` and `labelName`	Search the case headline, or match a label. Label names can be comma-separated.
`caseTypeName`, `caseTypeIdentifier`, or `caseStatusIdentifier`	Filter by case type or status. Use the relevant name or UUID.
`priorityJiraID` or `componentJiraID`	Filter using Jira priority or component IDs.
`resultID`	Filter by one or more comma-separated result codes: `0` N/A, `1` Failed, `2` Passed, `3` Untested, `4` N/A in progress, `5` Failed in progress, `6` Passed in progress, `7` Blocked.
`assigneeJiraID`, `createdBy`, `updatedBy`, or `testedBy`	Filter using Jira account IDs. The corresponding comparison parameter, such as `assigneeComparison`, accepts `equal` or `unequal`.
`environmentIdentifier`, `releaseJiraID`, or `sprintJiraID`	Narrow which executions are considered. A linked case without a matching execution can still appear as untested.
Date pairs and `timezone`	Use `createdStartDate`/`createdEndDate`, `updatedStartDate`/`updatedEndDate`, or `testedStartDate`/`testedEndDate`. Supply both dates as `YYYY-MM-DD`. Set `timezone`, for example `America/New_York`; the default is `Australia/Sydney`.

Use --data-urlencode to encode spaces and other special characters in query values.

Read the response and retrieve the remaining pages

Example response showing selected fields from a case row:

{
  "success": true,
  "message": "Test Cases returned successfully",
  "data": {
    "pagination": {
      "total": 1,
      "startAt": 0,
      "limit": 50
    },
    "data": [
      {
        "caseIdentifier": "b90295bd-2725-4f44-98e5-e55c671f39c8",
        "caseKey": "DEMO-C42",
        "headline": "Sign in with a valid account",
        "testCaseVersion": 1,
        "caseTypeName": "Functional",
        "priorityName": "Medium",
        "resultName": "PASSED",
        "resultID": 2,
        "eprKey": 2
      }
    ]
  }
}

data.pagination contains total, startAt, and limit. Pagination is nested inside data.
data.data contains the case rows. caseIdentifier and caseKey identify the case; testCaseVersion identifies the linked version.
resultName and resultID describe the latest matching result. Result names can use your configured labels. eprIdentifier and eprKey identify the matching Test Run’s iteration when a run exists.
Additional fields include case descriptions, account IDs, environment and release names, timestamps, attachment counts, and Test Run identifiers. Optional or zero-valued fields may be returned as empty strings, so handle "" values.

This endpoint does not return the full script-step list or every execution log.

For a page size of 50, request startAt=50, then 100, until all matching records are retrieved or the next page is empty. Keep the plan, iteration, requirement, filters, and sort order unchanged between pages. Counts can change if the underlying data changes while you are paging.

Troubleshooting

Message or issue	What to check
`One or more validation errors found.`	Read `data.errors`. Check UUIDs, numeric values, dates, account IDs, and sort options.
Invalid Test Plan key or key format	Copy the plan key from Vansah. Check that the plan is active and in the expected workspace.
Invalid iteration number or `eprIdentifier`	Use an existing active iteration belonging to the plan. Do not send both iteration selectors.
Invalid `testPlanIssueKey` or `testPlanFolderPath`	Check the work item key or exact folder path. The requirement must also be linked to the plan to return matching cases.
Conflicting requirement selectors	Keep only one of the three requirement selectors.
Empty list	Check the selected iteration, requirement, filters, and offset. Retry the first page without optional filters.
Authentication or space access error	Check the Vansah API URL, token, Jira space key, and the token account’s access.

An empty matching list is a successful response:

{
  "success": true,
  "message": "Test Cases returned successfully",
  "data": {
    "pagination": {
      "total": 0,
      "startAt": 0,
      "limit": 50
    },
    "data": []
  }
}

You can also view this request in the Vansah API collection in Postman.

List Test Cases in an Advanced Test Plan (API)