Unleash Metrics API

openapi: 3.0.3
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:
    trafficUsageDataSegmentedCombinedSchema:
      type: object
      description: Contains the recorded data usage for each API path, segmented by day/month and type of traffic
      required:
      - dateRange
      - apiData
      - grouping
      additionalProperties: false
      properties:
        grouping:
          type: string
          enum:
          - monthly
          - daily
          description: Whether the data is aggregated by month or by day.
          example: monthly
        dateRange:
          type: object
          required:
          - from
          - to
          additionalProperties: false
          description: The date range there is data for. The range is inclusive and goes from the start of the `from` date to the end of the `to` date
          properties:
            from:
              type: string
              format: date
              example: '2023-04-01'
              description: The start of the dateRange
            to:
              type: string
              format: date
              example: '2023-04-30'
              description: The end of the dateRange
        apiData:
          type: array
          description: Contains the recorded daily/monthly data usage for each API path
          items:
            type: object
            required:
            - apiPath
            - dataPoints
            additionalProperties: false
            properties:
              apiPath:
                type: string
                example: /api/client
                description: The API path
              dataPoints:
                type: array
                description: The recorded data points for the API path
                items:
                  type: object
                  required:
                  - period
                  - trafficTypes
                  additionalProperties: false
                  properties:
                    period:
                      type: string
                      pattern: ^\d{4}-\d{2}(-\d{2})?$
                      example: '2023-04-01'
                      description: The date of the data point. Formatted as a full date (e.g. 2023-04-01) if the data is aggregated by day or as a month (e.g. 2023-04) if the data is aggregated by month.
                    trafficTypes:
                      type: array
                      items:
                        type: object
                        required:
                        - group
                        - count
                        additionalProperties: false
                        properties:
                          group:
                            type: string
                            example: successful-requests
                            description: The type of traffic
                          count:
                            type: integer
                            minimum: 0
                            example: 42
                            description: The number of requests
                      description: The recorded traffic types for the data point
    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
          nullable: true
          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'
    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
    featureMetricsSchema:
      type: object
      additionalProperties: false
      required:
      - version
      - maturity
      - data
      description: A batch of feature metrics
      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
        data:
          description: Metrics gathered per environment
          type: array
          items:
            $ref: '#/components/schemas/featureEnvironmentMetricsSchema'
    applicationsSchema:
      additionalProperties: false
      description: An object containing a list of applications that have connected to Unleash via an SDK.
      required:
      - total
      - applications
      type: object
      properties:
        total:
          type: integer
          example: 50
          description: The total number of project applications.
        applications:
          description: The list of applications that have connected to this Unleash instance.
          type: array
          items:
            $ref: '#/components/schemas/applicationSchema'
    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
                nullable: true
                description: An SDK version identifier. Usually formatted as "unleash-client-<language>:<version>"
                example: unleash-client-java:7.0.0
              clientIp:
                type: string
                description: An IP address identifying the instance of the application running the SDK
                example: 192.168.0.1
                nullable: true
              lastSeen:
                type: string
                format: date-time
                example: '2023-04-19T08:15:14.000Z'
                description: The last time the application environment instance was seen
    createApplicationSchema:
      type: object
      description: Reported application information from Unleash SDKs
      properties:
        strategies:
          description: Which [strategies](https://docs.getunleash.io/concepts#activation-strategies) the application has loaded. Useful when trying to figure out if your [custom strategy](https://docs.getunleash.io/concepts/activation-strategies#custom-strategies) has been loaded in the SDK
          type: array
          items:
            type: string
          example:
          - standard
          - gradualRollout
          - mySpecialCustomStrategy
        url:
          description: A link to reference the application reporting the metrics. Could for instance be a GitHub link to the repository of the application
          type: string
          example: https://github.com/Unleash/unleash-proxy-client-js
        color:
          description: Css color to be used to color the application's entry in the application list
          type: string
          example: red
        icon:
          description: An URL to an icon file to be used for the applications's entry in the application list
          type: string
          example: https://github.com/favicon.ico
    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
   

# --- 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