Use this API to list the Test Cases linked to a Standard Test Plan and see their latest matching execution results for a selected iteration. You can narrow the list with filters and retrieve it a page at a time.

Before you begin

Create a Vansah API token and use the Vansah URL supplied for your workspace.
Make sure the token account can access the Jira space.
Copy the plan key from Vansah, for example DEMO-P12, and choose an existing iteration. The default is iteration 1.

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 DEMO and DEMO-P12 with your space and plan keys. Keep your token private.

Endpoint and headers

GET /api/v2/testPlan/testCases

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

Send the parameters in the query string. A JSON request body is not needed.

Plan, iteration, and pagination parameters

Parameter	How to use it
`projectKey`	The Jira space key. Include it to provide space context when using an API token, for example `DEMO`.
`testPlanKey`	The plan to retrieve, for example `DEMO-P12`. Include it to scope this request to your Standard Test Plan.
`iterationNumber`	Optional. Existing iteration number, such as `1` or `2`. Defaults to `1`.
`eprIdentifier`	Optional alternative to `iterationNumber`: the iteration UUID. Do not send both parameters.
`startAt`	Optional record offset. Defaults to `0`. Use a whole number of zero or greater.
`limit`	Optional page size. Defaults to `50`. Use a positive whole number.
`sortBy`	Optional. Useful choices include `caseKey`, `headline`, `result`, `priority`, `testedTime`, `caseCreatedDate`, and `caseModifiedDate`.
`sortOrder`	Optional. `asc` or `desc`; defaults to `asc`.

Use the Jira space key associated with the plan. Send testPlanKey on every page, together with the same iteration, filters, and sort order. Do not combine testPlanKey with testFolderIdentifier.

Example: retrieve the first page

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"

Example response, showing selected fields from a Test 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": 1
      }
    ]
  }
}

Understand the response

Field	Meaning
`success` and `message`	Whether the request succeeded and a summary of the outcome.
`data.pagination`	Contains `total`, `startAt`, and `limit`. Pagination is nested inside `data`.
`data.data`	The array of Test Case rows for this page.
`caseIdentifier` and `caseKey`	The Test Case UUID and readable key.
`testCaseVersion`	The version linked to the plan.
`headline`, `caseTypeName`, and `priorityName`	The Test Case’s title, type, and priority.
`resultName` and `resultID`	The latest matching execution result. Result names can reflect your configured result labels.
`eprIdentifier` and `eprKey`	The iteration UUID and number associated with the matching Test Run, when one exists.

Rows include additional Test Case and execution details, such as descriptions, assignee and owner account IDs, environment and release names, timestamps, attachment counts, and Test Run identifiers. Some missing or zero-valued fields are returned as empty strings, so allow for "" when reading optional values. This endpoint returns summary rows; it does not include the full list of script steps or every execution log.

Retrieve the remaining pages

For a page size of 50, request startAt=50, then 100, and continue until you have retrieved the matching records or receive an empty array. Check data.pagination, and keep the other query parameters unchanged. If records change while you are paging, the result count can change.

Filter the Test Cases

Add these optional parameters to narrow the list. Use --data-urlencode as in the examples so spaces and other characters are encoded correctly.

Filter	What it does
`caseKey` or `caseIdentifier`	Find a Test Case by its exact readable key or UUID.
`headline`	Find text within the Test Case headline or its short case reference.
`labelName`	Match a label name. Multiple names can be comma-separated.
`caseTypeName` or `caseTypeIdentifier`	Filter by Test Case type name or UUID.
`caseStatusIdentifier`	Filter by the Test Case status UUID.
`priorityJiraID` or `componentJiraID`	Filter using Jira priority or component IDs.
`assigneeJiraID`, `createdBy`, `updatedBy`, or `testedBy`	Filter using Jira account IDs. For comparison, use the corresponding `assigneeComparison`, `createdByComparison`, `updatedByComparison`, or `testedByComparison` value `equal` or `unequal`.
`resultID`	Filter by one or more result codes, comma-separated. See the result codes below.
`environmentIdentifier`, `releaseJiraID`, or `sprintJiraID`	Narrow the execution results considered using an environment UUID, Jira version ID, or Jira sprint ID.
`createdStartDate` and `createdEndDate`	Filter Test Cases by creation date. Supply both dates.
`updatedStartDate` and `updatedEndDate`	Filter Test Cases by modification date. Supply both dates.
`testedStartDate` and `testedEndDate`	Filter by execution date. Supply both dates.
`timezone`	Timezone for date filters, for example `America/New_York`. The backend default is `Australia/Sydney`.

Use YYYY-MM-DD for date filters, for example 2026-11-01 through 2026-11-13. Environment, release, and sprint filters affect which execution is used for the displayed result; a linked Test Case without a matching execution can still appear as untested.

Result filter codes

Code	Result
`0`	N/A
`1`	Failed
`2`	Passed
`3`	Untested
`4`	N/A in progress
`5`	Failed in progress
`6`	Passed in progress
`7`	Blocked

Example: failed Test Cases with a label

This request selects iteration 2 and filters for the Smoke label and a failed result:

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=2" \
  --data-urlencode "labelName=Smoke" \
  --data-urlencode "resultID=1" \
  --data-urlencode "startAt=0" \
  --data-urlencode "limit=50"

Troubleshooting

Message or issue	What to check
`One or more validation errors found.`	Inspect `data.errors`. Check numeric parameters, UUIDs, date values, and supported sort options.
`Invalid Test Plan Key format...`	Copy the plan key from Vansah, such as `DEMO-P12`, including its uppercase space prefix.
`Please provide a valid Test Plan key(...)`	Check that the plan exists, is active, and belongs to the expected workspace.
`Please provide a valid iteration number.` or `Please provide a valid eprIdentifier.`	Use an existing active iteration belonging to that plan.
`Please provide either eprIdentifier or iterationNumber, but not both.`	Remove one of the two iteration selectors.
Authentication or space access error	Check the Vansah URL, API token, Jira space key, and the token account’s space access.
Empty list	Check the plan, iteration, filters, and page offset. Retry the first page without optional filters.

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 a Standard Test Plan (API)