Get aggregate usage by service, environment, or environment type between two points in time for the current organization.
This API is available to customers subscribed to a drawdown billing plan and reports usage for a single account (organization). If you have multiple accounts, you must run the API separately in each account.
The time query results include the timestamp specified in '**startTime**' to the time before the specified '**endTime**'. For example, if you specify the '**startTime**' of ```2023-01-01T00:00:00Z``` and the '**endTime**' of ```2023-02-01T00:00:00Z```, the results include all of January 2023 and exclude any results from February. Your token must have one of the permissions listed in the Token Permissions.billing_usage_summary:get ]
# OpenAPI definition
````json
{
"openapi": "3.1.0",
"info": {
"title": "Billing",
"version": "2.3.1"
},
"servers": [
{
"url": "https://api.solace.cloud",
"description": "Solace PubSub+ Cloud US EAST Region"
},
{
"url": "https://api.solacecloud.com.au",
"description": "Solace PubSub+ Cloud AU Region"
},
{
"url": "https://api.solacecloud.eu",
"description": "Solace PubSub+ Cloud EU Region"
},
{
"url": "https://api.solacecloud.sg",
"description": "Solace PubSub+ Cloud SG Region"
}
],
"security": [
{
"bearerAuth": []
}
],
"tags": [
{
"name": "Usage"
}
],
"paths": {
"/api/v2/billing/usages/usageAggregates": {
"get": {
"tags": [
"Usage"
],
"summary": "Get usage aggregates for your organization",
"description": "Get aggregate usage by service, environment, or environment type between two points in time for the current organization.
This API is available to customers subscribed to a drawdown billing plan and reports usage for a single account (organization). If you have multiple accounts, you must run the API separately in each account.
\n\nThe time query results include the timestamp specified in '**startTime**' to the time before the specified '**endTime**'. For example, if you specify the '**startTime**' of ```2023-01-01T00:00:00Z``` and the '**endTime**' of ```2023-02-01T00:00:00Z```, the results include all of January 2023 and exclude any results from February.\n\nYour token must have one of the permissions listed in the Token Permissions.\nbilling_usage_summary:get ]",
"operationId": "getUsageAggregates",
"parameters": [
{
"name": "pageSize",
"in": "query",
"description": "The number of usage aggregates to return on each page.",
"schema": {
"type": "integer",
"default": 100,
"maximum": 1000,
"minimum": 1
}
},
{
"name": "pageNumber",
"in": "query",
"description": "The page number to retrieve.",
"schema": {
"type": "integer",
"default": 1,
"minimum": 1
}
},
{
"name": "aggregateBy",
"in": "query",
"description": "Which attribute to aggregate usage by. One of `service`, `environment`, `environmentType`.",
"required": true,
"schema": {
"type": "string",
"default": "",
"enum": [
"service",
"environment",
"environmentType"
]
}
},
{
"name": "aggregateById",
"in": "query",
"description": "The ID of the resource of `aggregateBy` type (ex. `aggregateBy=service&aggregateById=abc` gets the usage for the broker service `abc`).",
"required": false,
"schema": {
"type": "string",
"default": ""
}
},
{
"name": "startTime",
"in": "query",
"description": "The timestamp of the start time of the query, in ISO 8601 date/time format.",
"required": true,
"schema": {
"type": "string",
"format": "date-time",
"default": "",
"example": "2023-01-01T00:00:00Z"
}
},
{
"name": "endTime",
"in": "query",
"description": "The timestamp of the end time of the query, in ISO 8601 date/time format.",
"required": true,
"schema": {
"type": "string",
"format": "date-time",
"default": "",
"example": "2023-02-01T00:00:00Z"
}
}
],
"responses": {
"200": {
"description": "OK.",
"content": {
"*/*": {
"schema": {
"$ref": "#/components/schemas/UsageAggregationEnvelope",
"additionalProperties": {
"default": ""
},
"default": ""
}
}
}
},
"400": {
"description": "Bad request.",
"content": {
"*/*": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse",
"additionalProperties": {
"default": ""
},
"default": ""
}
}
}
},
"401": {
"description": "Unauthorized.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse",
"additionalProperties": {
"default": ""
},
"default": ""
},
"example": {
"message": "An authentication error occurred.",
"errorId": "618e2fb0-a198-4d9d-9219-13e51ef0ecec"
}
}
}
},
"403": {
"description": "Forbidden.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse",
"additionalProperties": {
"default": ""
},
"default": ""
},
"example": {
"message": "You do not have permissions to perform this operation.",
"errorId": "618e2fb0-a198-4d9d-9219-13e51ef0ecec"
}
}
}
},
"404": {
"description": "Not Found.",
"content": {
"*/*": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse",
"additionalProperties": {
"default": ""
},
"default": ""
}
}
}
},
"502": {
"description": "Bad Gateway - Marketplace integration error.",
"content": {
"*/*": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
}
},
"components": {
"schemas": {
"ErrorResponse": {
"type": "object",
"default": null,
"properties": {
"message": {
"type": "string",
"default": "",
"description": "A user-friendly message that describes the error.",
"example": "An error occurred."
},
"errorId": {
"type": "string",
"default": "",
"description": "The UUID (Universally Unique Identifier) that is logged with an appropriate stack trace for a WARN or ERROR log that allows support to better determine what cause the error.",
"example": "123e4567-e89b-12d3-a456-426655440000"
},
"meta": {
"type": "object",
"additionalProperties": {},
"default": "",
"description": "The metadata about the error. This provides additional information about the error that occurred.",
"example": "'object': { 'field': 'description' }"
},
"validationDetails": {
"type": "object",
"additionalProperties": {
"type": "array",
"items": {
"type": "string"
}
},
"default": "",
"description": "When applicable, these are the details of issues with the fields provided for the REST call.",
"example": "'name': ['Not unique']"
}
}
},
"NewProduct": {
"type": "object",
"default": null,
"properties": {
"type": {
"type": "string",
"default": "",
"description": "The type of object for informational purposes.",
"readOnly": true
},
"productCode": {
"type": "string",
"default": "",
"description": "The SKU for this product."
},
"displayName": {
"type": "string",
"default": "",
"description": "The display name for this product."
},
"environmentType": {
"type": "string",
"default": "",
"description": "The type of environment the usage was recorded in (`production`, `nonProduction`, or `account`)"
},
"totalHours": {
"type": "string",
"format": "float",
"default": "",
"description": "The total number of hours the product has been running, to 6 decimal places",
"example": 12.218889
},
"pcusPerYear": {
"type": "integer",
"format": "int32",
"default": "",
"description": "The number of PubSub+ capacity units (PCUs) consumed by this product in one year."
},
"totalPcus": {
"type": "number",
"format": "double",
"default": "",
"description": "The amount of PCUs that have been used for this product."
}
},
"required": [
"displayName",
"environmentType",
"pcusPerYear",
"productCode",
"totalHours",
"totalPcus"
]
},
"UsageAggregationContainer": {
"type": "object",
"default": null,
"properties": {
"id": {
"type": "string",
"default": "",
"description": "ID of the aggregation type."
},
"type": {
"type": "string",
"default": "",
"description": "The type of aggregation (as passed in by aggregateBy)."
},
"attributes": {
"type": "object",
"additionalProperties": {
"type": "string"
},
"default": "",
"description": "Attributes for the given resource. Varies based on type (ex. name for service)."
},
"usages": {
"type": "array",
"default": "",
"description": "The products of the organization.",
"items": {
"$ref": "#/components/schemas/NewProduct"
}
}
},
"required": [
"id",
"type"
]
},
"UsageAggregationEnvelope": {
"type": "object",
"default": null,
"description": "Envelope for usage aggregation response data",
"example": "{\n \"data\": [\n {\n \"id\": \"account\",\n \"type\": \"environmentType\",\n \"attributes\": {},\n \"usages\": [\n {\n \"productCode\": \"CM-CUSTOMER-PRIVATE-REGION-S\",\n \"displayName\": \"Customer Controlled Region\",\n \"environmentType\": \"account\",\n \"totalHours\": 1488.0,\n \"pcusPerYear\": 150,\n \"totalPcus\": 25.479453\n }\n {\n \"productCode\": \"CM-MESSAGE-SPOOL-EXPANSION-S\",\n \"displayName\": \"PS+ Message Spool Expansion 1K Units\",\n \"environmentType\": \"account\",\n \"totalHours\": 609.265556,\n \"pcusPerYear\": 16,\n \"totalPcus\": 1.112814\n }\n ]\n },\n {\n \"id\": \"nonProduction\",\n \"type\": \"environmentType\",\n \"attributes\": {},\n \"usages\": [\n {\n \"productCode\": \"CM-PUBSUB+SERVICE-STD-100-SA-S\",\n \"displayName\": \"Standard 100 Standalone Service\",\n \"environmentType\": \"nonProduction\",\n \"totalHours\": 773.516389,\n \"pcusPerYear\": 20,\n \"totalPcus\": 1.76602\n },\n {\n \"productCode\": \"CM-PUBSUB+SERVICE-ENT-250-HA-S\",\n \"displayName\": \"Enterprise 250 HA Service\",\n \"environmentType\": \"nonProduction\",\n \"totalHours\": 125.161667,\n \"pcusPerYear\": 55,\n \"totalPcus\": 0.785833\n }\n ]\n },\n {\n \"id\": \"production\",\n \"type\": \"environmentType\",\n \"attributes\": {},\n \"usages\": [\n {\n \"productCode\": \"CM-PUBSUB+SERVICE-ENT-250-HA-S\",\n \"displayName\": \"Enterprise 250 HA Service\",\n \"environmentType\": \"production\",\n \"totalHours\": 6329.193056,\n \"pcusPerYear\": 55,\n \"totalPcus\": 39.738085\n },\n {\n \"productCode\": \"CM-PUBSUB+MICRO-INTEGRATIONS-SINGLE-S\",\n \"displayName\": \"Micro-Integration - Single\",\n \"environmentType\": \"production\",\n \"totalHours\": 271.772778,\n \"pcusPerYear\": 10,\n \"totalPcus\": 0.310243\n },\n {\n \"productCode\": \"CM-PUBSUB+SERVICE-STD-100-SA-S\",\n \"displayName\": \"Standard 100 Standalone Service\",\n \"environmentType\": \"production\",\n \"totalHours\": 6359.108333,\n \"pcusPerYear\": 20,\n \"totalPcus\": 14.518513\n }\n ]\n }\n ],\n \"meta\": {\n \"pagination\": {\n \"pageNumber\": 1,\n \"pageSize\": 1000,\n \"count\": 3,\n \"nextPage\": null,\n \"totalPages\": 1\n }\n }\n}",
"properties": {
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/UsageAggregationContainer"
}
},
"meta": {
"type": "object",
"additionalProperties": {},
"default": "",
"description": "The metadata about the response, which can include: