Query cases

  • Updated on Nov 5, 2024
  • 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.
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" ]
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)
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. 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.

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.

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
default

An unexpected error response.

Expand All
object
code
integer (int32)
message
string
details
Array of object (protobufAny)
object

Any contains an arbitrary serialized protocol buffer message along with a URL that describes the type of the serialized message.

Protobuf library provides support to pack/unpack Any values in the form of utility functions or additional generated methods of the Any type.

Example 1: Pack and unpack a message in C++.

Foo foo = ...; Any any; any.PackFrom(foo); ... if (any.UnpackTo(&foo))

Example 2: Pack and unpack a message in Java.

Foo foo = ...; Any any = Any.pack(foo); ... if (any.is(Foo.class)) // or ... if (any.isSameTypeAs(Foo.getDefaultInstance()))

Example 3: Pack and unpack a message in Python.

foo = Foo(...) any = Any() any.Pack(foo) ... if any.Is(Foo.DESCRIPTOR): any.Unpack(foo) ...

Example 4: Pack and unpack a message in Go

foo := &pb.Foo any, err := anypb.New(foo) if err != nil ... foo := &pb.Foo if err := any.UnmarshalTo(foo); err != nil

The pack methods provided by protobuf library will by default use 'type.googleapis.com/full.type.name' as the type URL and the unpack methods only use the fully qualified type name after the last '/' in the type URL, for example "foo.bar.com/x/y.z" will yield type name "y.z".

JSON

The JSON representation of an Any value uses the regular representation of the deserialized, embedded message, with an additional field @type which contains the type URL. Example:

package google.profile; message Person

{ "@type": "type.googleapis.com/google.profile.Person", "firstName": , "lastName": }

If the embedded message type is well-known and has a custom JSON representation, that representation will be embedded adding a field value which holds the custom JSON in addition to the @type field. Example (for message [google.protobuf.Duration][]):

{ "@type": "type.googleapis.com/google.protobuf.Duration", "value": "1.212s" }

@type
string

A URL/resource name that uniquely identifies the type of the serialized protocol buffer message. This string must contain at least one "/" character. The last segment of the URL's path must represent the fully qualified name of the type (as in path/google.protobuf.Duration). The name should be in a canonical form (e.g., leading "." is not accepted).

In practice, teams usually precompile into the binary all types that they expect it to use in the context of Any. However, for URLs which use the scheme http, https, or no scheme, one can optionally set up a type server that maps type URLs to message definitions as follows:

  • If no scheme is provided, https is assumed.
  • An HTTP GET on the URL must yield a [google.protobuf.Type][] value in binary format, or produce an error.
  • Applications are allowed to cache lookup results based on the URL, or have them precompiled into a binary to avoid any lookup. Therefore, binary compatibility needs to be preserved on changes to types. (Use versioned type names to manage breaking changes.)

Note: this functionality is not currently available in the official protobuf release, and it is not used for type URLs beginning with type.googleapis.com. As of May 2023, there are no widely used type server implementations and no plans to implement one.

Schemes other than http, https (or the empty scheme) might be used with implementation specific semantics.

property*
object additionalProperties