Unleash Metrics API
Register, read, or delete metrics recorded by Unleash.
OpenAPI Specification
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