Tags
How to work with test case tags using the public API
Tags help organize and categorize test cases within your project. You can use tags in query plans to filter test cases when creating runs.
List Tags
/paginated endpoints are transitional. In API v1, the base paths will return paginated responses and the /paginated suffix will be removed.
Returns all tags defined in the project. This endpoint is particularly useful when creating run query plans that filter test cases by tags.
Path Parameters
project_id: The project identifier (can be either the project code or UUID)
Query Parameters
| Parameter | Type | Description | Default | Example |
|---|---|---|---|---|
offset | number | Number of rows to skip before returning results. | 0 | offset=10 |
limit | number | Maximum number of rows to return. Accepted range: 0–1,000. | 100 | limit=20 |
sortField | string | Field to sort by: created_at or title. | title | sortField=title |
sortOrder | string | Sort direction for sortField: asc or desc. | asc | sortOrder=asc |
include | string | Include additional fields omitted by default. Accepted value: tcaseCount. | None | include=tcaseCount |
Response
Status: 200 OK
{
total: number, // Total number of tags
offset: number, // The page offset
limit: number, // The page limit
data: Array<{ // List of tags in the page
id: number // Unique tag identifier within the project
title: string // Tag label
tcaseCount?: number // Number of test cases using this tag (only included if requested)
}>
}Example Request
curl \
-H "Authorization: ApiKey your.api.key.here" \
https://your-company.your-region-code.qasphere.com/api/public/v0/project/BD/tag/paginatedExample Response
{
"total": 3,
"offset": 0,
"limit": 100,
"data": [
{
"id": 1,
"title": "regression"
},
{
"id": 2,
"title": "api-tests"
},
{
"id": 3,
"title": "smoke-tests"
}
]
}Error Responses
| Status Code | Description |
|---|---|
| 401 | Invalid or missing API key |
| 403 | Insufficient permissions or suspended tenant |
| 404 | Project not found |
| 500 | Internal server error |
Using Tags in Run Query Plans
Tags returned by this endpoint can be used in run query plans to filter test cases. For example:
{
"title": "API Regression Run",
"type": "live",
"queryPlans": [
{
"folderIds": [1],
"tagIds": [2], // Using the tag ID for "api-tests"
"priorities": ["high"]
}
]
}Tag IDs are unique within a project but not across projects. Always verify you're using tag IDs from the correct project.
Using Multiple Tags
You can include multiple tag IDs in a query plan to select test cases that have any of the specified tags.
{
"tagIds": [2, 3] // Selects test cases with either "api-tests" or "smoke-tests" tags
}List Tags (Deprecated)
Deprecated
This endpoint is deprecated. Use List Tags (GET /api/public/v0/project/{project_id}/tag/paginated) instead.
Returns all tags defined in the project. This endpoint is particularly useful when creating run query plans that filter test cases by tags.
Path Parameters
project_id: The project identifier (can be either the project code or UUID)
Response
Status: 200 OK
{
tags: Array<{
id: number // Unique tag identifier within the project
title: string // Tag name/label
}>
}Example Request
curl \
-H "Authorization: ApiKey your.api.key.here" \
https://your-company.your-region-code.qasphere.com/api/public/v0/project/BD/tagExample Response
{
"tags": [
{
"id": 1,
"title": "regression"
},
{
"id": 2,
"title": "api-tests"
},
{
"id": 3,
"title": "smoke-tests"
}
]
}Error Responses
| Status Code | Description |
|---|---|
| 401 | Invalid or missing API key |
| 403 | Insufficient permissions or suspended tenant |
| 404 | Project not found |
| 500 | Internal server error |