openapi: 3.0.1
info:
title: ilert REST Alert Actions Reports API
description: "# Introduction\nThe ilert API is a [RESTful](https://en.wikipedia.org/wiki/Representational_state_transfer) API and provides programmatic access to entities in ilert and lets you easily integrate ilert with 3rd party tools. If you are looking to develop an inbound integration (e.g. for a monitoring tool), please use our [Events API](#tag/events). \n\nThe API supports the JSON content type for requests and responses. The response content type is requested via the HTTP Accept header (`application/json`). All resources are accessible via https and are located at `api.ilert.com/api`. \n\n You may download ilert's latest [OpenAPI.json {...} here](https://api.ilert.com/api-docs/openapi.json).\n\n If you are looking for a classic Swagger-UI view you may also open [this link](https://api.ilert.com/api-docs/swagger-ui). \n\n ## Authentication\nThe REST API accepts bearer API tokens. Each user may create API keys using the ilert web application. Note: Make sure to send the `Bearer ` prefix e.g. `Bearer APIKEY` when sending api key requests. By default, access to all resources (using any method) requires the client to be authenticated.\n\n ## Team Context\n When using API tokens, the currently selected team context of the user will not be taken into account, i.e. list results will always return all entities to which the user has a view permission. When using basic auth credentials the currently selected team context of the user will be used to filter resource results. The context may be overwritten for API key calls using the `team-context` HTTP header. Specifying `0` for ALL teams, `-1` for MY teams or a specific team id e.g. `team-context=901` to fetch results for a certain team. \n\n ## Errors\nilert uses HTTP response codes to indicate success or failure of an API request. Codes in the 2xx range indicate success, codes in the 4xx range indicate a client error (e.g. a missing required parameter) and codes in the 5xx range indicate an error with ilert's servers. In case of an error, the response body contains the following information:\n\n Attribute | Description \n ------------- | ------------- \n status | the corresponsing HTTP status code \n message | a human readable description of the error \n code | error code, used to identify error type \n\n ## API Versioning\nChanges to our API are always backwards-compatible. To get more information about our API versioning and historical changes, please <a href='https://docs.ilert.com/rest-api/api-version-history' target='_blank'>take a look here</a>."
version: v2.2026.5-r.3
x-logo:
url: ./ilert-logo-spaced.png
backgroundColor: '#fafafa'
altText: ilert documentation logo
servers:
- url: /api
security:
- apiKey: []
tags:
- name: Reports
paths:
/reports/alerts:
get:
tags:
- Reports
summary: List alert metrics for the requested resources
parameters:
- name: sources
in: query
description: alert source ids to filter metrics for
schema:
type: number
- name: policies
in: query
description: escalation policy ids to filter metrics for
schema:
type: number
- name: numbers
in: query
description: phone numbers of call routing numbers to filter metrics for
schema:
type: string
- name: from
in: query
description: date-time ISO-UTC e.g. 2021-05-25T21:24:56.771Z, start of the time range, may not exceed 1 year in total span
required: true
schema:
type: string
- name: until
in: query
description: date-time ISO-UTC e.g. 2021-05-25T21:24:56.771Z, end of the time range, must be after 'from', must not be in the future
required: true
schema:
type: string
- name: timezone
in: query
description: Time zone in which the results will be rendered, defaults to tenant's configured default timezone
schema:
type: string
- name: metric
in: query
description: 'Describes the metric that should be fetched choose one of: COUNT, MTTA or MTTR - defaults to COUNT'
schema:
type: string
- name: group-by
in: query
description: 'Defines the grouping of metrics, choose one of: DAY, WEEK or MONTH - defaults to WEEK'
schema:
type: string
- name: priority
in: query
description: 'Sets the priority filter that should be applied, choose one of: LOW, HIGH or ALL - defaults to ALL'
schema:
type: string
responses:
'200':
description: "an array of alert report metrics, each metric is another array containing data in the following order: \n\n[long:alertSourceId, long:escalationPolicyId, string:callRoutingNumberPhoneNumber, string:ISO-8601, long:value]\n\ne.g. [ [202541, 13541, \"\", \"2021-08\", 15] ]\n\nPlease note: the ISO-8601 (4th column) in this case depends on the chosen 'group-by' parameter. DAY=2021-08-01, WEEK=2021-W12, MONTH=2021-08"
content:
application/json:
schema:
type: array
items:
type: array
items:
oneOf:
- type: number
- type: string
metric sample:
example:
summary: metric sample
value:
- - 202541
- 13541
- ''
- 2021-08
- 15
/reports/alerts/summary:
get:
tags:
- Reports
summary: Summarize a list of alert metrics
parameters:
- name: sources
in: query
description: alert source ids to filter metrics for
schema:
type: number
- name: policies
in: query
description: escalation policy ids to filter metrics for
schema:
type: number
- name: numbers
in: query
description: phone numbers of call routing numbers to filter metrics for
schema:
type: string
- name: from
in: query
description: date-time ISO-UTC e.g. 2021-05-25T21:24:56.771Z, start of the time range, may not exceed 1 year in total span
required: true
schema:
type: string
- name: until
in: query
description: date-time ISO-UTC e.g. 2021-05-25T21:24:56.771Z, end of the time range, must be after 'from', must not be in the future
required: true
schema:
type: string
- name: timezone
in: query
description: Time zone in which the results will be rendered, defaults to tenant's configured default timezone
schema:
type: string
- name: metric
in: query
description: 'Describes the metric that should be fetched choose one of: COUNT, MTTA or MTTR - defaults to COUNT'
schema:
type: string
- name: group-by
in: query
description: 'Defines the grouping of metrics, choose one of: DAY, WEEK or MONTH - defaults to WEEK'
schema:
type: string
- name: priority
in: query
description: 'Sets the priority filter that should be applied, choose one of: LOW, HIGH or ALL - defaults to ALL'
schema:
type: string
responses:
'200':
description: an array containing summarized alert report metrics for the requested resource
content:
application/json:
schema:
type: array
items:
type: object
properties:
alertSourceId:
type: number
escalationPolicyId:
type: number
callRoutingNumberPhoneNumber:
type: string
count:
type: number
mtta:
type: number
mttr:
type: number
/reports/api-keys/usage:
get:
tags:
- Reports
summary: List API key usage metrics for the requested resources
description: This endpoint requires 'ADMIN' permissions
parameters:
- name: scopes
in: query
description: scopes of our API resources e.g. alert see https://docs.ilert.com/rest-api/developing-ilert-apps/token-lifetimes-error-codes-app-verification-etc.#ilert-oauth2-scopes
schema:
type: string
- name: from
in: query
description: date-time ISO-UTC e.g. 2021-05-25T21:24:56.771Z, start of the time range, may not exceed 1 month (31 days) in total span (use this to paginate)
required: true
schema:
type: string
- name: until
in: query
description: date-time ISO-UTC e.g. 2021-05-25T21:24:56.771Z, end of the time range, must be after 'from', must not be in the future (use this to paginate)
required: true
schema:
type: string
- name: timezone
in: query
description: Time zone in which the results will be rendered, defaults to tenant's configured default timezone
schema:
type: string
responses:
'200':
description: "an array of usage metrics, each metric is another array containing data in the following order: \n\n[long:userId, string:scope, string:ISO-8601, long:value]\n\ne.g. [ [202541, \"source\", \"2023-04-21\", 15] ]\n\nPlease note: the ISO-8601 (3th column) in this case is always DAY (2021-08-01) usually 24 hours apart, but there is a slight chance that the same userId and scope have multiple entries for the same DAY"
content:
application/json:
schema:
type: array
items:
type: array
items:
oneOf:
- type: number
- type: string
metric sample:
example:
summary: metric sample
value:
- - 202541
- alert
- 2023-04
- 15
components:
securitySchemes:
apiKey:
type: apiKey
description: The Bearer API key of your user <a href='/api-docs/#section/Authentication'>more info</a>.
name: Authorization
in: header
x-original-swagger-version: '2.0'