# V2 Web API

## Capabilities

The Capabilities API allows you to directly discover which functions from the V2 API functionality, including the selectable aggregate functions, are supported by the currently configured storage driver. A capabilities query returns a flattened dictionary of properties with associated boolean values - a ‘False’ or absent value means that the corresponding feature is not available in the backend.

GET /v2/capabilities

  Returns a flattened dictionary of API capabilities.

  Capabilities supported by the currently configured storage driver.

  Return type:

    `Capabilities`

class aodh.api.controllers.v2.capabilities.Capabilities(**kw)

  A representation of the API and storage capabilities.

  Usually constrained by restrictions imposed by the storage driver.

  alarm_storage

    A flattened dictionary of alarm storage capabilities

  api

    A flattened dictionary of API capabilities

## Alarms

GET /v2/alarms

  Return all alarms, based on the query provided.

  Parameters:

    - q (list(`Query`)) – Filter rules for the alarms to be returned.

    - sort (list(`str`)) – A list of pairs of sort key and sort dir.

    - limit (`int`) – The maximum number of items to be return.

    - marker (`str`) – The pagination query marker.

  Return type:

    list(`Alarm`)

POST /v2/alarms

  Create a new alarm.

  Parameters:

    - data (`Alarm`) – an alarm within the request body.

  Return type:

    `Alarm`

GET /v2/alarms/(alarm_id)

  Return this alarm.

  Return type:

    `Alarm`

PUT /v2/alarms/(alarm_id)

  Modify this alarm.

  Parameters:

    - data (`Alarm`) – an alarm within the request body.

  Return type:

    `Alarm`

DELETE /v2/alarms/(alarm_id)

  Delete this alarm.

GET /v2/alarms/(alarm_id)/history

  Assembles the alarm history requested.

  Parameters:

    - q (list(`Query`)) – Filter rules for the changes to be described.

    - sort (list(`str`)) – A list of pairs of sort key and sort dir.

    - limit (`int`) – The maximum number of items to be return.

    - marker (`str`) – The pagination query marker.

  Return type:

    list(`AlarmChange`)

PUT /v2/alarms/(alarm_id)/state

  Set the state of this alarm.

  Parameters:

    - state (`Enum(ok, alarm, insufficient data)`) – an alarm state within the request body.

  Return type:

    `Enum(ok, alarm, insufficient data)`

GET /v2/alarms/(alarm_id)/state

  Get the state of this alarm.

  Return type:

    `Enum(ok, alarm, insufficient data)`

class aodh.api.controllers.v2.alarms.Alarm(rule=None, time_constraints=None, **kwargs)

  Representation of an alarm.

  alarm_actions

    The actions to do when alarm state change to alarm

  alarm_id

    The UUID of the alarm

  property description

    The description of the alarm

  enabled

    This alarm is enabled?

  evaluate_timestamp

    The latest alarm evaluation time

  insufficient_data_actions

    The actions to do when alarm state change to insufficient data

  name

    The name for the alarm

  ok_actions

    The actions to do when alarm state change to ok

  project_id

    The ID of the project or tenant that owns the alarm

  repeat_actions

    The actions should be re-triggered on each evaluation cycle

  property severity

    The severity of the alarm

  property state

    The state offset the alarm

  state_reason

    The reason of the current state

  state_timestamp

    The date of the last alarm state changed

  time_constraints

    Describe time constraints for the alarm

  timestamp

    The date of the last alarm definition update

  property type

    Explicit type specifier to select which rule to follow below.

  user_id

    The ID of the user who created the alarm

class aodh.api.controllers.v2.alarm_rules.gnocchi.MetricOfResourceRule(**kw)
  aggregation_method

    The aggregation_method to compare to the threshold

  property comparison_operator
  evaluation_periods

    The number of historical periods to evaluate the threshold

  granularity

    The time range in seconds over which query

  metric

    The name of the metric

  resource_id

    The id of a resource

  resource_type

    The resource type

  threshold

    The threshold of the alarm

class aodh.api.controllers.v2.alarm_rules.gnocchi.AggregationMetricByResourcesLookupRule(**kw)
  aggregation_method

    The aggregation_method to compare to the threshold

  property comparison_operator
  evaluation_periods

    The number of historical periods to evaluate the threshold

  granularity

    The time range in seconds over which query

  metric

    The name of the metric

  query

    The query to filter the metric, Don’t forget to filter out deleted resources (example: {“and”: [{“=”: {“ended_at”: null}}, …]}), Otherwise Gnocchi will try to create the aggregate against obsolete resources

  resource_type

    The resource type

  threshold

    The threshold of the alarm

class aodh.api.controllers.v2.alarm_rules.gnocchi.AggregationMetricsByIdLookupRule(**kw)
  aggregation_method

    The aggregation_method to compare to the threshold

  property comparison_operator
  evaluation_periods

    The number of historical periods to evaluate the threshold

  granularity

    The time range in seconds over which query

  metrics

    A list of metric Ids

  threshold

    The threshold of the alarm

class aodh.api.controllers.v2.alarms.AlarmTimeConstraint(**kw)

  Representation of a time constraint on an alarm.

  property description

    The description of the constraint

  duration

    How long the constraint should last, in seconds

  name

    The name of the constraint

  start

    Start point of the time constraint, in cron format

  timezone

    Timezone of the constraint

class aodh.api.controllers.v2.alarms.AlarmChange(**kw)

  Representation of an event in an alarm’s history.

  alarm_id

    The UUID of the alarm

  detail

    JSON fragment describing change

  event_id

    The UUID of the change event

  on_behalf_of

    The tenant on behalf of which the change is being made

  project_id

    The project ID of the initiating identity

  timestamp

    The time/date of the alarm change

  type

    The type of change

  user_id

    The user ID of the initiating identity

## Filtering Queries

The filter expressions of the query feature operate on the fields of Alarm and AlarmChange. The following comparison operators are supported: =, !=, <, <=, >, >= and in; and the following logical operators can be used: and or and not. The field names are validated against the database models.

Complex Query supports defining the list of orderby expressions in the form of [{“field_name”: “asc”}, {“field_name2”: “desc”}, …].

The number of the returned items can be bounded using the limit option.

The filter, orderby and limit are all optional fields in a query.

POST /v2/query/alarms

  Define query for retrieving Alarm data.

  Parameters:

    - body (`ComplexQuery`) – Query rules for the alarms to be returned.

  Return type:

    list(`Alarm`)

POST /v2/query/alarms/history

  Define query for retrieving AlarmChange data.

  Parameters:

    - body (`ComplexQuery`) – Query rules for the alarm history to be returned.

  Return type:

    list(`AlarmChange`)

class aodh.api.controllers.v2.query.ComplexQuery(**kw)

  Holds a sample query encoded in json.

  filter

    The filter expression encoded in json.

  limit

    The maximum number of results to be returned.

  orderby

    List of single-element dicts for specifing the ordering of the results.

## Composite rule Alarm

The composite type alarm allows users to specify a composite rule to define an alarm with multiple triggering conditions, using a combination of and and or relations. A composite rule is composed of multiple threshold rules or gnocchi rules. A sample composite alarm request form is as follows:

    {
        "name": "test_composite",
        "type": "composite",
        "composite_rule": {
            "and": [THRESHOLD_RULE1, THRESHOLD_RULE2, {
                'or': [THRESHOLD_RULE3, GNOCCHI_RULE1,
                       GNOCCHI_RULE2, GNOCCHI_RULE3]
            }]
        }
    }

A sub-rule in composite_rule is same as a threshold_rule in threshold alarm or a gnocchi_rule in gnocchi alarm. Additionally it has a mandatory type field to specify the rule type, like in the following sample:

    {
        "threshold": 0.8,
        "meters": [
            "f6857d3f-bde6-441a-aa1d-e98fa4ea543f",
            "ea1491ca-5309-4b5a-9f05-34409c6e8b6c"
        ],
        "type": "gnocchi_resources_threshold"
    }

this page last updated: 2026-08-15 16:35:58

Except where otherwise noted, this document is licensed under Creative Commons Attribution 3.0 License. See all OpenStack Legal Documents.

found an error? report a bug