Unleash Metrics API

openapi: 3.2.0
info:
  title: Unleash Admin Addons Metrics API
  version: 7.4.1
  description: Create, update, and delete [Unleash addons](https://docs.getunleash.io/addons).
servers:
- url: https://app.unleash-instance.example.com
  description: Your Unleash instance (replace with your actual URL)
security:
- apiKey: []
- bearerToken: []
tags:
- name: Metrics
  description: Register, read, or delete metrics recorded by Unleash.
paths:
  /api/admin/metrics/rps:
    get:
      tags:
      - Metrics
      operationId: getRequestsPerSecond
      summary: Gets Usage Data
      description: '**Enterprise feature**


        Gets usage data per app/endpoint from a prometheus compatible metrics endpoint'
      responses:
        '200':
          description: requestsPerSecondSegmentedSchema
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/requestsPerSecondSegmentedSchema'
  /api/admin/metrics/traffic:
    get:
      tags:
      - Metrics
      operationId: getTrafficDataUsageForPeriod
      summary: Get Aggregated Traffic Data for a Given Time Period.
      description: '**Enterprise feature**


        Gets traffic usage data for the selected period, either aggregated by day or by month.'
      parameters:
      - name: grouping
        in: query
        required: true
        schema:
          type: string
          enum:
          - daily
          - monthly
          example: daily
        description: Whether to aggregate the data by month or by day
      - name: from
        schema:
          type: string
          format: date
          example: '2024-01-01'
        description: The starting date of the traffic data usage search in IS:yyyy-MM-dd format
        in: query
        required: true
      - name: to
        schema:
          type: string
          example: '2024-01-31'
          format: date
        description: The starting date of the traffic data usage search in IS:yyyy-MM-dd format
        in: query
        required: true
      responses:
        '200':
          description: trafficUsageDataSegmentedCombinedSchema
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/trafficUsageDataSegmentedCombinedSchema'
  /api/admin/metrics/applications/{appName}:
    post:
      tags:
      - Metrics
      operationId: createApplication
      summary: Create an Application to Connect Reported Metrics
      description: Is used to report usage as well which sdk the application uses
      responses:
        '202':
          description: This response has no body.
        '400':
          description: The request data does not match what we expect.
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    example: 9c40958a-daac-400e-98fb-3bb438567008
                    description: The ID of the error instance
                  name:
                    type: string
                    example: ValidationError
                    description: The name of the error kind
                  message:
                    type: string
                    example: The request payload you provided doesn't conform to the schema. The .parameters property should be object. You sent [].
                    description: A description of what went wrong.
        '401':
          description: Authorization information is missing or invalid. Provide a valid API token as the `authorization` header, e.g. `authorization:*.*.my-admin-token`.
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    example: 9c40958a-daac-400e-98fb-3bb438567008
                    description: The ID of the error instance
                  name:
                    type: string
                    example: AuthenticationRequired
                    description: The name of the error kind
                  message:
                    type: string
                    example: You must log in to use Unleash. Your request had no authorization header, so we could not authorize you. Try logging in at /auth/simple/login.
                    description: A description of what went wrong.
        '403':
          description: The provided user credentials are valid, but the user does not have the necessary permissions to perform this operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    example: 9c40958a-daac-400e-98fb-3bb438567008
                    description: The ID of the error instance
                  name:
                    type: string
                    example: NoAccessError
                    description: The name of the error kind
                  message:
                    type: string
                    example: You need the "UPDATE_ADDON" permission to perform this action in the "development" environment.
                    description: A description of what went wrong.
      requestBody:
        description: createApplicationSchema
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/createApplicationSchema'
      parameters:
      - name: appName
        in: path
        required: true
        schema:
          type: string
    delete:
      tags:
      - Metrics
      operationId: deleteApplication
      summary: Delete an Application
      description: Delete the application specified in the request URL. Returns 200 OK if the application was successfully deleted or if it didn't exist
      responses:
        '200':
          description: This response has no body.
        '401':
          description: Authorization information is missing or invalid. Provide a valid API token as the `authorization` header, e.g. `authorization:*.*.my-admin-token`.
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    example: 9c40958a-daac-400e-98fb-3bb438567008
                    description: The ID of the error instance
                  name:
                    type: string
                    example: AuthenticationRequired
                    description: The name of the error kind
                  message:
                    type: string
                    example: You must log in to use Unleash. Your request had no authorization header, so we could not authorize you. Try logging in at /auth/simple/login.
                    description: A description of what went wrong.
        '403':
          description: The provided user credentials are valid, but the user does not have the necessary permissions to perform this operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    example: 9c40958a-daac-400e-98fb-3bb438567008
                    description: The ID of the error instance
                  name:
                    type: string
                    example: NoAccessError
                    description: The name of the error kind
                  message:
                    type: string
                    example: You need the "UPDATE_ADDON" permission to perform this action in the "development" environment.
                    description: A description of what went wrong.
      parameters:
      - name: appName
        in: path
        required: true
        schema:
          type: string
    get:
      tags:
      - Metrics
      operationId: getApplication
      summary: Get Application Data
      description: Returns data about the specified application (`appName`). The data contains information on the name of the application, sdkVersion (which sdk reported these metrics, typically `unleash-client-node:3.4.1` or `unleash-client-java:7.1.0`), as well as data about how to display this application in a list.
      responses:
        '200':
          description: applicationSchema
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/applicationSchema'
        '404':
          description: The requested resource was not found.
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    example: 9c40958a-daac-400e-98fb-3bb438567008
                    description: The ID of the error instance
                  name:
                    type: string
                    example: NotFoundError
                    description: The name of the error kind
                  message:
                    type: string
                    example: Could not find the addon with ID "12345".
                    description: A description of what went wrong.
      parameters:
      - name: appName
        in: path
        required: true
        schema:
          type: string
  /api/admin/metrics/applications:
    get:
      tags:
      - Metrics
      summary: Get All Applications
      description: Returns all applications registered with Unleash. Applications can be created via metrics reporting or manual creation
      parameters:
      - name: query
        schema:
          type: string
          example: first_app
        description: The search query for the application name
        in: query
      - name: offset
        schema:
          type: string
          example: '50'
        description: The number of applications to skip when returning a page. By default it is set to 0.
        in: query
      - name: limit
        schema:
          type: string
          example: '50'
        description: The number of applications to return in a page. By default it is set to 1000.
        in: query
      - name: sortBy
        schema:
          type: string
          example: type
        description: The field to sort the results by. By default it is set to "appName".
        in: query
      - name: sortOrder
        schema:
          type: string
          example: desc
        description: The sort order for the sortBy. By default it is det to "asc".
        in: query
      operationId: getApplications
      responses:
        '200':
          description: applicationsSchema
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/applicationsSchema'
  /api/admin/metrics/applications/{appName}/overview:
    get:
      tags:
      - Metrics
      operationId: getApplicationOverview
      summary: Get Application Overview
      description: Returns an overview of the specified application (`appName`).
      responses:
        '200':
          description: applicationOverviewSchema
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/applicationOverviewSchema'
        '404':
          description: The requested resource was not found.
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    example: 9c40958a-daac-400e-98fb-3bb438567008
                    description: The ID of the error instance
                  name:
                    type: string
                    example: NotFoundError
                    description: The name of the error kind
                  message:
                    type: string
                    example: Could not find the addon with ID "12345".
                    description: A description of what went wrong.
      parameters:
      - name: appName
        in: path
        required: true
        schema:
          type: string
  /api/admin/metrics/instances/{appName}/environment/{environment}:
    get:
      tags:
      - Metrics
      operationId: getApplicationEnvironmentInstances
      summary: Get Application Environment Instances (last 24h)
      description: Returns an overview of the instances for the given `appName` and `environment` that have received traffic in the last 24 hours.
      responses:
        '200':
          description: applicationEnvironmentInstancesSchema
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/applicationEnvironmentInstancesSchema'
        '404':
          description: The requested resource was not found.
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    example: 9c40958a-daac-400e-98fb-3bb438567008
                    description: The ID of the error instance
                  name:
                    type: string
                    example: NotFoundError
                    description: The name of the error kind
                  message:
                    type: string
                    example: Could not find the addon with ID "12345".
                    description: A description of what went wrong.
      parameters:
      - name: appName
        in: path
        required: true
        schema:
          type: string
      - name: environment
        in: path
        required: true
        schema:
          type: string
  /api/admin/metrics/sdks/outdated:
    get:
      tags:
      - Metrics
      operationId: getOutdatedSdks
      summary: Get Outdated Sdks
      description: Returns a list of the outdated SDKS with the applications using them.
      responses:
        '200':
          description: outdatedSdksSchema
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/outdatedSdksSchema'
        '404':
          description: The requested resource was not found.
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    example: 9c40958a-daac-400e-98fb-3bb438567008
                    description: The ID of the error instance
                  name:
                    type: string
                    example: NotFoundError
                    description: The name of the error kind
                  message:
                    type: string
                    example: Could not find the addon with ID "12345".
                    description: A description of what went wrong.
  /api/admin/client-metrics/features/{name}/raw:
    get:
      operationId: getRawFeatureMetrics
      tags:
      - Metrics
      summary: Get Feature Metrics
      description: Get usage metrics for a specific feature for the last 48 hours, grouped by hour
      responses:
        '200':
          description: featureMetricsSchema
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/featureMetricsSchema'
        '401':
          description: Authorization information is missing or invalid. Provide a valid API token as the `authorization` header, e.g. `authorization:*.*.my-admin-token`.
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    example: 9c40958a-daac-400e-98fb-3bb438567008
                    description: The ID of the error instance
                  name:
                    type: string
                    example: AuthenticationRequired
                    description: The name of the error kind
                  message:
                    type: string
                    example: You must log in to use Unleash. Your request had no authorization header, so we could not authorize you. Try logging in at /auth/simple/login.
                    description: A description of what went wrong.
        '403':
          description: The provided user credentials are valid, but the user does not have the necessary permissions to perform this operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    example: 9c40958a-daac-400e-98fb-3bb438567008
                    description: The ID of the error instance
                  name:
                    type: string
                    example: NoAccessError
                    description: The name of the error kind
                  message:
                    type: string
                    example: You need the "UPDATE_ADDON" permission to perform this action in the "development" environment.
                    description: A description of what went wrong.
        '404':
          description: The requested resource was not found.
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    example: 9c40958a-daac-400e-98fb-3bb438567008
                    description: The ID of the error instance
                  name:
                    type: string
                    example: NotFoundError
                    description: The name of the error kind
                  message:
                    type: string
                    example: Could not find the addon with ID "12345".
                    description: A description of what went wrong.
      parameters:
      - name: name
        in: path
        required: true
        schema:
          type: string
  /api/admin/client-metrics/features/{name}:
    get:
      operationId: getFeatureUsageSummary
      tags:
      - Metrics
      summary: Last Hour of Usage and a List of Applications That Have Reported Seeing This Feature Flag
      description: Separate counts for yes (enabled), no (disabled), as well as how many times each variant was selected during the last hour
      responses:
        '200':
          description: featureUsageSchema
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/featureUsageSchema'
        '401':
          description: Authorization information is missing or invalid. Provide a valid API token as the `authorization` header, e.g. `authorization:*.*.my-admin-token`.
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    example: 9c40958a-daac-400e-98fb-3bb438567008
                    description: The ID of the error instance
                  name:
                    type: string
                    example: AuthenticationRequired
                    description: The name of the error kind
                  message:
                    type: string
                    example: You must log in to use Unleash. Your request had no authorization header, so we could not authorize you. Try logging in at /auth/simple/login.
                    description: A description of what went wrong.
        '403':
          description: The provided user credentials are valid, but the user does not have the necessary permissions to perform this operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    example: 9c40958a-daac-400e-98fb-3bb438567008
                    description: The ID of the error instance
                  name:
                    type: string
                    example: NoAccessError
                    description: The name of the error kind
                  message:
                    type: string
                    example: You need the "UPDATE_ADDON" permission to perform this action in the "development" environment.
                    description: A description of what went wrong.
        '404':
          description: The requested resource was not found.
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    example: 9c40958a-daac-400e-98fb-3bb438567008
                    description: The ID of the error instance
                  name:
                    type: string
                    example: NotFoundError
                    description: The name of the error kind
                  message:
                    type: string
                    example: Could not find the addon with ID "12345".
                    description: A description of what went wrong.
      parameters:
      - name: name
        in: path
        required: true
        schema:
          type: string
  /api/admin/custom-metrics:
    get:
      tags:
      - Metrics
      summary: Get Stored Custom Metrics
      description: Retrieves the stored custom metrics data.
      operationId: getCustomMetrics
      responses:
        '200':
          description: This response has no body.
  /api/admin/custom-metrics/prometheus:
    get:
      tags:
      - Metrics
      summary: Get Metrics in Prometheus Format
      description: Exposes all custom metrics in Prometheus text format for scraping.
      operationId: getPrometheusMetrics
      responses:
        '200':
          description: Prometheus formatted metrics
          content:
            text/plain:
              schema:
                type: string
components:
  schemas:
    requestsPerSecondSchema:
      type: object
      description: Statistics for usage of Unleash, formatted so it can easily be used in a graph
      properties:
        status:
          type: string
          description: Whether the query against prometheus succeeded or failed
          enum:
          - success
          - failure
          example: success
        data:
          type: object
          description: The query result from prometheus
          properties:
            resultType:
              type: string
              description: Prometheus compatible result type.
              enum:
              - matrix
              - vector
              - scalar
              - string
              example: vector
            result:
              description: An array of values per metric. Each one represents a line in the graph labeled by its metric name
              type: array
              items:
                type: object
                description: A representation of a single metric to build a line in a graph
                properties:
                  metric:
                    description: A key value set representing the metric
                    type: object
                    properties:
                      appName:
                        description: Name of the application this metric relates to
                        type: string
                        example: mySdk
                      endpoint:
                        description: Which endpoint has been accessed
                        type: string
                        example: /api/frontend
                  values:
                    description: 'An array of arrays. Each element of the array is an array of size 2 consisting of the 2 axis for the graph: in position zero the x axis represented as a number and position one the y axis represented as string'
                    type: array
                    items:
                      type: array
                      description: Either the x axis represented as a number or the y axis represented as a string
                      items:
                        anyOf:
                        - type: string
                          description: An identifier for the line in the graph
                        - type: number
                          description: The number of requests at this point in time
    applicationEnvironmentIssuesSchema:
      type: object
      description: This list of issues that might be wrong with the application
      additionalProperties: false
      required:
      - missingFeatures
      - outdatedSdks
      properties:
        missingFeatures:
          type: array
          items:
            type: string
          description: The list of features that are missing in Unleash
          example:
          - feature1
          - feature2
        outdatedSdks:
          type: array
          items:
            type: string
          description: The list of used SDKs that are outdated
          example:
          - unleash-client-node:5.4.0
          - unleash-client-node:5.3.0
    applicationUsageSchema:
      type: object
      description: Data about an project that have been used by applications.
      additionalProperties: false
      required:
      - project
      - environments
      properties:
        project:
          description: Name of the project
          type: string
          example: main-project
        environments:
          description: Which environments have been accessed in this project.
          type: array
          items:
            type: string
          example:
          - development
          - production
    outdatedSdksSchema:
      type: object
      description: Data about outdated SDKs that should be upgraded.
      additionalProperties: false
      required:
      - sdks
      properties:
        sdks:
          type: array
          description: A list of SDKs
          items:
            type: object
            required:
            - sdkVersion
            - applications
            additionalProperties: false
            properties:
              sdkVersion:
                type: string
                description: An outdated SDK version identifier. Usually formatted as "unleash-client-<language>:<version>"
                example: unleash-client-java:7.0.0
              applications:
                type: array
                items:
                  description: Name of the application
                  type: string
                  example: accounting
                description: A list of applications using the SDK version
    applicationOverviewEnvironmentSchema:
      type: object
      description: Data about an application environment
      additionalProperties: false
      required:
      - name
      - instanceCount
      - sdks
      - frontendSdks
      - backendSdks
      - lastSeen
      - issues
      properties:
        name:
          description: Name of the application environment
          type: string
          example: production
        instanceCount:
          description: The number of instances of the application environment
          type: number
          example: 5
        sdks:
          description: SDKs used in the application environment
          type: array
          items:
            type: string
          example:
          - unleash-client-node:5.4.0
          - unleash-client-node:5.3.0
        frontendSdks:
          description: Frontend SDKs used in the application environment
          type: array
          items:
            type: string
          example:
          - unleash-client-js:3.7.5
        backendSdks:
          description: Backend SDKs used in the application environment
          type: array
          items:
            type: string
          example:
          - unleash-client-node:5.4.0
        lastSeen:
          type:
          - string
          - 'null'
          format: date-time
          example: '2023-04-19T08:15:14.000Z'
          description: The last time the application environment was seen
        issues:
          description: This list of issues that might be wrong with the application
          $ref: '#/components/schemas/applicationEnvironmentIssuesSchema'
    featureEnvironmentMetricsSchema:
      type: object
      additionalProperties: false
      required:
      - environment
      - timestamp
      - 'yes'
      - 'no'
      description: How many times `feautreName` was evaluated to `true` (yes) and `false` (no) for `appName` in `environmnet`
      properties:
        featureName:
          description: The name of the feature
          type: string
          example: my.special.feature
        appName:
          description: The name of the application the SDK is being used in
          type: string
          example: accounting
        environment:
          description: Which environment the SDK is being used in
          type: string
          example: development
        timestamp:
          description: The start of the time window these metrics are valid for. The window is usually 1 hour wide
          example: '1926-05-08T12:00:00.000Z'
          $ref: '#/components/schemas/dateSchema'
        'yes':
          description: How many times the toggle evaluated to true
          type: integer
          example: 974
          minimum: 0
        'no':
          description: How many times the toggle evaluated to false
          type: integer
          example: 50
          minimum: 0
        variants:
          description: How many times each variant was returned
          type: object
          additionalProperties:
            type: integer
            minimum: 0
          example:
            variantA: 15
            variantB: 25
            variantC: 5
    featureUsageSchema:
      type: object
      additionalProperties: false
      description: How many applications have seen this feature flag, as well as how this feature was evaluated the last hour
      required:
      - version
      - maturity
      - featureName
      - lastHourUsage
      - seenApplications
      properties:
        version:
          description: The version of this schema
          type: integer
          minimum: 1
        maturity:
          description: The maturity level of this API (alpha, beta, stable, deprecated)
          type: string
          example: stable
        featureName:
          description: The name of the feature
          type: string
          example: my.special.feature
        lastHourUsage:
          description: Last hour statistics. Accumulated per feature per environment. Contains counts for evaluations to true (yes) and to false (no)
          type: array
          items:
            $ref: '#/components/schemas/featureEnvironmentMetricsSchema'
        seenApplications:
          description: A list of applications seen using this feature
          type: array
          items:
            type: string
          example:
          - accounting
          - billing
          - booking
    applicationEnvironmentInstancesSchema:
      type: object
      description: Data about an application environment instances that are connected to Unleash via an SDK.
      additionalProperties: false
      required:
      - instances
      properties:
        instances:
          type: array
          description: A list of instances
          items:
            type: object
            required:
            - instanceId
            additionalProperties: false
            properties:
              instanceId:
                description: 'A unique identifier identifying the instance of the application running the SDK. Often changes based on execution environment. For instance: two pods in Kubernetes will have two different instanceIds'
                type: string
                example: b77f3d13-5f48-4a7b-a3f4-a449b97ce43a
              sdkVersion:
                type:
                - string
                - 'null'
                description: An SDK version identifier. Usually formatted as "unleash-client-<language>:<version>"
                example: unleash-client-java:7.0.0
              clientIp:
                type:
                - string
                - 'null'
                description: An IP address identifying the instance of the application running the SDK
                example: 192.168.0.1
              lastSeen:
                type: string
                format: date-time
             

# --- truncated at 32 KB (42 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/unleash/refs/heads/main/openapi/unleash-metrics-api-openapi.yml