Use the following API method to request the list of fields available for dynamic filtering when creating or updating test runs and test plans.
get_dynamic_filter_fields
Returns the list of fields available for dynamic filtering for a specific project.
GET index.php?/api/v2/get_dynamic_filter_fields/{project_id}Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| project_id | integer | true | The ID of the project for which dynamic filter fields should be returned. |
Response content
The response includes an array of field definitions that can be used to build dynamic_filters payloads for supported run and plan API endpoints.
The returned fields match the dynamic filter fields available in the TestRail UI for the selected project. This includes supported system fields and active custom case fields that are filterable for the project.
Non-filterable field types, such as Text, Steps, and Scenarios, are not returned. Please see below for a typical response:
[
{
"type_id": 6,
"system_name": "status_id",
"label": "Status",
"options": "1, Untested\n2, Retest\n3, Passed\n4, Failed"
},
{
"type_id": 6,
"system_name": "priority_id",
"label": "Priority",
"options": "1, Low\n2, Medium\n3, High"
},
{
"type_id": 1,
"system_name": "title",
"label": "Title",
"sub_filters": "1, Is\n2, Is Not\n5, Contains\n6, Does not contain"
},
{
"type_id": 8,
"system_name": "updated_on",
"label": "Updated On",
"sub_filters": "1, Is\n2, Is Not\n3, Is Before\n4, Is After"
},
{
"type_id": 12,
"system_name": "custom_multiselect",
"label": "Custom Multiselect",
"options": "1, Option 1\n2, Option 2"
}
]Response fields
| Name | Type | Description |
|---|---|---|
| type_id | integer | The field type ID. Clients can use this to determine how to render or construct filters for the field. |
| system_name | string | The system name of the field. This value is used when constructing dynamic_filters. |
| label | string | The display label of the field. |
| options | string | The available options for fields with selectable values, such as dropdown, multiselect, user, milestone, priority, status, type, or templates. |
| sub_filters | string | The supported operators for fields that support condition-based filtering, such as string, URL, integer, or date fields. |
Field type IDs
| Type ID | Name |
|---|---|
| 1 | String |
| 2 | Integer |
| 3 | Text |
| 4 | URL |
| 5 | Checkbox |
| 6 | Dropdown |
| 7 | User |
| 8 | Date |
| 9 | Milestone |
| 10 | Steps |
| 12 | Multi-select |
Supported fields
The response can include supported system fields such as:
| Field | Description |
|---|---|
| Assigned To | Filter cases by assigned user. |
| Automation Type | Filter cases by automation type. |
| Created By | Filter cases by creator. |
| Created On | Filter cases by creation date. |
| Estimate | Filter cases by estimate. |
| Forecast | Filter cases by forecast. |
| Labels | Filter cases by labels. |
| Milestone | Filter cases by milestone. |
| Priority | Filter cases by priority. |
| References | Filter cases by references. |
| Templates | Filter cases by template. |
| Title | Filter cases by title. |
| Type | Filter cases by case type. |
| Updated By | Filter cases by last updated user. |
| Updated On | Filter cases by last updated date. |
The response can also include active custom case fields that are available for the selected project and supported by dynamic filtering.
Using field names in dynamic filters
When using a field returned by this endpoint in a dynamic_filters payload, prefix the system_name with cases:.
For example, if this endpoint returns:
{
"type_id": 6,
"system_name": "priority_id",
"label": "Priority",
"options": "1, Low\n2, Medium\n3, High"
}Use the field as follows in a dynamic filter:
{
"mode": "1",
"filters": {
"cases:priority_id": {
"values": [2]
}
}
}Response codes
| Status Code | Description |
|---|---|
| 200 | Success. The available dynamic filter fields are returned as part of the response. |
| 400 | Invalid or unknown project. |
| 403 | No access to the project. |
| 429 | TestRail Cloud only - too many requests. |
Notes
This endpoint returns only the fields supported by TestRail’s dynamic filter behavior for the selected project. It should be used before constructing dynamic_filters payloads, especially when building API clients, CLIs, or integrations that need to render dynamic filter options outside of the TestRail UI.
Using dynamic filters with runs and plans
The get_dynamic_filter_fields endpoint is used to discover which fields can be used in a dynamic_filters payload. Dynamic filters are supported when creating or updating test runs and test plans, allowing API clients to create selections that behave like the TestRail UI’s Selection Filter.