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'