--- updatedAt: 2026-07-31T16:28:22.000Z agentTools: projectIndex: https://docs.greynoise.io/llms.txt --- # Search Tactics Detections Search the Tactics detections recorded for a workspace. A detection is an aggregated view of a single attacker session observed on one of your deployed sensors: the commands that ran, the MITRE ATT&CK techniques and tactics they map to, the files the session touched, and the hosts it contacted. Only sessions carrying at least one ATT&CK technique are retained as detections, so activity that never matched a technique is not returned by this endpoint. Filters supplied in the request body are combined with AND, with one exception: `techniques` and `tactics` combine with each other using OR (a detection matches if it carries any listed technique **or** any listed tactic), and that bundle is then ANDed with the remaining filters. A body is required; send `{}` to apply no filters. Results are ordered newest first and paged with an opaque cursor: pass the `next_cursor` from a response back as the `cursor` query parameter to fetch the following page. `total_count`, `stats`, and `tactic_stats` are computed over the whole filtered result set and are returned only on the first page (when no `cursor` is supplied). Each detection in `sessions` carries a **bounded** `commands` preview — at most 40 of the session's distinct commands, in no particular order. Fetch the detection by ID for the complete, ordered command timeline. # OpenAPI definition ```json { "openapi": "3.0.0", "info": { "description": "GreyNoise is a cybersecurity company that collects and analyzes Internet-wide scan and attack traffic. Use GreyNoise to contextualize existing alerts, filter false-positives, identify compromised devices, and track emerging threats.", "version": "3.0.0", "title": "GreyNoise API", "contact": { "email": "hello@greynoise.io" }, "license": { "name": "Proprietary", "url": "https://www.greynoise.io/terms" } }, "tags": [ { "name": "Tactics", "description": "Endpoints for querying Tactics detections — aggregated attacker sessions\nobserved on your deployed sensors, labeled with MITRE ATT&CK\ntechniques and tactics. Search detections in a workspace, retrieve a\nsingle detection's command timeline, list the destination IPs it\ncontacted, and inspect the files it touched. Requires the Tactics\nentitlement.\n" } ], "security": [ { "APIKeyHeaderAuth": [] } ], "paths": { "/v3/workspaces/{workspace_id}/tactics": { "post": { "tags": [ "Tactics" ], "summary": "Search Tactics Detections", "operationId": "SearchTacticsDetections", "description": "Search the Tactics detections recorded for a workspace.\n\nA detection is an aggregated view of a single attacker session observed\non one of your deployed sensors: the commands that ran, the MITRE ATT&CK\ntechniques and tactics they map to, the files the session touched, and\nthe hosts it contacted. Only sessions carrying at least one ATT&CK\ntechnique are retained as detections, so activity that never matched a\ntechnique is not returned by this endpoint.\n\nFilters supplied in the request body are combined with AND, with one\nexception: `techniques` and `tactics` combine with each other using OR\n(a detection matches if it carries any listed technique **or** any\nlisted tactic), and that bundle is then ANDed with the remaining\nfilters. A body is required; send `{}` to apply no filters.\n\nResults are ordered newest first and paged with an opaque cursor: pass\nthe `next_cursor` from a response back as the `cursor` query parameter\nto fetch the following page. `total_count`, `stats`, and `tactic_stats`\nare computed over the whole filtered result set and are returned only\non the first page (when no `cursor` is supplied).\n\nEach detection in `sessions` carries a **bounded** `commands` preview —\nat most 40 of the session's distinct commands, in no particular order.\nFetch the detection by ID for the complete, ordered command timeline.\n", "parameters": [ { "$ref": "#/components/parameters/workspaceId" }, { "in": "query", "name": "page_size", "description": "Number of detections to return per page.", "required": false, "schema": { "type": "integer", "default": 100, "minimum": 1, "maximum": 10000 } }, { "in": "query", "name": "cursor", "description": "Opaque pagination cursor taken from a previous response's `next_cursor`. Omit to request the first page.\n", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "exclude_non_interactive", "description": "When `true`, return only interactive sessions (those with a shell ancestor). Non-interactive sessions are included by default.\n", "required": false, "schema": { "type": "boolean", "default": false } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TacticsSearchRequest" } } } }, "responses": { "200": { "description": "OK - matching detections returned.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TacticsSearchResponse" } } } }, "400": { "$ref": "#/components/responses/TacticsBadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/TacticsForbidden" }, "500": { "$ref": "#/components/responses/TacticsUnexpectedError" } } } } }, "servers": [ { "url": "https://api.greynoise.io" }, { "url": "http://api.greynoise.io" } ], "components": { "securitySchemes": { "APIKeyHeaderAuth": { "type": "apiKey", "in": "header", "name": "key" } }, "responses": { "Unauthorized": { "description": "Unauthorized. Please check your API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" }, "example": { "message": "Unauthorized" } } } }, "TacticsBadRequest": { "description": "Bad request - a path parameter, query parameter, or request body was\ninvalid. Validation errors raised by the Tactics backend are returned\nas a plain-text message; errors raised by the API gateway use the JSON\n`{\"message\": ...}` shape.\n", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ErrorMessage" }, { "type": "string" } ] }, "examples": { "invalidQueryParameter": { "value": "page_size must be an integer" }, "invalidRequestBody": { "value": "invalid request body: unexpected EOF" }, "gatewayError": { "value": { "message": "bad request: multiple workspaces provided" } } } } } }, "TacticsForbidden": { "description": "Forbidden - the workspace is not entitled to Tactics (or, for the host\nartifact content endpoint, not entitled to file contents), or the\nauthenticated user does not have access to the requested workspace.\nContact sales@greynoise.io to enable Tactics for your workspace.\n", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/TacticsError" }, { "$ref": "#/components/schemas/ErrorMessage" } ] }, "examples": { "missingEntitlement": { "value": { "error": "feature not enabled for this workspace" } }, "workspaceAccessDenied": { "value": { "message": "forbidden" } } } } } }, "TacticsUnexpectedError": { "description": "Unexpected error while serving the request. Errors raised by the\nTactics backend are returned as a plain-text message; errors raised by\nthe API gateway use the JSON `{\"message\": ...}` shape.\n", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ErrorMessage" }, { "type": "string" } ] }, "examples": { "gatewayError": { "value": { "message": "internal server error" } }, "serviceError": { "value": "Internal Server Error" } } } } } }, "parameters": { "workspaceId": { "name": "workspace_id", "in": "path", "description": "Workspace UUID.", "required": true, "schema": { "type": "string", "format": "uuid" } } }, "schemas": { "ErrorMessage": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "TacticsError": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "TacticsSearchRequest": { "type": "object", "description": "Detection search filters. Every field is optional; send `{}` to match all detections in the workspace. Fields combine with AND, except `techniques` and `tactics`, which combine with each other using OR.\n", "properties": { "start_time": { "type": "string", "format": "date-time", "description": "Only return detections active at or after this time. When omitted no lower bound is applied and the search spans all retained history; supplying a bound is strongly recommended.\n", "example": "2026-07-29T00:00:00Z" }, "end_time": { "type": "string", "format": "date-time", "description": "Only return detections active at or before this time. Defaults to the current time.\n", "example": "2026-07-30T00:00:00Z" }, "sensor_id": { "type": "string", "format": "uuid", "description": "Only return detections observed on this sensor." }, "profile_id": { "type": "string", "format": "uuid", "description": "Only return detections observed on this profile." }, "profile_instance_id": { "type": "string", "format": "uuid", "description": "Only return detections observed on this profile instance." }, "rules": { "type": "array", "description": "Only return detections that triggered at least one of these sensor rules.\n", "items": { "type": "string" }, "example": [ "command_run", "internet_access" ] }, "techniques": { "type": "array", "description": "Only return detections carrying at least one of these MITRE ATT&CK technique IDs. Combines with `tactics` using OR.\n", "items": { "type": "string" }, "example": [ "T1082", "T1059.004" ] }, "tactics": { "type": "array", "description": "Only return detections carrying at least one of these MITRE ATT&CK tactic IDs. Combines with `techniques` using OR.\n", "items": { "type": "string" }, "example": [ "TA0007", "TA0002" ] }, "process_name": { "type": "string", "description": "Only return detections containing an event whose process has this name.\n", "example": "curl" }, "process_parent": { "type": "string", "description": "Only return detections containing an event whose parent process has this name.\n", "example": "bash" }, "process_grandparent": { "type": "string", "description": "Only return detections containing an event whose grandparent process has this name.\n" }, "process_great_grandparent": { "type": "string", "description": "Only return detections containing an event whose great-grandparent process has this name.\n" }, "any_process": { "type": "string", "description": "Only return detections containing an event where this name appears at any level of the process ancestry - the process itself, its parent, grandparent, or great-grandparent.\n", "example": "wget" }, "ip": { "type": "string", "description": "Only return detections whose session contacted this destination address. IPv4 only.\n", "example": "198.51.100.42" } } }, "TacticsSearchResponse": { "type": "object", "properties": { "sessions": { "type": "array", "description": "The page of matching detections, ordered newest first. Named `sessions` because a detection is an aggregated attacker session.\n", "items": { "$ref": "#/components/schemas/TacticsDetectionSummary" } }, "has_more": { "type": "boolean", "description": "Whether a further page of detections is available.", "example": true }, "next_cursor": { "type": "string", "description": "Opaque cursor for the next page. Pass it back as the `cursor` query parameter. Omitted when `has_more` is false.\n", "example": "eyJ0IjoiMjAyNi0wNy0yOVQxNDoxMjowM1oiLCJzIjoiMDE5MWQ4YzQtOTk0Yy04ZmMyLWEwNzMtM2ZlM2NjYjRhMDFmIn0=" }, "total_count": { "type": "integer", "format": "int64", "description": "Total number of detections matching the filter, across all pages. Returned on the first page only (when no `cursor` was supplied).\n", "example": 248 }, "stats": { "type": "object", "description": "Per-day MITRE ATT&CK technique histogram over the full filtered\nresult set. Keys are UTC calendar dates (`YYYY-MM-DD`); each value\nmaps a technique ID to the number of distinct detections in which\nthat technique appeared on that day. Returned on the first page\nonly.\n", "additionalProperties": { "type": "object", "additionalProperties": { "type": "integer", "format": "int64" } }, "example": { "2026-07-29": { "T1082": 14, "T1059.004": 9 } } }, "tactic_stats": { "type": "object", "description": "Per-day MITRE ATT&CK tactic histogram, in the same shape as\n`stats`. A detection carrying several techniques that map to the\nsame tactic is counted once. Returned on the first page only.\n", "additionalProperties": { "type": "object", "additionalProperties": { "type": "integer", "format": "int64" } }, "example": { "2026-07-29": { "TA0007": 21, "TA0002": 11 } } } } }, "TacticsDetectionSummary": { "type": "object", "description": "An aggregated attacker session observed on one of your deployed sensors, as returned by the detection search endpoint.\n", "properties": { "session_id": { "type": "string", "format": "uuid", "description": "Detection identifier. Pass this value as `detection_id` when fetching the detection, its destination IPs, or its files.\n", "example": "0191d8c4-994c-8fc2-a073-3fe3ccb4a01f" }, "workspace_id": { "type": "string", "format": "uuid", "description": "Workspace the detection belongs to." }, "sensor_id": { "type": "string", "format": "uuid", "description": "Sensor that observed the session." }, "profile_id": { "type": "string", "format": "uuid", "description": "Profile the session ran against." }, "profile_instance_id": { "type": "string", "format": "uuid", "description": "Specific profile instance the session ran against." }, "start_time": { "type": "string", "format": "date-time", "description": "Time of the first event in the session.", "example": "2026-07-29T14:12:03Z" }, "end_time": { "type": "string", "format": "date-time", "description": "Time of the last event in the session.", "example": "2026-07-29T14:31:47Z" }, "initial_process_name": { "type": "string", "description": "Name of the first process observed in the session.", "example": "bash" }, "initial_process_parent": { "type": "string", "description": "Parent of the first process observed in the session.", "example": "sshd" }, "rules": { "type": "array", "description": "Distinct sensor rules the session triggered.", "items": { "type": "string" }, "example": [ "command_run", "internet_access" ] }, "techniques": { "type": "array", "description": "Distinct MITRE ATT&CK technique IDs observed in the session.", "items": { "type": "string" }, "example": [ "T1082", "T1059.004" ] }, "tactics": { "type": "array", "description": "Distinct MITRE ATT&CK tactic IDs observed in the session, derived from its techniques.\n", "items": { "type": "string" }, "example": [ "TA0007", "TA0002" ] }, "commands": { "type": "array", "description": "Commands run during the session.\n\nOn the search endpoint this is a bounded preview: at most 40 of the\nsession's **distinct** commands, in no particular order and not\nnecessarily the earliest ones. Fetch the detection by ID for the\ncomplete sequence in chronological order, including repeats.\n", "items": { "type": "string" }, "example": [ "uname -a", "cat /etc/passwd" ] }, "executable_paths": { "type": "array", "description": "Distinct paths of executables run during the session.\n\nOn the search endpoint this is a bounded preview: at most 40 paths,\nan arbitrary subset with no total. Fetch the detection by ID for\nthe complete set.\n", "items": { "type": "string" }, "example": [ "/usr/bin/curl" ] }, "artifacts": { "type": "array", "description": "Files the session created or modified.\n\nOn the search endpoint this is a bounded preview: at most 40 files,\nan arbitrary subset with no total. On the get-detection endpoint the\nset is complete and paged by `artifacts_page` rather than truncated,\nso every path is reachable.\n", "items": { "$ref": "#/components/schemas/TacticsDetectionArtifact" } }, "interactive": { "type": "boolean", "description": "Whether the session had a shell ancestor - a hands-on-keyboard session rather than automated activity.\n", "example": true } } }, "TacticsDetectionArtifact": { "type": "object", "description": "A file the detection's session created or modified.", "properties": { "path": { "type": "string", "description": "Absolute path of the file on the profile instance.", "example": "/tmp/.x/miner" }, "sha256": { "type": "string", "description": "Reserved. Not currently populated on this surface - use the detection files endpoint for a file's hashes, size, and type.\n", "example": "" } } } } } } ```