PractiTest Query Language (PTQL) allows you to find and filter entities such as tests, requirements, issues, test sets, and runs using a human-readable query syntax via the API.
Important Notes:
- PTQL is currently in Beta, and minor changes may still occur over time.
- PTQL is available only for Corporate licenses.
- What is PTQL
- Basic Syntax
- Field Names
- Supported Operators
- Matching Behavior
- Combining Conditions
- User Fields
- Cross-Entity Filters
- Counting Link Entities
- Custom View References
- Auto-Filter Views
- Cross-Entity View References
- Filtering Runs
- Filtering Instances
- Parameter Conflicts
What Is PTQL
PTQL enables you to define flexible and precise filters using a query-based syntax. It allows you to do operations such as:
- Filter entities based on field values
- Combine multiple conditions
- Query relationships between entities (e.g., tests linked to requirements)
- Use dynamic conditions such as current user or recent activity
Basic Syntax
Use PTQL to filter entities by field value using:
- = for equals
- != for not equals
Examples:
- Status = “Open”
- Priority != “Low”
If a field name contains spaces, wrap it in single quotes:
- ‘Assigned To’ = “john@example.com”
- ‘Story Points’ > 5
Field Names
PTQL uses the display names of fields as they appear in the PractiTest UI.
- Field names are case-insensitive
- Custom fields use their display name
- Renamed fields must be referenced by their updated name
To retrieve available fields for your project, use: GET /api/v2/projects/{project_id}/fields.json
Supported Operators
| Operator | Description | Example |
| = | Equals | Status = “Open” |
| != | Not equals | Status != “Closed” |
| > >= < <= | Numeric comparison | ‘Story Points’ >= 10 |
| IS EMPTY | Field is empty | description IS EMPTY |
| IS NOT EMPTY | Field has value | description IS NOT EMPTY |
| CONTAINS | Substring match | name CONTAINS “login” |
| NOT CONTAINS | Exclude substring | name NOT CONTAINS “login” |
| STARTS WITH | Prefix match | name STARTS WITH “API” |
| NOT STARTS WITH | Exclude prefix | name NOT STARTS WITH “API” |
| IN LAST | Time-based filter | created_at IN LAST 7 days |
| NOT IN LAST | Exclude time range | updated_at NOT IN LAST 30 days |
Matching Behavior
- = and != perform exact matching
- Use CONTAINS or STARTS WITH for partial matches
Examples:
- name = “Login Page” – Exact Match
- name CONTAINS “login” – Partial Match (case-insensitive)
- name STARTS WITH “API” –Prefix Match (case-insensitive)
Combining Conditions
You can combine conditions such as ‘AND’, ‘OR’ and ‘NOT’ using logical operators:
- Status = “Open” AND Priority = “High”
- Status = “Open” OR Status = “In Progress”
- NOT Status = “Closed”
Operator precedence:
- ‘AND’ binds tighter than ‘OR’
- Use parentheses to control logic
Example:
(Status = “Open” OR Status = “In Progress”) AND Priority = “High”
Complex Example: Find high-priority open issues assigned to you that are linked to approved requirements
(Status = “Open” OR Status = “In Progress”)
AND Priority = “High”
AND ‘Assigned To’ = CURRENT_USER
AND LINKED TO Requirement WHERE (Status = “Approved” AND ‘Review Status’ != “Rejected”)
User Fields
User-based fields accept email addresses:
- ‘Assigned To’ = “john@example.com”
- Author = “jane@example.com”
You can also use ‘CURRENT_USER’ for the authenticated API user:
- ‘Assigned To’ = CURRENT_USER
For the Assigned To field, you can also filter by group:
- ‘Assigned To’ = GROUP “Testers”
Cross-Entity Filters
PTQL supports filtering based on linked entities using ‘LINKED TO’. ‘WHERE’ clause is optional and can be used to filter by properties of the linked entities, or omitted to match any linked entity. Here are some examples:
- LINKED TO Requirement
- LINKED TO Requirement WHERE (Status = “Approved”)
- NOT LINKED TO Issue
- NOT LINKED TO Issue WHERE (Status = “Open”)
Supported entity types:
- Requirement
- Issue
- Test
- TestSet
- Milestone
- Run
Counting Linked Entities
You can filter entities based on the number of linked entities using the ‘COUNT(…)’ function.
‘COUNT’ wraps a ‘LINKED TO’ expression and allows you to compare the number of matching linked entities using standard operators.
Examples:
- COUNT(LINKED TO Test) > 5
- COUNT(LINKED TO Test WHERE (‘Run Status’ = “Blocked”)) > 0
- COUNT(LINKED TO Test WHERE (Priority = “High”)) >= 10
Custom View References
PTQL allows you to reference saved custom views directly within your queries using the VIEW keyword.
Referencing a View by Path
If your views are organized in a hierarchy, you can reference child views using /:
- VIEW “All Bugs” / “Sprint 1”
- VIEW “All Bugs” / “Sprint 1” / “Assigned to me”
Referencing a View by ID
You can reference a specific view using its ID:
- VIEW #42
Combining Views with Other Conditions
You can combine ‘VIEW’ with other PTQL conditions using logical operators:
- VIEW “Open Bugs” AND ‘Assigned To’ = CURRENT_USER
- VIEW “Open Bugs” OR VIEW “Reopened Bugs”) AND Priority = “High”
- NOT VIEW “Excluded from report”
Important Notes:
- View names are matched within the same entity type. For example, an Issue view cannot be used when querying Tests.
- If multiple views have the same name, use the ID format (VIEW #42) to avoid ambiguity.
- ‘VIEW’ can be combined with ‘LINKED TO’ and all other PTQL operators.
Auto-Filter Views
When the referenced view is an auto-filter view, you can target a specific subtree by appending a WHERE(…) condition to the VIEW reference.
Examples:
- VIEW #42 WHERE (Status = “Ready”)
- VIEW “By Status” WHERE (Status = “Ready”)
- VIEW “All Bugs” / “Auto Filter by Status” WHERE (Status = “Ready” AND ‘Run Status’ = “PASSED”)
WHERE can be used after both the ID form (VIEW #N) and the name based form (VIEW “name” or VIEW “name” / “child”)
Fields inside the WHERE clause must match the fields used by the referenced auto-filter view (not the source entity). For cross-entity references, use the linked entity field names.
Example:
- A Test view referencing a Requirement auto-filter – use the linked entity’s field names.
Auto-Filter View Restrictions
Restrictions inside VIEW … WHERE (…) are:
- Only equality (=) is supported
- !=, CONTAINS, ranges, and IS EMPTY are not supported
- Conditions can only be combined using AND
- OR and NOT are not supported inside the WHERE (…) section
The fields must also match the referenced view’s auto-filter levels in order. For example, if the view is auto-filtered first by Status and then by Run Status:
- VIEW #42 WHERE (Status = “Ready”) – # level 1 only
- VIEW #42 WHERE (Status = “Ready” AND ‘Run Status’ = “PASSED”) – # both levels\
Using fields in a different order or using fields that are not part of the auto-filter structure will return an error.
Using OTHER for Empty Values
To target the Other / Empty values branch of an auto-filter level, use the OTHER keyword without quotes:
- VIEW #42 WHERE (Status = OTHER)
Combining Auto-Filter Views with Other Conditions
Parentheses around the WHERE body are required to keep the query unambiguous when combined with additional conditions.
Examples:
- VIEW #42 WHERE (Status = “Ready”) AND updated_at IN LAST 7 days
- NOT VIEW #42 WHERE (Status = “Ready”)
- (VIEW #42 WHERE (Status = “Ready”) OR VIEW #99 WHERE (Status = “Ready”)) AND Priority = “High”
Cross-Entity View References
PTQL supports referencing saved views inside queries using either a view ID or a view name.
Referencing Views by ID
Use VIEW #N to reference a saved view by its ID.
ID-based references can point to views of any entity type in the project.
When the referenced view belongs to a different entity than the source query, PTQL automatically treats it as a cross-entity filter.
For example, if you are querying Tests and reference a Requirement view:
- VIEW #42
PTQL expands it internally to:
- LINKED TO Requirement WHERE (<view 42 filter>)
Referencing Views by Name
Name-based references (VIEW “name”, VIEW “name” / “child”) only match views within the source entity — use the ID form to reference views of a different entity.
Filtering Runs
Use the set-ptql parameter on the runs endpoint to filter by test set. Runs belonging to matching test sets are returned.
Note: set-ptql cannot be combined with set-filter-id.
Example to find runs that belong to test sets containing tests that are not linked to any requirement:
- LINKED TO Test WHERE (NOT (LINKED TO Requirement))
Filtering Instances
Like runs, the set-ptql parameter on the instances endpoint filters test sets. Instances belonging to matching test sets are returned.
Note: set-ptql cannot be combined with set-filter-id.
API Usage
For API usage examples, please refer to our full API documentation.
Parameter Conflicts
The ptql parameter cannot be combined with:
- Tests, Requirements Issues, Test Sets: filter-id, autofilter-value, subautofilter-value
The set-ptql cannot be combined with:
- Runs, Instances: set-filter-id
