Query cases

  • Updated on Nov 18, 2025
  • Published on Jan 1, 2024
  • 7 minute(s) read
Prev Next
Post
/v1alpha/cases/query

Returns a list of all cases within the workspace that match the provided query.

Security
HTTP
Type bearer
Body parameters
Expand All
object
filters
object (v1ListCasesFilters)
states
Array of object (case_managementcasesv1State)

The states of the cases to be retrieved.

Example[ { "value": "on hold" }, { "value": "closed" } ]
object
value
string

The name of the state. The default states are: new, in progress, on hold, resolved, closed. If your workspace has custom states, you can specify them by name.

Examplenew
severities
Array of object (v1Severity)

The severities of the cases to be retrieved.

Example[ { "value": "high" }, { "value": "critical" } ]
object
value
string

The severity of the case. The possible values are: informational, low, medium, high, critical.

Examplehigh
assignees
Array of string

The assignees of the cases to be retrieved.

Example[ "john@torq.io", "jane@torq.io" ]
string
created_at
object (case_managementcasesv1TimeRangeFilter)

Time range filter.

start_time
string (date-time)

The start time for the retrieval of cases within a specified creation time range.

end_time
string (date-time)

The end time for the retrieval of cases within a specified creation time range.

relative
string
  • RELATIVE_UNSPECIFIED: The relative time range is unspecified.
  • RELATIVE_LAST_15_MIN: The relative time range is 15 minutes.
  • RELATIVE_LAST_1_HOUR: The relative time range is 1 hour.
  • RELATIVE_LAST_4_HOURS: The relative time range is 4 hours.
  • RELATIVE_LAST_1_DAY: The relative time range is 1 day.
  • RELATIVE_LAST_2_DAYS: The relative time range is 2 days.
  • RELATIVE_LAST_7_DAYS: The relative time range is 7 days.
  • RELATIVE_LAST_14_DAYS: The relative time range is 14 days.
  • RELATIVE_LAST_30_DAYS: The relative time range is 30 days.
  • RELATIVE_LAST_90_DAYS: The relative time range is 90 days.
  • RELATIVE_LAST_1_MONTH: The relative time range is 1 month.
  • RELATIVE_LAST_3_MONTHS: The relative time range is 3 months.
Valid values[ "RELATIVE_UNSPECIFIED", "RELATIVE_LAST_15_MIN", "RELATIVE_LAST_1_HOUR", "RELATIVE_LAST_4_HOURS", "RELATIVE_LAST_1_DAY", "RELATIVE_LAST_2_DAYS", "RELATIVE_LAST_7_DAYS", "RELATIVE_LAST_14_DAYS", "RELATIVE_LAST_30_DAYS", "RELATIVE_LAST_90_DAYS", "RELATIVE_LAST_1_MONTH", "RELATIVE_LAST_3_MONTHS" ]
Default"RELATIVE_UNSPECIFIED"
text
string

The free text to match within the text fields of the cases to be retrieved.

Examplemalware
sla_range
object (v1SLARangeFilter)

Filter based on the duration passed relative to the SLA, measured as a percentage. Setting 'from' to 1 and 'to' to 0 will return all the cases with breached SLA.

from
number (float)

The minimum percentage of elapsed duration relative to the SLA, for instance, 0.2 indicating 20% elapsed.

Example0.2
to
number (float)

The maximum percentage of elapsed duration relative to the SLA, for instance, 0.5 indicating 50% elapsed.

Example0.5
categories
Array of string

The categories of the cases to be retrieved.

Example[ "malware", "phishing" ]
string
observable_ids
Array of integer

The observable IDs of the cases to be retrieved.

Example[ 28, 29 ]
integer (int32)
tags
Array of string

The tags of the cases to be retrieved.

Example[ "user", "phishing" ]
string
custom_fields
Array of object (v1ListCasesFiltersCustomField)

The custom fields of the cases to be retrieved.

object

Custom field key and value pair.

key
string

The custom field key.

Examplecustom_field_1
value
string

The custom field value.

Examplecustom_value_1
values
Array of string

The custom field values.

Example[ "user", "phishing" ]
string
resolution_reasons
Array of string

The resolution reasons of the cases to be retrieved.

Example[ "user", "phishing" ]
string
pending_tasks
integer (int32)

The minimum number of pending tasks in the cases to be retrieved. Retrieve cases that have at least the specified number of pending tasks. For example, for pending_tasks=2, cases that have 2 pending tasks or more will be retrieved.

Example2
runbook_names
Array of string

The runbook names of the cases to be retrieved.

Example[ "new user", "service interruption" ]
string
case_ids
Array of integer

The IDs of the cases to be retrieved.

integer (int32)
conclusions
Array of object (v1Conclusion)

Conclusions.

The review conclusions of the cases to be retrieved.

Example[ { "value": "approved" }, { "value": "rejected" } ]
object
value
string

The review conclusion. The default conclusions are Approved and Rejected, but they can be customized on the Cases settings page.

ExampleApproved
reviewers
Array of object (v1Actor)

Reviewers.

The reviewers of the cases to be retrieved.

Example[ { "user": "john@torq.io" }, { "user": "jane@torq.io" } ]
object
user
object (ActorUser)
email
string

The email of the actor. Only applicable when the actor is a user.

Examplejane@torq.io
updated_at
object (case_managementcasesv1TimeRangeFilter)

Time range filter.

start_time
string (date-time)

The start time for the retrieval of cases within a specified creation time range.

end_time
string (date-time)

The end time for the retrieval of cases within a specified creation time range.

relative
string
  • RELATIVE_UNSPECIFIED: The relative time range is unspecified.
  • RELATIVE_LAST_15_MIN: The relative time range is 15 minutes.
  • RELATIVE_LAST_1_HOUR: The relative time range is 1 hour.
  • RELATIVE_LAST_4_HOURS: The relative time range is 4 hours.
  • RELATIVE_LAST_1_DAY: The relative time range is 1 day.
  • RELATIVE_LAST_2_DAYS: The relative time range is 2 days.
  • RELATIVE_LAST_7_DAYS: The relative time range is 7 days.
  • RELATIVE_LAST_14_DAYS: The relative time range is 14 days.
  • RELATIVE_LAST_30_DAYS: The relative time range is 30 days.
  • RELATIVE_LAST_90_DAYS: The relative time range is 90 days.
  • RELATIVE_LAST_1_MONTH: The relative time range is 1 month.
  • RELATIVE_LAST_3_MONTHS: The relative time range is 3 months.
Valid values[ "RELATIVE_UNSPECIFIED", "RELATIVE_LAST_15_MIN", "RELATIVE_LAST_1_HOUR", "RELATIVE_LAST_4_HOURS", "RELATIVE_LAST_1_DAY", "RELATIVE_LAST_2_DAYS", "RELATIVE_LAST_7_DAYS", "RELATIVE_LAST_14_DAYS", "RELATIVE_LAST_30_DAYS", "RELATIVE_LAST_90_DAYS", "RELATIVE_LAST_1_MONTH", "RELATIVE_LAST_3_MONTHS" ]
Default"RELATIVE_UNSPECIFIED"
order
string

The order in which to sort the results. The possible values are: asc (ascending), desc (descending). Default is desc.

Exampleasc
order_by
string

The criteria by which to sort the results. The possible values are: severity, created_at, state, title, assignee, sla_expiration, category, updated_at. Default is severity.

Examplecreated_at
page_size
integer (int32)

The maximum number of cases to retrieve per page. Default is 100. Maximum is 500. If the number of results exceeds the defined page size, use pagination to retrieve the next page of results.

Example50
page_token
string

The token received from a previous List cases request. Provide this to retrieve the next page of results.

field_mask
string

Field mask to specify which fields to FILTER out from the response. If not provided, all fields are returned.

Exampleid,title,state,severity
Responses
200

A successful response.

Expand All
object
cases
Array of object (v1Case)

The returned cases.

object
id
integer (int32)

The unique identifier of the case.

Example28
pretty_id
string

The unique identifier of the case as displayed on the Cases page.

Example#28
title
string

The case title.

Examplecompromised user device
description
string

The case description.

ExampleA user device is infected with a malware
state
object (case_managementcasesv1State)
value
string

The name of the state. The default states are: new, in progress, on hold, resolved, closed. If your workspace has custom states, you can specify them by name.

Examplenew
severity
object (v1Severity)
value
string

The severity of the case. The possible values are: informational, low, medium, high, critical.

Examplehigh
assignee
string

The email address of the case assignee.

Examplejohn@torq.io
reporter
object (v1Actor)
kind
string

The actor kind. Supported values are: USER, WORKFLOW, SOCRATES.

user
object (ActorUser)
email
string

The email of the actor. Only applicable when the actor is a user.

Examplejane@torq.io
created_at
string (date-time)

The timestamp when the case was created.

updated_at
string (date-time)

The timestamp when the case was last updated.

completed_at
string (date-time)

The timestamp when the case was resolved or closed.

sla
object (v1Sla)
value
string (int64)

The duration, measured in seconds, from the creation of the case until it should be resolved or closed.

Example86400
start_time
string (date-time)

The timestamp when the case was created.

end_time
string (date-time)

The timestamp when the case was resolved or closed.

category
string

The case categpry.

Examplemalware
tags
Array of string

The case tags.

Example[ "user", "phishing" ]
string
tasks
object (v1Tasks)
pending
integer (int64)

The number of pending tasks.

Example3
resolution_summary
object (v1ResolutionSummary)
reason
string

The reason the case was resolved or closed (up to 100 characters).

Exampleuser device was cleaned
details
string

The detailed overview of the case resolution.

ExampleThe user device was cleaned using the following steps: ...
runbook_id
string

The case runbook ID.

review
object (v1Review)
reviewer
object (v1Actor)
kind
string

The actor kind. Supported values are: USER, WORKFLOW, SOCRATES.

user
object (ActorUser)
email
string

The email of the actor. Only applicable when the actor is a user.

Examplejane@torq.io
conclusion
object (v1Conclusion)
value
string

The review conclusion. The default conclusions are Approved and Rejected, but they can be customized on the Cases settings page.

ExampleApproved
note
string

The case review conclusion note, providing additional context.

Example
reviewed_by
object (v1Actor)
kind
string

The actor kind. Supported values are: USER, WORKFLOW, SOCRATES.

user
object (ActorUser)
email
string

The email of the actor. Only applicable when the actor is a user.

Examplejane@torq.io
access_policy_type
string
  • ACCESS_POLICY_UNSPECIFIED: The case is publicly accessible.
  • ACCESS_POLICY_PUBLIC: The case is publicly accessible.
  • ACCESS_POLICY_COLLABORATORS_LIST: The case is accessible only to a list of collaborators
Valid values[ "ACCESS_POLICY_UNSPECIFIED", "ACCESS_POLICY_PUBLIC", "ACCESS_POLICY_COLLABORATORS_LIST" ]
Default"ACCESS_POLICY_UNSPECIFIED"
access_mode
object (v1AccessMode)
id
string
  • ACCESS_POLICY_UNSPECIFIED: The case is publicly accessible.
  • ACCESS_POLICY_PUBLIC: The case is publicly accessible.
  • ACCESS_POLICY_COLLABORATORS_LIST: The case is accessible only to a list of collaborators
Valid values[ "ACCESS_POLICY_UNSPECIFIED", "ACCESS_POLICY_PUBLIC", "ACCESS_POLICY_COLLABORATORS_LIST" ]
Default"ACCESS_POLICY_UNSPECIFIED"
next_page_token
string

When a token is returned it indicates there is another page of results to retrieve. Pass this token in the page_token parameter in a subsequent List cases request to retrieve the next page of results. If this field isn't returned it means there are no additional pages to retrieve.

401

Invalid bearer token. If you receive this message more than once try creating a new Client ID/Client Secret or generating a new bearer token.

object
403

You don't have permission to access this resource.

object