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-:" 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 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 applicationSchema: type: object description: Data about an application that's connected to Unleash via an SDK. additionalProperties: false required: - appName properties: appName: description: Name of the application type: string example: accounting sdkVersion: description: Which SDK and version the application reporting uses. Typically represented as `:` type: string example: unleash-client-java:8.0.0 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 description: description: Extra information added about the application reporting the metrics. Only present if added via the Unleash Admin interface type: string example: Application for reporting page visits 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: The CSS color that is 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 usage: description: The list of projects the application has been using. type: array items: $ref: '#/components/schemas/applicationUsageSchema' 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-:" 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 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 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 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 applicationOverviewIssuesSchema: type: object description: This list of issues that might be wrong with the application additionalProperties: false required: - missingStrategies properties: missingStrategies: type: array items: type: string description: The list of strategies that are missing from Unleash example: - feature1 - feature2 applicationOverviewSchema: type: object description: Data about an application that's connected to Unleash via an SDK. additionalProperties: false required: - projects - featureCount - environments - issues properties: projects: description: The list of projects the application has been using. type: array items: type: string example: - default - payment featureCount: description: The number of features the application has been using. type: number example: 5 environments: type: array description: The list of environments the application has been using. items: $ref: '#/components/schemas/applicationOverviewEnvironmentSchema' issues: description: This list of issues that might be wrong with the application $ref: '#/components/schemas/applicationOverviewIssuesSchema' requestsPerSecondSegmentedSchema: type: object description: Get usage metrics separated by client and admin paths properties: clientMetrics: $ref: '#/components/schemas/requestsPerSecondSchema' adminMetrics: $ref: '#/components/schemas/requestsPerSecondSchema' dateSchema: description: A representation of a date. Either as a date-time string or as a UNIX timestamp. oneOf: - type: string format: date-time description: An [RFC-3339](https://www.rfc-editor.org/rfc/rfc3339.html)-compliant timestamp. example: '2023-07-27T11:23:44Z' - type: integer description: A [UNIX timestamp](https://en.wikipedia.org/wiki/Unix_time). example: 1690449593 securitySchemes: apiKey: type: apiKey in: header name: Authorization description: API key needed to access this API bearerToken: type: http scheme: bearer description: API key needed to access this API, in Bearer token format