Anomaly Events¶

Reference for the anomaly_events endpoints of the Surfmeter API.

Surfmeter API – Anomaly Events v1¶

The Surfmeter API lets you manage clients, users, capabilities, measurements, and organization-wide settings programmatically.

Servers¶

Description	URL
https://surfmeter-server.{host}/client_admin_api/v1	https://surfmeter-server.{host}/client_admin_api/v1

Anomaly Events¶

POST /anomaly_events/search¶

Input parameters

Parameter	In	Type	Default	Nullable	Description
`ApiKeyAuth`	header	string	N/A	No	API key used on every request. Create keys in the Surfmeter Dashboard under Keys → Surfmeter API Keys.

Request body

application/json

{
    "body": null,
    "source_only": true,
    "size": 0,
    "from": 0,
    "search_after": [
        null
    ]
}

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the request body

{
    "description": "Request data for the anomaly events search action. Wraps an Elasticsearch search request against the current data owner's `anomaly_events-*` indices. The `body` property is passed through to Elasticsearch as a Query DSL payload; additional top-level properties (`size`, `from`, `search_after`) control pagination and are forwarded to the Elasticsearch client alongside the body.",
    "type": "object",
    "additionalProperties": false,
    "required": [
        "body"
    ],
    "properties": {
        "body": {
            "additionalProperties": true,
            "description": "Elasticsearch Query DSL payload. Treated as a passthrough: any valid Elasticsearch search request body (`query`, `aggs`, `sort`, `size`, `from`, `search_after`, `_source`, etc.) is accepted. May also be provided as a JSON-formatted string, in which case it is parsed server-side.",
            "oneOf": [
                {
                    "type": "object"
                },
                {
                    "type": "string"
                }
            ]
        },
        "source_only": {
            "type": "boolean",
            "description": "If true, the response is reduced to a plain array of `_source` documents instead of the full Elasticsearch response envelope."
        },
        "size": {
            "type": "integer",
            "description": "Maximum number of hits to return. Forwarded to the Elasticsearch client as a top-level parameter; equivalent to setting `size` inside `body`."
        },
        "from": {
            "type": "integer",
            "description": "Offset of the first hit to return, used for basic pagination. Forwarded to the Elasticsearch client as a top-level parameter."
        },
        "search_after": {
            "type": "array",
            "description": "Opaque cursor for deep pagination. Pass the `sort` array from the last hit of the previous page; requires a stable `sort` clause in `body`.",
            "items": {}
        }
    }
}

Response 200 OK

application/json

Schema of the response body

{
    "description": "Response for the anomaly events search action. Shape depends on the request: when `source_only=true` the response is an array of anomaly event source documents; otherwise it is the raw Elasticsearch search response envelope (hits, aggregations, etc.). The shape of individual event source documents is hand-maintained in `@surfmeter/elasticsearch-attributes/src/types/AnomalyEvent.ts`.",
    "oneOf": [
        {
            "description": "Returned when `source_only=true`: a plain array of anomaly event `_source` documents, without Elasticsearch metadata.",
            "type": "array",
            "items": {
                "type": "object",
                "additionalProperties": true
            }
        },
        {
            "description": "Default response: the Elasticsearch search response envelope. Only the outermost keys are described here; everything inside is passed through unchanged.",
            "type": "object",
            "additionalProperties": true,
            "properties": {
                "took": {
                    "type": "integer",
                    "description": "Time in milliseconds Elasticsearch spent executing the search."
                },
                "timed_out": {
                    "type": "boolean",
                    "description": "Whether the search timed out before completing."
                },
                "_shards": {
                    "type": "object",
                    "additionalProperties": true,
                    "description": "Per-shard execution summary reported by Elasticsearch."
                },
                "hits": {
                    "type": "object",
                    "additionalProperties": true,
                    "description": "Container for matching anomaly event documents. Includes `total`, `max_score`, and `hits` (an array of hit objects with `_index`, `_id`, `_source`, `sort`, etc.)."
                },
                "aggregations": {
                    "type": "object",
                    "additionalProperties": true,
                    "description": "Aggregation results, present only when the request `body` contained an `aggs` clause."
                }
            }
        }
    ]
}

PATCH /anomaly_events/resolve¶

Input parameters

Parameter	In	Type	Default	Nullable	Description
`ApiKeyAuth`	header	string	N/A	No	API key used on every request. Create keys in the Surfmeter Dashboard under Keys → Surfmeter API Keys.

Request body

application/json

{
    "anomaly_ids": [
        "string"
    ]
}

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the request body

{
    "description": "Request data for the anomaly events bulk-resolve action. Closes one or more active anomaly episodes as if the analyzer's automatic resolution sweep had run on them. Idempotent: already-resolved or unknown ids silently no-op.",
    "type": "object",
    "additionalProperties": false,
    "required": [
        "anomaly_ids"
    ],
    "properties": {
        "anomaly_ids": {
            "type": "array",
            "description": "Episode document ids to resolve. Each id is the deterministic Elasticsearch `_id`: `{rule_id}::{detection_pass}::{first_seen_epoch}`. Server enforces a per-request cap (currently 500) to keep a single `update_by_query` bounded; batch above that on the client.",
            "minItems": 1,
            "maxItems": 500,
            "items": {
                "type": "string",
                "minLength": 1
            }
        }
    }
}

Response 200 OK

application/json

{
    "updated": 0,
    "requested": 0
}

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "description": "Response for the anomaly events bulk-resolve action. A 200 with `updated < requested` is success — the missing ids were either already-resolved episodes, ids from another data owner, or ids that simply do not exist.",
    "type": "object",
    "additionalProperties": false,
    "required": [
        "updated",
        "requested"
    ],
    "properties": {
        "updated": {
            "type": "integer",
            "minimum": 0,
            "description": "Number of episode documents flipped from `new` to `resolved` by this call."
        },
        "requested": {
            "type": "integer",
            "minimum": 0,
            "description": "Number of `anomaly_ids` submitted in the request. Compare against `updated` to surface partial-success messaging."
        }
    }
}

GET /anomaly_events/{anomaly_id}¶

Input parameters

Parameter	In	Type	Default	Nullable	Description
`ApiKeyAuth`	header	string	N/A	No	API key used on every request. Create keys in the Surfmeter Dashboard under Keys → Surfmeter API Keys.
`anomaly_id`	path	string		No

Response 200 OK

application/json

{
    "anomaly_event": {}
}

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "description": "Response for the anomaly events show action. Wraps the matched event's Elasticsearch `_source` under an `anomaly_event` key. The shape of the source document itself is hand-maintained in `@surfmeter/elasticsearch-attributes/src/types/AnomalyEvent.ts`.",
    "type": "object",
    "additionalProperties": false,
    "required": [
        "anomaly_event"
    ],
    "properties": {
        "anomaly_event": {
            "type": "object",
            "additionalProperties": true,
            "description": "The matched anomaly event source document. Concrete field shape is owned by `AnomalyEvent.ts` in `@surfmeter/elasticsearch-attributes`; this schema only enforces that the response wraps a single event object."
        }
    }
}

Schemas¶

AnomalyEventResolveData¶

Name	Type
`anomaly_ids`	Array<string>

AnomalyEventResolveResponse¶

Name	Type
`requested`	integer
`updated`	integer

AnomalyEventSearchData¶

Name	Type
`body`
`from`	integer
`search_after`	Array<>
`size`	integer
`source_only`	boolean

AnomalyEventSearchResponse¶

Type:

AnomalyEventShowResponse¶

Name	Type
`anomaly_event`

Security schemes¶

Name	Type	Scheme	Description
ApiKeyAuth	apiKey		API key used on every request. Create keys in the Surfmeter Dashboard under Keys → Surfmeter API Keys.