Query observables

  • Updated on Jun 4, 2026
  • Published on Jan 1, 2024
Prev Next
Post
/v1alpha/observables/query

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

Security
HTTP
Type bearer
Body parameters

List observables request Returns a list of observables by filters.

Expand All
object

List observables request Returns a list of observables by filters.

filter
object (v1ListObservablesFilters)
types
Array of object (v1ObservableType)

The types of the observables to be retrieved.

Example[ "TYPE_ID_HOSTNAME", "TYPE_ID_IP_ADDRESS" ]
object
id
string
  • TYPE_ID_UNKNOWN: The observable type is unknown.
  • TYPE_ID_HOSTNAME: The observable type is Hostname.
  • TYPE_ID_IP_ADDRESS: The observable type is IP address.
  • TYPE_ID_MAC_ADDRESS: The observable type is MAC address.
  • TYPE_ID_USER_NAME: The observable type is User name.
  • TYPE_ID_EMAIL_ADDRESS: The observable type is Email.
  • TYPE_ID_URL: The observable type is URL.
  • TYPE_ID_FILE_NAME: The observable type is File name.
  • TYPE_ID_FILE_HASH: The observable type is File hash.
  • TYPE_ID_PROCESS_NAME: The observable type is Process name.
  • TYPE_ID_RESOURCE_UID: The observable type is Resource UID.
  • TYPE_ID_OTHER: The observable type is Other.
Valid values[ "TYPE_ID_UNKNOWN", "TYPE_ID_HOSTNAME", "TYPE_ID_IP_ADDRESS", "TYPE_ID_MAC_ADDRESS", "TYPE_ID_USER_NAME", "TYPE_ID_EMAIL_ADDRESS", "TYPE_ID_URL", "TYPE_ID_FILE_NAME", "TYPE_ID_FILE_HASH", "TYPE_ID_PROCESS_NAME", "TYPE_ID_RESOURCE_UID", "TYPE_ID_OTHER" ]
Default"TYPE_ID_UNKNOWN"
reputations
Array of object (v1Reputation)

The reputations of the observables to be retrieved.

object
id
string
  • SCORE_UNKNOWN: The reputation score is unknown.
  • SCORE_VERY_SAFE: The reputation score is Very safe.
  • SCORE_SAFE: The reputation score is Safe.
  • SCORE_PROBABLY_SAFE: The reputation score is Probably safe.
  • SCORE_LEANS_SAFE: The reputation score is Leans safe.
  • SCORE_MAY_NOT_BE_SAFE: The reputation score is May not be safe.
  • SCORE_EXERCISE_CAUTION: The reputation score is Exercise caution.
  • SCORE_SUSPICIOUS_OR_RISKY: The reputation score is Suspicious or risky.
  • SCORE_POSSIBLY_MALICIOUS: The reputation score is Possibly malicious.
  • SCORE_PROBABLY_MALICIOUS: The reputation score is Probably malicious.
  • SCORE_MALICIOUS: The reputation score is Malicious.
  • SCORE_OTHER: The reputation score is not mapped.
Valid values[ "SCORE_UNKNOWN", "SCORE_VERY_SAFE", "SCORE_SAFE", "SCORE_PROBABLY_SAFE", "SCORE_LEANS_SAFE", "SCORE_MAY_NOT_BE_SAFE", "SCORE_EXERCISE_CAUTION", "SCORE_SUSPICIOUS_OR_RISKY", "SCORE_POSSIBLY_MALICIOUS", "SCORE_PROBABLY_MALICIOUS", "SCORE_MALICIOUS", "SCORE_OTHER" ]
Default"SCORE_UNKNOWN"
first_observed_at
object (case_managementobservablesv1TimeRangeFilter)
start_time
string (date-time)

The start time for the filter.

end_time
string (date-time)

The end time for the filter.

last_observed_at
object (case_managementobservablesv1TimeRangeFilter)
start_time
string (date-time)

The start time for the filter.

end_time
string (date-time)

The end time for the filter.

sub_types
Array of object (v1ObservableSubType)

The sub types of the observables to be retrieved.

object
id
string

The sub type of the observable value.

  • SUB_TYPE_ID_UNKNOWN: The observable sub type is unknown.
  • SUB_TYPE_ID_HOSTNAME_FQDN: The observable type is Hostname and the sub type is FQDN.
  • SUB_TYPE_ID_HOSTNAME_NETBIOS: The observable type is hostname and the sub type is NetBIOS.
  • SUB_TYPE_ID_IP_ADDRESS_IPV4: The observable type is IP address and the sub type is IPv4.
  • SUB_TYPE_ID_IP_ADDRESS_IPV6: The observable type is IP address and the sub type is IPv6.
  • SUB_TYPE_ID_FILE_HASH_MD5: The observable type is File hash and the sub type is MD5.
  • SUB_TYPE_ID_FILE_HASH_SHA1: The observable type is File hash and the sub type is SHA1.
  • SUB_TYPE_ID_FILE_HASH_SHA256: The observable type is File hash and the sub type is SHA256.
  • SUB_TYPE_ID_USERNAME_UPN: The observable type is User name and the sub type is UPN.
  • SUB_TYPE_ID_USERNAME_DOMAIN: The observable type is User name and the sub type is Down-level Logon name.
  • SUB_TYPE_ID_OTHER: The observable type is Other.
Valid values[ "SUB_TYPE_ID_UNKNOWN", "SUB_TYPE_ID_HOSTNAME_FQDN", "SUB_TYPE_ID_HOSTNAME_NETBIOS", "SUB_TYPE_ID_IP_ADDRESS_IPV4", "SUB_TYPE_ID_IP_ADDRESS_IPV6", "SUB_TYPE_ID_FILE_HASH_MD5", "SUB_TYPE_ID_FILE_HASH_SHA1", "SUB_TYPE_ID_FILE_HASH_SHA256", "SUB_TYPE_ID_USERNAME_UPN", "SUB_TYPE_ID_USERNAME_DOMAIN", "SUB_TYPE_ID_OTHER" ]
Default"SUB_TYPE_ID_UNKNOWN"
search
string

Search term to filter observables by value. This will search across all observable value fields.

page_size
integer (int32)

The maximum number of observables 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.

page_token
string

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

order
string

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

Exampledesc
order_by
string

The criteria by which to sort the results. The possible values are: type, sub_type, reputation, first_seen, last_seen, case_count. Default is first_seen.

Examplefirst_seen
Responses
200

A successful response.

Expand All
object
observables
Array of object (v1Observable)

The list of observables.

object
id
integer (int32)

The unique identifier of the observable. This field value is automatically generated and shouldn't be provided when creating or updating an observable.

Example28
value
object (v1ObservableValue)
unknown
string

The observable value type is unknown. Only applicable when the observable type is TYPE_ID_UNKNOWN.

hostname
string

The observable value is a hostname. Only applicable when the observable type is TYPE_ID_HOSTNAME. The hostname represents a unique name assigned to a device connected to a computer network, as defined by RFC 1034.

Examplemachine-1
ip
string

The observable value is an IP address. Only applicable when the observable type is TYPE_ID_IP_ADDRESS. An IP address is an Internet Protocol address, in either IPv4 or IPv6 format.

Example127.0.0.1
mac_address
string

The observable value is a MAC (media access control) address. Only applicable when the observable type is TYPE_ID_MAC_ADDRESS.

Example00-B0-D0-63-C2-26
username
string

The observable value is a user name. Only applicable when the observable type is TYPE_ID_USER_NAME.

Examplejohn_dough_35
email_address
string

The observable value is an email. Only applicable when the observable type is TYPE_ID_EMAIL_ADDRESS. The email address is validated with RFC 5322.

Examplejohn@torq.io
url
string

The observable value is a URL (Uniform Resource Locator). Only applicable when the observable type is TYPE_ID_URL.

Examplehttps://app.torq.io
file_name
string

The observable value is a file name. Only applicable when the observable type is TYPE_ID_FILE_NAME.

Examplesuspicious.exe
file_hash
string

The observable value is a file hash. Only applicable when the observable type is TYPE_ID_FILE_HASH.

Example64e6df0ee478868b42d5eb7d443430283b0ddc0c
process_name
string

The observable value is a process name. Only applicable when the observable type is TYPE_ID_PROCESS_NAME.

Exampledoom.exe
resource_uid
string

The observable value is a resource UID. Only applicable when the observable type is TYPE_ID_RESOURCE_UID. Examples: S3 bucket name or an EC2 instance ID.

Example09e516de-65c9-45af-a6b2-02828fbabf67
other_type
string

The observable value type is Other. Only applicable when the observable type is TYPE_ID_OTHER.

type
object (v1ObservableType)
id
string
  • TYPE_ID_UNKNOWN: The observable type is unknown.
  • TYPE_ID_HOSTNAME: The observable type is Hostname.
  • TYPE_ID_IP_ADDRESS: The observable type is IP address.
  • TYPE_ID_MAC_ADDRESS: The observable type is MAC address.
  • TYPE_ID_USER_NAME: The observable type is User name.
  • TYPE_ID_EMAIL_ADDRESS: The observable type is Email.
  • TYPE_ID_URL: The observable type is URL.
  • TYPE_ID_FILE_NAME: The observable type is File name.
  • TYPE_ID_FILE_HASH: The observable type is File hash.
  • TYPE_ID_PROCESS_NAME: The observable type is Process name.
  • TYPE_ID_RESOURCE_UID: The observable type is Resource UID.
  • TYPE_ID_OTHER: The observable type is Other.
Valid values[ "TYPE_ID_UNKNOWN", "TYPE_ID_HOSTNAME", "TYPE_ID_IP_ADDRESS", "TYPE_ID_MAC_ADDRESS", "TYPE_ID_USER_NAME", "TYPE_ID_EMAIL_ADDRESS", "TYPE_ID_URL", "TYPE_ID_FILE_NAME", "TYPE_ID_FILE_HASH", "TYPE_ID_PROCESS_NAME", "TYPE_ID_RESOURCE_UID", "TYPE_ID_OTHER" ]
Default"TYPE_ID_UNKNOWN"
name
string

The name of the observable type. The name is automatically derived from the type ID.

reputation
object (v1Reputation)
id
string
  • SCORE_UNKNOWN: The reputation score is unknown.
  • SCORE_VERY_SAFE: The reputation score is Very safe.
  • SCORE_SAFE: The reputation score is Safe.
  • SCORE_PROBABLY_SAFE: The reputation score is Probably safe.
  • SCORE_LEANS_SAFE: The reputation score is Leans safe.
  • SCORE_MAY_NOT_BE_SAFE: The reputation score is May not be safe.
  • SCORE_EXERCISE_CAUTION: The reputation score is Exercise caution.
  • SCORE_SUSPICIOUS_OR_RISKY: The reputation score is Suspicious or risky.
  • SCORE_POSSIBLY_MALICIOUS: The reputation score is Possibly malicious.
  • SCORE_PROBABLY_MALICIOUS: The reputation score is Probably malicious.
  • SCORE_MALICIOUS: The reputation score is Malicious.
  • SCORE_OTHER: The reputation score is not mapped.
Valid values[ "SCORE_UNKNOWN", "SCORE_VERY_SAFE", "SCORE_SAFE", "SCORE_PROBABLY_SAFE", "SCORE_LEANS_SAFE", "SCORE_MAY_NOT_BE_SAFE", "SCORE_EXERCISE_CAUTION", "SCORE_SUSPICIOUS_OR_RISKY", "SCORE_POSSIBLY_MALICIOUS", "SCORE_PROBABLY_MALICIOUS", "SCORE_MALICIOUS", "SCORE_OTHER" ]
Default"SCORE_UNKNOWN"
name
string

The reputation name. The name is automatically derived from the reputation ID.

first_observed_at
string (date-time)

The time when the observable was first observed. This field value is automatically generated and shouldn't be provided when creating or updating an observable.

last_observed_at
string (date-time)

The time when the observable was last observed. This field value is automatically generated and shouldn't be provided when creating or updating an observable.

description
string

The observable description.

Examplea files suspected as malicious
sub_type
object (v1ObservableSubType)
id
string

The sub type of the observable value.

  • SUB_TYPE_ID_UNKNOWN: The observable sub type is unknown.
  • SUB_TYPE_ID_HOSTNAME_FQDN: The observable type is Hostname and the sub type is FQDN.
  • SUB_TYPE_ID_HOSTNAME_NETBIOS: The observable type is hostname and the sub type is NetBIOS.
  • SUB_TYPE_ID_IP_ADDRESS_IPV4: The observable type is IP address and the sub type is IPv4.
  • SUB_TYPE_ID_IP_ADDRESS_IPV6: The observable type is IP address and the sub type is IPv6.
  • SUB_TYPE_ID_FILE_HASH_MD5: The observable type is File hash and the sub type is MD5.
  • SUB_TYPE_ID_FILE_HASH_SHA1: The observable type is File hash and the sub type is SHA1.
  • SUB_TYPE_ID_FILE_HASH_SHA256: The observable type is File hash and the sub type is SHA256.
  • SUB_TYPE_ID_USERNAME_UPN: The observable type is User name and the sub type is UPN.
  • SUB_TYPE_ID_USERNAME_DOMAIN: The observable type is User name and the sub type is Down-level Logon name.
  • SUB_TYPE_ID_OTHER: The observable type is Other.
Valid values[ "SUB_TYPE_ID_UNKNOWN", "SUB_TYPE_ID_HOSTNAME_FQDN", "SUB_TYPE_ID_HOSTNAME_NETBIOS", "SUB_TYPE_ID_IP_ADDRESS_IPV4", "SUB_TYPE_ID_IP_ADDRESS_IPV6", "SUB_TYPE_ID_FILE_HASH_MD5", "SUB_TYPE_ID_FILE_HASH_SHA1", "SUB_TYPE_ID_FILE_HASH_SHA256", "SUB_TYPE_ID_USERNAME_UPN", "SUB_TYPE_ID_USERNAME_DOMAIN", "SUB_TYPE_ID_OTHER" ]
Default"SUB_TYPE_ID_UNKNOWN"
name
string

The name of the observable sub type. The name is automatically derived from the sub type ID.

enrichment
object

The observable enrichment data in JSON format.

associated_cases_count
integer (int32)

The number of cases that this observable is associated with.

updated_at
string (date-time)

The timestamp of when the observable was last updated. This value is automatically generated.

enrichment_updated_at
string (date-time)

The timestamp of when the observable enrichment field was last updated. This value is automatically generated.

deleted_at
string (date-time)

The timestamp of when the observable was deleted.

threat_intel
object (v1ThreatIntel)

ThreatIntel represents the complete threat intelligence data for an observable.

detection
object (v1DetectionInfo)

DetectionInfo represents aggregated detection information from multiple vendors.

verdict
object (v1Verdict)

Verdict represents a threat intel verdict with an ID and name.

id
string

VerdictID represents the verdict classification for a threat intel detection.

  • VERDICT_ID_UNSPECIFIED: The verdict is unspecified.
  • VERDICT_ID_UNKNOWN: The verdict is unknown.
  • VERDICT_ID_KNOWN: The observable is known and not malicious.
  • VERDICT_ID_SUSPICIOUS: The observable is suspicious.
  • VERDICT_ID_MALICIOUS: The observable is malicious.
Valid values[ "VERDICT_ID_UNSPECIFIED", "VERDICT_ID_UNKNOWN", "VERDICT_ID_KNOWN", "VERDICT_ID_SUSPICIOUS", "VERDICT_ID_MALICIOUS" ]
Default"VERDICT_ID_UNSPECIFIED"
name
string

The name of the verdict, automatically derived from the verdict ID.

detected_count
integer (int32)

The number of vendors that flagged the observable as malicious.

total_count
integer (int32)

The total number of vendors that scanned the observable.

last_scanned
string (date-time)

The time when the observable was last scanned.

vendors
Array of object (v1VendorDetection)

The list of vendor detections.

object

VendorDetection represents a detection result from a specific vendor.

name
string

The name of the vendor.

verdict
object (v1Verdict)

Verdict represents a threat intel verdict with an ID and name.

id
string

VerdictID represents the verdict classification for a threat intel detection.

  • VERDICT_ID_UNSPECIFIED: The verdict is unspecified.
  • VERDICT_ID_UNKNOWN: The verdict is unknown.
  • VERDICT_ID_KNOWN: The observable is known and not malicious.
  • VERDICT_ID_SUSPICIOUS: The observable is suspicious.
  • VERDICT_ID_MALICIOUS: The observable is malicious.
Valid values[ "VERDICT_ID_UNSPECIFIED", "VERDICT_ID_UNKNOWN", "VERDICT_ID_KNOWN", "VERDICT_ID_SUSPICIOUS", "VERDICT_ID_MALICIOUS" ]
Default"VERDICT_ID_UNSPECIFIED"
name
string

The name of the verdict, automatically derived from the verdict ID.

metadata
object

Additional metadata from the vendor.

property*
string additionalProperties
update_time
string (date-time)

The time when the vendor last updated the detection.

ip
object (v1IPThreatIntel)

IPThreatIntel represents IP-specific threat intelligence data.

asn
string

The Autonomous System Number.

owner
string

The owner of the ASN (e.g. "MICROSOFT-CORP-MSN-AS-BLOCK").

country
string

The country where the IP is located.

last_seen
string (date-time)

The last time the IP was seen by threat intel sources.

whois
object (v1WHOISInfo)

WHOISInfo represents WHOIS registration data as flexible key-value pairs.

fields
object

Key-value pairs of WHOIS fields (e.g. NetRange, CIDR, Organization, RegDate).

property*
string additionalProperties
last_updated
string (date-time)

The time when the WHOIS record was last updated.

domain
object (v1DomainThreatIntel)

DomainThreatIntel represents domain-specific threat intelligence data.

categories
Array of string

The categories assigned to the domain by threat intel sources.

string
dns
object (v1DNSInfo)

DNSInfo represents DNS record information for a domain.

a_records
Array of string

The A records (IPv4 addresses).

string
ns_records
Array of string

The NS records (name servers).

string
mx_records
Array of string

The MX records (mail exchange).

string
last_updated
string (date-time)

The time when DNS records were last updated.

last_seen
string (date-time)

The last time the domain was seen by threat intel sources.

whois
object (v1WHOISInfo)

WHOISInfo represents WHOIS registration data as flexible key-value pairs.

fields
object

Key-value pairs of WHOIS fields (e.g. NetRange, CIDR, Organization, RegDate).

property*
string additionalProperties
last_updated
string (date-time)

The time when the WHOIS record was last updated.

url
object (v1URLThreatIntel)

URLThreatIntel represents URL-specific threat intelligence data.

categories
Array of string

The categories assigned to the URL by threat intel sources.

string
threat_name
string

The threat classification name.

classification_reason
string

The reason for the threat classification.

last_seen
string (date-time)

The last time the URL was seen by threat intel sources.

hash
object (v1HashThreatIntel)

HashThreatIntel represents file hash-specific threat intelligence data.

malware_family
string

The malware family name (e.g. "Trojan.Cobalt_Strike/Beacon").

file_info
object (v1FileInfo)

FileInfo represents file metadata for a hash observable.

type
string

The file type (e.g. "PE32 executable (DLL)").

size
string (int64)

The size of the file in bytes.

names
Array of string

The known file names associated with this hash.

string
signature
object (v1SignatureInfo)

SignatureInfo represents digital signature information for a file.

status
object (v1SignatureStatus)

SignatureStatus represents a digital signature status with an ID and name.

id
string

SignatureStatusID represents the status of a digital signature.

  • SIGNATURE_STATUS_ID_UNSPECIFIED: The signature status is unspecified.
  • SIGNATURE_STATUS_ID_UNSIGNED: The file is unsigned.
  • SIGNATURE_STATUS_ID_VALID: The signature is valid.
  • SIGNATURE_STATUS_ID_INVALID: The signature is invalid.
  • SIGNATURE_STATUS_ID_EXPIRED: The signature has expired.
Valid values[ "SIGNATURE_STATUS_ID_UNSPECIFIED", "SIGNATURE_STATUS_ID_UNSIGNED", "SIGNATURE_STATUS_ID_VALID", "SIGNATURE_STATUS_ID_INVALID", "SIGNATURE_STATUS_ID_EXPIRED" ]
Default"SIGNATURE_STATUS_ID_UNSPECIFIED"
name
string

The name of the signature status, automatically derived from the status ID.

signer
string

The entity that signed the file.

threat_intel_updated_at
string (date-time)

The timestamp when the threat intelligence data was last updated.

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 observables 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