> ## Documentation Index > Fetch the complete documentation index at: https://developers.torq.io/llms.txt > Use this file to discover all available pages before exploring further. # Query observables > Returns a list of all observables within the workspace that match the provided query. ## OpenAPI ````json POST /v1alpha/observables/query { "openapi": "3.0.1", "info": { "contact": { "email": "support@torq.io", "name": "torq.io", "url": "https://torq.io" }, "title": "Torq Public API[development]", "version": "${DH_DEPLOY_VERSION}" }, "servers": [ { "url": "https://api.torq.io/public", "description": "US Environment" }, { "url": "https://api.eu.torq.io/public", "description": "European Enviornment" } ], "security": [ { "bearerAuth": [] } ], "tags": [ { "name": "ActivityLogs" }, { "name": "Users" }, { "name": "ApiKeys" }, { "name": "AuditLogs" }, { "name": "Executions" }, { "name": "ShareRequests" }, { "name": "StepRunners" }, { "name": "Integrations" }, { "name": "IPAccessService" }, { "name": "RolesService" }, { "name": "Secrets" }, { "name": "SecuritySettingsService" }, { "name": "ClaimMappings" }, { "name": "IdpSsoService" }, { "name": "Workflows" }, { "name": "Workspaces" }, { "name": "WorkspaceVariables" }, { "name": "Cases" }, { "name": "Cases Attachments" }, { "name": "Cases Custom Fields" }, { "name": "Cases Notes" }, { "name": "Observables" }, { "name": "Cases Observables" }, { "name": "CaseSearchService" }, { "name": "Cases Links" }, { "name": "Cases Events" }, { "name": "ExtendedCaseService" }, { "name": "Cases Runbooks" } ], "externalDocs": { "description": "Torq Documentation", "url": "https://learn.torq.io" }, "x-original-swagger-version": "2.0", "paths": { "/v1alpha/observables/query": { "post": { "description": "Returns a list of all observables within the workspace that match the provided query.", "operationId": "queryObservables", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/v1ListObservablesRequest" } } }, "description": "List observables request\nReturns a list of observables by filters.", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/v1ListObservablesResponse" } } }, "description": "A successful response." }, "401": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "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." }, "403": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "You don't have permission to access this resource." } }, "summary": "Query observables", "tags": [ "Observables" ], "x-codegen-request-body-name": "body" } } }, "components": { "schemas": { "v1ListObservablesRequest": { "description": "List observables request\nReturns a list of observables by filters.", "properties": { "filter": { "$ref": "#/components/schemas/v1ListObservablesFilters" }, "page_size": { "description": "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](https://learn.torq.io/apidocs/pagination) to retrieve the next page of results.", "format": "int32", "type": "integer" }, "page_token": { "description": "The token received from a previous `List observables` request. Provide this to retrieve the next page of results.", "type": "string" }, "order": { "description": "The order in which to sort the results. The possible values are: asc (ascending), desc (descending). Default is desc.", "example": "desc", "type": "string" }, "order_by": { "description": "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.", "example": "first_seen", "type": "string" } }, "type": "object" }, "v1ListObservablesResponse": { "properties": { "observables": { "description": "The list of observables.", "items": { "$ref": "#/components/schemas/v1Observable" }, "type": "array" }, "next_page_token": { "description": "When a token is returned it indicates there is another page of results to retrieve.\nPass this token in the page_token parameter in a subsequent `List observables` request to retrieve the next page of results.\nIf this field isn't returned it means there are no additional pages to retrieve.", "type": "string" } }, "title": "List observables response", "type": "object" }, "v1ListObservablesFilters": { "properties": { "types": { "description": "The types of the observables to be retrieved.", "example": [ "TYPE_ID_HOSTNAME", "TYPE_ID_IP_ADDRESS" ], "items": { "$ref": "#/components/schemas/v1ObservableType" }, "type": "array" }, "reputations": { "description": "The reputations of the observables to be retrieved.", "items": { "$ref": "#/components/schemas/v1Reputation" }, "type": "array" }, "first_observed_at": { "$ref": "#/components/schemas/case_managementobservablesv1TimeRangeFilter" }, "last_observed_at": { "$ref": "#/components/schemas/case_managementobservablesv1TimeRangeFilter" }, "sub_types": { "description": "The sub types of the observables to be retrieved.", "items": { "$ref": "#/components/schemas/v1ObservableSubType" }, "type": "array" }, "search": { "description": "Search term to filter observables by value. This will search across all observable value fields.", "type": "string" } }, "title": "ListObservableFilters - represent the filter to list observables", "type": "object" }, "v1Observable": { "properties": { "id": { "description": "The unique identifier of the observable. This field value is automatically generated and shouldn't be provided when creating or updating an observable.", "example": 28, "format": "int32", "type": "integer" }, "value": { "$ref": "#/components/schemas/v1ObservableValue" }, "type": { "$ref": "#/components/schemas/v1ObservableType" }, "reputation": { "$ref": "#/components/schemas/v1Reputation" }, "first_observed_at": { "description": "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.", "format": "date-time", "readOnly": true, "type": "string" }, "last_observed_at": { "description": "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.", "format": "date-time", "readOnly": true, "type": "string" }, "description": { "description": "The observable description.", "example": "a files suspected as malicious", "type": "string" }, "sub_type": { "$ref": "#/components/schemas/v1ObservableSubType" }, "enrichment": { "description": "The observable enrichment data in JSON format.", "type": "object" }, "associated_cases_count": { "description": "The number of cases that this observable is associated with.", "format": "int32", "readOnly": true, "type": "integer" }, "updated_at": { "description": "The timestamp of when the observable was last updated. This value is automatically generated.", "format": "date-time", "readOnly": true, "type": "string" }, "enrichment_updated_at": { "description": "The timestamp of when the observable enrichment field was last updated. This value is automatically generated.", "format": "date-time", "readOnly": true, "type": "string" }, "deleted_at": { "description": "The timestamp of when the observable was deleted.", "format": "date-time", "readOnly": true, "type": "string" }, "threat_intel": { "$ref": "#/components/schemas/v1ThreatIntel" }, "threat_intel_updated_at": { "description": "The timestamp when the threat intelligence data was last updated.", "format": "date-time", "readOnly": true, "type": "string" } }, "title": "Observable", "type": "object" }, "v1ObservableType": { "properties": { "id": { "$ref": "#/components/schemas/ObservableTypeTypeID" }, "name": { "description": "The name of the observable type. The name is automatically derived from the type ID.", "readOnly": true, "type": "string" } }, "title": "Type of the observable", "type": "object" }, "v1Reputation": { "properties": { "id": { "$ref": "#/components/schemas/ReputationScore" }, "name": { "description": "The reputation name. The name is automatically derived from the reputation ID.", "readOnly": true, "type": "string" } }, "title": "Reputation of the observable", "type": "object" }, "case_managementobservablesv1TimeRangeFilter": { "properties": { "start_time": { "description": "The start time for the filter.", "format": "date-time", "type": "string" }, "end_time": { "description": "The end time for the filter.", "format": "date-time", "type": "string" } }, "title": "Filter by range of time", "type": "object" }, "v1ObservableSubType": { "properties": { "id": { "$ref": "#/components/schemas/ObservableSubTypeSubTypeID" }, "name": { "description": "The name of the observable sub type. The name is automatically derived from the sub type ID.", "readOnly": true, "type": "string" } }, "title": "Sub Type of the observable", "type": "object" }, "v1ObservableValue": { "properties": { "unknown": { "description": "The observable value type is unknown. Only applicable when the observable type is TYPE_ID_UNKNOWN.", "type": "string" }, "hostname": { "description": "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.", "example": "machine-1", "type": "string" }, "ip": { "description": "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.", "example": "127.0.0.1", "type": "string" }, "mac_address": { "description": "The observable value is a MAC (media access control) address. Only applicable when the observable type is TYPE_ID_MAC_ADDRESS.", "example": "00-B0-D0-63-C2-26", "type": "string" }, "username": { "description": "The observable value is a user name. Only applicable when the observable type is TYPE_ID_USER_NAME.", "example": "john_dough_35", "type": "string" }, "email_address": { "description": "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.", "example": "john@torq.io", "type": "string" }, "url": { "description": "The observable value is a URL (Uniform Resource Locator). Only applicable when the observable type is TYPE_ID_URL.", "example": "https://app.torq.io", "type": "string" }, "file_name": { "description": "The observable value is a file name. Only applicable when the observable type is TYPE_ID_FILE_NAME.", "example": "suspicious.exe", "type": "string" }, "file_hash": { "description": "The observable value is a file hash. Only applicable when the observable type is TYPE_ID_FILE_HASH.", "example": "64e6df0ee478868b42d5eb7d443430283b0ddc0c", "type": "string" }, "process_name": { "description": "The observable value is a process name. Only applicable when the observable type is TYPE_ID_PROCESS_NAME.", "example": "doom.exe", "type": "string" }, "resource_uid": { "description": "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.", "example": "09e516de-65c9-45af-a6b2-02828fbabf67", "type": "string" }, "other_type": { "description": "The observable value type is Other. Only applicable when the observable type is TYPE_ID_OTHER.", "type": "string" } }, "title": "Observable Value representation", "type": "object" }, "v1ThreatIntel": { "description": "ThreatIntel represents the complete threat intelligence data for an observable.", "properties": { "detection": { "$ref": "#/components/schemas/v1DetectionInfo" }, "ip": { "$ref": "#/components/schemas/v1IPThreatIntel" }, "domain": { "$ref": "#/components/schemas/v1DomainThreatIntel" }, "url": { "$ref": "#/components/schemas/v1URLThreatIntel" }, "hash": { "$ref": "#/components/schemas/v1HashThreatIntel" } }, "type": "object" }, "ObservableTypeTypeID": { "default": "TYPE_ID_UNKNOWN", "description": "- TYPE_ID_UNKNOWN: The observable type is unknown.\n - TYPE_ID_HOSTNAME: The observable type is Hostname.\n - TYPE_ID_IP_ADDRESS: The observable type is IP address.\n - TYPE_ID_MAC_ADDRESS: The observable type is MAC address.\n - TYPE_ID_USER_NAME: The observable type is User name.\n - TYPE_ID_EMAIL_ADDRESS: The observable type is Email.\n - TYPE_ID_URL: The observable type is URL.\n - TYPE_ID_FILE_NAME: The observable type is File name.\n - TYPE_ID_FILE_HASH: The observable type is File hash.\n - TYPE_ID_PROCESS_NAME: The observable type is Process name.\n - TYPE_ID_RESOURCE_UID: The observable type is Resource UID.\n - TYPE_ID_OTHER: The observable type is Other.", "enum": [ "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" ], "title": "TypeID - represent the type of the observable", "type": "string" }, "ReputationScore": { "default": "SCORE_UNKNOWN", "description": "- SCORE_UNKNOWN: The reputation score is unknown.\n - SCORE_VERY_SAFE: The reputation score is Very safe.\n - SCORE_SAFE: The reputation score is Safe.\n - SCORE_PROBABLY_SAFE: The reputation score is Probably safe.\n - SCORE_LEANS_SAFE: The reputation score is Leans safe.\n - SCORE_MAY_NOT_BE_SAFE: The reputation score is May not be safe.\n - SCORE_EXERCISE_CAUTION: The reputation score is Exercise caution.\n - SCORE_SUSPICIOUS_OR_RISKY: The reputation score is Suspicious or risky.\n - SCORE_POSSIBLY_MALICIOUS: The reputation score is Possibly malicious.\n - SCORE_PROBABLY_MALICIOUS: The reputation score is Probably malicious.\n - SCORE_MALICIOUS: The reputation score is Malicious.\n - SCORE_OTHER: The reputation score is not mapped.", "enum": [ "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" ], "title": "The observable reputation score", "type": "string" }, "ObservableSubTypeSubTypeID": { "default": "SUB_TYPE_ID_UNKNOWN", "description": "The sub type of the observable value.\n\n - SUB_TYPE_ID_UNKNOWN: The observable sub type is unknown.\n - SUB_TYPE_ID_HOSTNAME_FQDN: The observable type is Hostname and the sub type is FQDN.\n - SUB_TYPE_ID_HOSTNAME_NETBIOS: The observable type is hostname and the sub type is NetBIOS.\n - SUB_TYPE_ID_IP_ADDRESS_IPV4: The observable type is IP address and the sub type is IPv4.\n - SUB_TYPE_ID_IP_ADDRESS_IPV6: The observable type is IP address and the sub type is IPv6.\n - SUB_TYPE_ID_FILE_HASH_MD5: The observable type is File hash and the sub type is MD5.\n - SUB_TYPE_ID_FILE_HASH_SHA1: The observable type is File hash and the sub type is SHA1.\n - SUB_TYPE_ID_FILE_HASH_SHA256: The observable type is File hash and the sub type is SHA256.\n - SUB_TYPE_ID_USERNAME_UPN: The observable type is User name and the sub type is UPN.\n - SUB_TYPE_ID_USERNAME_DOMAIN: The observable type is User name and the sub type is Down-level Logon name.\n - SUB_TYPE_ID_OTHER: The observable type is Other.", "enum": [ "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" ], "type": "string" }, "v1DetectionInfo": { "description": "DetectionInfo represents aggregated detection information from multiple vendors.", "properties": { "verdict": { "$ref": "#/components/schemas/v1Verdict" }, "detected_count": { "description": "The number of vendors that flagged the observable as malicious.", "format": "int32", "type": "integer" }, "total_count": { "description": "The total number of vendors that scanned the observable.", "format": "int32", "type": "integer" }, "last_scanned": { "description": "The time when the observable was last scanned.", "format": "date-time", "type": "string" }, "vendors": { "description": "The list of vendor detections.", "items": { "$ref": "#/components/schemas/v1VendorDetection" }, "type": "array" } }, "type": "object" }, "v1IPThreatIntel": { "description": "IPThreatIntel represents IP-specific threat intelligence data.", "properties": { "asn": { "description": "The Autonomous System Number.", "type": "string" }, "owner": { "description": "The owner of the ASN (e.g. \"MICROSOFT-CORP-MSN-AS-BLOCK\").", "type": "string" }, "country": { "description": "The country where the IP is located.", "type": "string" }, "last_seen": { "description": "The last time the IP was seen by threat intel sources.", "format": "date-time", "type": "string" }, "whois": { "$ref": "#/components/schemas/v1WHOISInfo" } }, "type": "object" }, "v1DomainThreatIntel": { "description": "DomainThreatIntel represents domain-specific threat intelligence data.", "properties": { "categories": { "description": "The categories assigned to the domain by threat intel sources.", "items": { "type": "string" }, "type": "array" }, "dns": { "$ref": "#/components/schemas/v1DNSInfo" }, "last_seen": { "description": "The last time the domain was seen by threat intel sources.", "format": "date-time", "type": "string" }, "whois": { "$ref": "#/components/schemas/v1WHOISInfo" } }, "type": "object" }, "v1URLThreatIntel": { "description": "URLThreatIntel represents URL-specific threat intelligence data.", "properties": { "categories": { "description": "The categories assigned to the URL by threat intel sources.", "items": { "type": "string" }, "type": "array" }, "threat_name": { "description": "The threat classification name.", "type": "string" }, "classification_reason": { "description": "The reason for the threat classification.", "type": "string" }, "last_seen": { "description": "The last time the URL was seen by threat intel sources.", "format": "date-time", "type": "string" } }, "type": "object" }, "v1HashThreatIntel": { "description": "HashThreatIntel represents file hash-specific threat intelligence data.", "properties": { "malware_family": { "description": "The malware family name (e.g. \"Trojan.Cobalt_Strike/Beacon\").", "type": "string" }, "file_info": { "$ref": "#/components/schemas/v1FileInfo" }, "signature": { "$ref": "#/components/schemas/v1SignatureInfo" } }, "type": "object" }, "v1Verdict": { "description": "Verdict represents a threat intel verdict with an ID and name.", "properties": { "id": { "$ref": "#/components/schemas/VerdictVerdictID" }, "name": { "description": "The name of the verdict, automatically derived from the verdict ID.", "readOnly": true, "type": "string" } }, "type": "object" }, "v1VendorDetection": { "description": "VendorDetection represents a detection result from a specific vendor.", "properties": { "name": { "description": "The name of the vendor.", "type": "string" }, "verdict": { "$ref": "#/components/schemas/v1Verdict" }, "metadata": { "additionalProperties": { "type": "string" }, "description": "Additional metadata from the vendor.", "type": "object" }, "update_time": { "description": "The time when the vendor last updated the detection.", "format": "date-time", "type": "string" } }, "type": "object" }, "v1WHOISInfo": { "description": "WHOISInfo represents WHOIS registration data as flexible key-value pairs.", "properties": { "fields": { "additionalProperties": { "type": "string" }, "description": "Key-value pairs of WHOIS fields (e.g. NetRange, CIDR, Organization, RegDate).", "type": "object" }, "last_updated": { "description": "The time when the WHOIS record was last updated.", "format": "date-time", "type": "string" } }, "type": "object" }, "v1DNSInfo": { "description": "DNSInfo represents DNS record information for a domain.", "properties": { "a_records": { "description": "The A records (IPv4 addresses).", "items": { "type": "string" }, "type": "array" }, "ns_records": { "description": "The NS records (name servers).", "items": { "type": "string" }, "type": "array" }, "mx_records": { "description": "The MX records (mail exchange).", "items": { "type": "string" }, "type": "array" }, "last_updated": { "description": "The time when DNS records were last updated.", "format": "date-time", "type": "string" } }, "type": "object" }, "v1FileInfo": { "description": "FileInfo represents file metadata for a hash observable.", "properties": { "type": { "description": "The file type (e.g. \"PE32 executable (DLL)\").", "type": "string" }, "size": { "description": "The size of the file in bytes.", "format": "int64", "type": "string" }, "names": { "description": "The known file names associated with this hash.", "items": { "type": "string" }, "type": "array" } }, "type": "object" }, "v1SignatureInfo": { "description": "SignatureInfo represents digital signature information for a file.", "properties": { "status": { "$ref": "#/components/schemas/v1SignatureStatus" }, "signer": { "description": "The entity that signed the file.", "type": "string" } }, "type": "object" }, "VerdictVerdictID": { "default": "VERDICT_ID_UNSPECIFIED", "description": "VerdictID represents the verdict classification for a threat intel detection.\n\n - VERDICT_ID_UNSPECIFIED: The verdict is unspecified.\n - VERDICT_ID_UNKNOWN: The verdict is unknown.\n - VERDICT_ID_KNOWN: The observable is known and not malicious.\n - VERDICT_ID_SUSPICIOUS: The observable is suspicious.\n - VERDICT_ID_MALICIOUS: The observable is malicious.", "enum": [ "VERDICT_ID_UNSPECIFIED", "VERDICT_ID_UNKNOWN", "VERDICT_ID_KNOWN", "VERDICT_ID_SUSPICIOUS", "VERDICT_ID_MALICIOUS" ], "type": "string" }, "v1SignatureStatus": { "description": "SignatureStatus represents a digital signature status with an ID and name.", "properties": { "id": { "$ref": "#/components/schemas/SignatureStatusSignatureStatusID" }, "name": { "description": "The name of the signature status, automatically derived from the status ID.", "readOnly": true, "type": "string" } }, "type": "object" }, "SignatureStatusSignatureStatusID": { "default": "SIGNATURE_STATUS_ID_UNSPECIFIED", "description": "SignatureStatusID represents the status of a digital signature.\n\n - SIGNATURE_STATUS_ID_UNSPECIFIED: The signature status is unspecified.\n - SIGNATURE_STATUS_ID_UNSIGNED: The file is unsigned.\n - SIGNATURE_STATUS_ID_VALID: The signature is valid.\n - SIGNATURE_STATUS_ID_INVALID: The signature is invalid.\n - SIGNATURE_STATUS_ID_EXPIRED: The signature has expired.", "enum": [ "SIGNATURE_STATUS_ID_UNSPECIFIED", "SIGNATURE_STATUS_ID_UNSIGNED", "SIGNATURE_STATUS_ID_VALID", "SIGNATURE_STATUS_ID_INVALID", "SIGNATURE_STATUS_ID_EXPIRED" ], "type": "string" } }, "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "64fb4b65-44d8-4304-881c-b1f8b6b3100a" } } } } ````