The Abacus Usage Metering and Aggregation REST API can be used by Cloud resource providers to submit usage data, usage dashboards to retrieve real time usage reports, and billing systems to retrieve the aggregated and rated usage data needed for billing. Cloud resources include services and application runtimes or containers for example.
Usage data is exchanged with Abacus in the form of usage documents. Each document type has a JSON representation and one or more REST methods.
Resource usage collection
Resource configuration
Resource pricing
Usage summary report
GraphQL usage query
The resource usage collection API can be used by Cloud resource providers to submit usage for instances of Cloud resources, including service instances and application runtimes or containers.
Usage can be submitted by POSTing resource usage documents to Abacus.
A resource usage document contains usage measurements for a Cloud resource.
Once a resource usage document has been submitted to Abacus it can be retrieved using GET.
HTTP request:
POST /v1/metering/collected/usage with a resource usage document
Description: Records the resource usage document and processes the Cloud resource usage data it contains.
HTTP response:
- 202 to indicate usage was accepted with the URL of the resource usage document in a Location header
- 400 to report an invalid request
- 401 to report an unauthorized request
- 403 to report an insufficient scope error, encountered when the resource_id value is invalid
- 429 to signal that rate-limit was reached
- 500 to report a server error
- 503 to report collector is overloaded
HTTP request:
GET /v1/metering/collected/usage/:usage_document_id
Description: Retrieves a previously submitted resource usage document.
HTTP response: 200 to indicate success with the requested resource usage document, 404 if the usage is not found, 500 to report a server error.
{
"start": 1396421450000,
"end": 1396421451000,
"organization_id": "us-south:54257f98-83f0-4eca-ae04-9ea35277a538",
"space_id": "d98b5916-3c77-44b9-ac12-04456df23eae",
"consumer_id": "app:d98b5916-3c77-44b9-ac12-045678edabae",
"resource_id": "object-storage",
"plan_id": "basic",
"resource_instance_id": "d98b5916-3c77-44b9-ac12-04d61c7a4eae",
"measured_usage": [
{
"measure": "storage",
"quantity": 10
},
{
"measure": "api_calls",
"quantity": 10
}
]
}{
"type": "object",
"required": [
"usage"
],
"properties": {
"start": {
"type": "integer",
"format": "utc-millisec"
},
"end": {
"type": "integer",
"format": "utc-millisec"
},
"organization_id": {
"type": "string"
},
"space_id": {
"type": "string"
},
"consumer_id": {
"type": "string"
},
"resource_id": {
"type": "string"
},
"plan_id": {
"type": "string"
},
"resource_instance_id": {
"type": "string"
},
"measured_usage": {
"type": "array",
"minItems": 1,
"items": {
"type": "object",
"required": [
"measure",
"quantity"
],
"properties": {
"measure": {
"type": "string"
},
"quantity": {
"type": "number"
}
},
"additionalProperties": false
},
"additionalItems": false
}
},
"additionalProperties": false,
"title": "Resource Usage"
}The resource type API is used by abacus to retrieve resource type for Cloud resources.
This API enable Cloud platform integrating Abacus to generalizes onboarded resource_ids to a single resource type.
HTTP request:
GET /v1/provisioning/resources/:resource_id/type
Description: Retrieves the resource type for the specified resource id.
HTTP response: 200 to indicate success with the requested resource type, 404 if the resource type is not found, 500 to report a server error.
The metering plan id API is used by abacus to retrieve metering plan id for Cloud resources.
Given the organization id, resource type, plan id, and time returns the metering plan id.
This API gives more flexibility to Cloud platform integrating Abacus. Cloud platform integrating Abacus would be able give different way of metering depending on the given organization id, resource type, plan id, and time.
HTTP request:
GET /v1/metering/plans/:metering_plan_id
Description: Retrieves the metering plan of the specified metering plan id.
HTTP response: 200 to indicate success with the requested metering configuration document, 404 if the configuration is not found, 500 to report a server error.
{
"plan_id": "basic-object-storage",
"measures": [
{
"name": "storage",
"unit": "BYTE"
},
{
"name": "api_calls",
"units": "CALL"
}
],
"metrics": [
{
"name": "storage",
"unit": "GIGABYTE",
"meter": "(m) => m.storage / 1073741824",
"accumulate": "(a, qty) => Math.max(a, qty)"
},
{
"name": "thousand_api_calls",
"unit": "THOUSAND_CALLS",
"meter": "(m) => m.light_api_calls / 1000",
"accumulate": "(a, qty) => a ? a + qty : qty",
"aggregate": "(a, qty) => a ? a + qty : qty",
"summarize": "(t, qty) => qty"
}
]
}{
"type": "object",
"required": [
"plan_id",
"measures",
"metrics"
],
"properties": {
"plan_id": {
"type": "string"
},
"measures": {
"type": "array",
"minItems": "1",
"items": {
"type": "object",
"required": [
"name",
"unit"
],
"properties": {
"name": {
"type": "string"
},
"unit": {
"type": "string"
}
},
"additionalProperties": false
},
"additionalItems": false
},
"metrics": {
"type": "array",
"minItems": 1,
"items": {
"type": "object",
"required": [
"name",
"unit"
],
"properties": {
"name": {
"type": "string"
},
"unit": {
"type": "string"
},
"meter": {
"type": "string"
},
"accumulate": {
"type": "string"
},
"aggregate": {
"type": "string"
},
"summarize": {
"type": "string"
}
},
"additionalProperties": false
},
"additionalItems": false
},
"additionalProperties": false,
"title": "Metering Plan"
}HTTP request:
POST /v1/metering/plans
Description: Creates metering plan based on the request body.
HTTP response: 201 to indicate success with the creation of the plan, 409 to indicate the plan has a conflict, 500 to report a server error.
{
"plan_id": "basic-object-storage",
"measures": [
{
"name": "storage",
"unit": "BYTE"
},
{
"name": "api_calls",
"units": "CALL"
}
],
"metrics": [
{
"name": "storage",
"unit": "GIGABYTE",
"meter": "(m) => m.storage / 1073741824",
"accumulate": "(a, qty) => Math.max(a, qty)"
},
{
"name": "thousand_api_calls",
"unit": "THOUSAND_CALLS",
"meter": "(m) => m.light_api_calls / 1000",
"accumulate": "(a, qty) => a ? a + qty : qty",
"aggregate": "(a, qty) => a ? a + qty : qty",
"summarize": "(t, qty) => qty"
}
]
}{
"type": "object",
"required": [
"plan_id",
"measures",
"metrics"
],
"properties": {
"plan_id": {
"type": "string"
},
"measures": {
"type": "array",
"minItems": "1",
"items": {
"type": "object",
"required": [
"name",
"unit"
],
"properties": {
"name": {
"type": "string"
},
"unit": {
"type": "string"
}
},
"additionalProperties": false
},
"additionalItems": false
},
"metrics": {
"type": "array",
"minItems": 1,
"items": {
"type": "object",
"required": [
"name",
"unit"
],
"properties": {
"name": {
"type": "string"
},
"unit": {
"type": "string"
},
"meter": {
"type": "string"
},
"accumulate": {
"type": "string"
},
"aggregate": {
"type": "string"
},
"summarize": {
"type": "string"
}
},
"additionalProperties": false
},
"additionalItems": false
},
"additionalProperties": false,
"title": "Metering Plan"
}The rating plans API is used by Abacus to retrieve rating plan documents for Cloud resources.
Rating plan documents describe the types of metrics, and rating, and charge formulas that must be used by Abacus to rate, and report usage for each type of Cloud resource.
This API defines the contract between Abacus and the Cloud platform integrating it. The Cloud platform can manage and store rating plan documents describing its Cloud resources in a platform specific way outside of Abacus, and is simply expected to make these documents available to Abacus at an API endpoint supporting a GET method.
HTTP request:
GET /v1/rating/plans/:rating_plan_id
Description: Retrieves the rating plan of the specified rating plan id.
HTTP response: 200 to indicate success with the requested rating plan document, 404 if the plan is not found, 500 to report a server error.
{
"plan_id": "object-rating-plan",
"metrics": [
{
"name": "storage"
},
{
"name": "thousand_api_calls",
"rate": "(p, qty) => p ? p * qty : 0",
"charge": "(t, cost) => cost"
}
]
}{
"type": "object",
"required": [
"plan_id",
"metrics"
],
"properties": {
"plan_id": {
"type": "string"
},
"metrics": {
"type": "array",
"minItems": 1,
"items": {
"type": "object",
"required": [
"name"
],
"properties": {
"name": {
"type": "string"
},
"rate": {
"type": "string"
},
"charge": {
"type": "string"
}
},
"additionalProperties": false
},
"additionalItems": false
},
"additionalProperties": false,
"title": "Metering Plan"
}HTTP request:
POST /v1/rating/plans
Description: Creates rating plan based on the request body.
HTTP response: 201 to indicate success with the creation of the plan, 409 to indicate the plan has a conflict, 500 to report a server error.
{
"plan_id": "object-rating-plan",
"metrics": [
{
"name": "storage"
},
{
"name": "thousand_api_calls",
"rate": "(p, qty) => p ? p * qty : 0",
"charge": "(t, cost) => cost"
}
]
}{
"type": "object",
"required": [
"plan_id",
"metrics"
],
"properties": {
"plan_id": {
"type": "string"
},
"metrics": {
"type": "array",
"minItems": 1,
"items": {
"type": "object",
"required": [
"name"
],
"properties": {
"name": {
"type": "string"
},
"rate": {
"type": "string"
},
"charge": {
"type": "string"
}
},
"additionalProperties": false
},
"additionalItems": false
},
"additionalProperties": false,
"title": "Metering Plan"
}The pricing plans API is used by Abacus to retrieve pricing plan data for Cloud resources.
Pricing plan documents are used to configure the prices of the metrics used to rate Cloud resources. Different prices can be defined for different countries.
This API defines the contract between Abacus and the Cloud platform integrating it. The Cloud platform can manage and store pricing plan data for its Cloud resources in a platform specific way outside of Abacus, and is simply expected to make the pricing data available to Abacus at an API endpoint supporting a GET method.
HTTP request:
GET /v1/pricing/plans/:pricing_plan_id
Description: Retrieves the pricing of the specified pricing plan id.
HTTP response: 200 to indicate success with the requested pricing plan data, 404 if the pricing data is not found, 500 to report a server error.
{
"plan_id": "object-pricing-basic",
"metrics": [
{
"name": "storage",
"prices": [
{
"country": "USA",
"price": 1
},
{
"country": "EUR",
"price": 0.7523
},
{
"country": "CAN",
"price": 1.06
}
]
},
{
"name": "thousand_api_calls",
"prices": [
{
"country": "USA",
"price": 0.03
},
{
"country": "EUR",
"price": 0.0226
},
{
"country": "CAN",
"price": 0.0317
}
]
}
]
}{
"title": "Price Plan",
"type": "object",
"properties": {
"plan_id": {
"type": "string"
},
"metrics": {
"type": "array",
"minItems": 1,
"items": {
"title": "metric",
"type": "object",
"properties": {
"name": {
"type": "string"
},
"prices": {
"type": "array",
"minItems": 1,
"items": {
"title": "price",
"type": "object",
"properties": {
"country": {
"type": "string"
},
"price": {
"type": "number"
}
},
"required": [
"country",
"price"
],
"additionalProperties": false
},
"additionalItems": false
}
},
"required": [
"name",
"prices"
],
"additionalProperties": false
},
"additionalItems": false
}
},
"required": [
"plan_id",
"metrics"
],
"additionalProperties": false
}
HTTP request:
POST /v1/pricing/plans
Description: Creates pricing plan based on the request body.
HTTP response: 201 to indicate success with the creation of the plan, 409 to indicate the plan has a conflict, 500 to report a server error.
{
"plan_id": "object-pricing-basic",
"metrics": [
{
"name": "storage",
"prices": [
{
"country": "USA",
"price": 1
},
{
"country": "EUR",
"price": 0.7523
},
{
"country": "CAN",
"price": 1.06
}
]
},
{
"name": "thousand_api_calls",
"prices": [
{
"country": "USA",
"price": 0.03
},
{
"country": "EUR",
"price": 0.0226
},
{
"country": "CAN",
"price": 0.0317
}
]
}
]
}{
"title": "Price Plan",
"type": "object",
"properties": {
"plan_id": {
"type": "string"
},
"metrics": {
"type": "array",
"minItems": 1,
"items": {
"title": "metric",
"type": "object",
"properties": {
"name": {
"type": "string"
},
"prices": {
"type": "array",
"minItems": 1,
"items": {
"title": "price",
"type": "object",
"properties": {
"country": {
"type": "string"
},
"price": {
"type": "number"
}
},
"required": [
"country",
"price"
],
"additionalProperties": false
},
"additionalItems": false
}
},
"required": [
"name",
"prices"
],
"additionalProperties": false
},
"additionalItems": false
}
},
"required": [
"plan_id",
"metrics"
],
"additionalProperties": false
}HTTP request:
GET /v1/metering/organizations/:organization_id/resource_types/:resource_type/plans/:plan_id/time/:time/metering_plan/id
Description: Retrieves the metering plan of the specified organization id, resource type, plan id at the specified time.
HTTP response: 200 to indicate success with the requested metering plan id, 404 if the metering plan id is not found, 500 to report a server error.
The rating plan id API is used by abacus to retrieve rating plan id for Cloud resources.
Given the organization id, resource type, plan id, and time returns the rating plan id.
This API gives more flexibility to Cloud platform integrating Abacus. Cloud platform integrating Abacus would be able give different way of rating depending on the given organization id, resource type, plan id, and time.
HTTP request:
GET /v1/rating/organizations/:organization_id/resource_types/:resource_type/plans/:plan_id/time/:time/rating_plan/id
Description: Retrieves the rating plan of the specified organization id, resource type, plan id at the specified time.
HTTP response: 200 to indicate success with the requested rating plan id, 404 if the rating plan id is not found, 500 to report a server error.
The pricing plan id API is used by abacus to retrieve pricing plan id for Cloud resources.
Given the organization id, resource type, plan id, and time returns the pricing plan id.
This API gives more flexibility to Cloud platform integrating Abacus. Cloud platform integrating Abacus would be able give different pricing depending on the given organization id, resource type, plan id, and time.
HTTP request:
GET /v1/pricing/organizations/:organization_id/resource_types/:resource_type/plans/:plan_id/time/:time/pricing_plan/id
Description: Retrieves the pricing plan of the specified organization id, resource type, plan id at the specified time.
HTTP response: 200 to indicate success with the requested pricing plan id, 404 if the pricing plan id is not found, 500 to report a server error.
The metering plans API is used by Abacus to retrieve metering plan documents for Cloud resources.
Metering plan documents describe the types of measurements, metrics, units, and metering, accumulation, aggregation, and reporting formulas that must be used by Abacus to meter, and report usage for each type of Cloud resource.
This API defines the contract between Abacus and the Cloud platform integrating it. The Cloud platform can manage and store metering plan documents describing its Cloud resources in a platform specific way outside of Abacus, and is simply expected to make these documents available to Abacus at an API endpoint supporting a GET method.
The usage summary report API can be used to retrieve aggregated usage summary report documents from Abacus.
HTTP request:
GET /v1/metering/organizations/:organization_id/aggregated/usage/:time
Description: Retrieves a usage report document containing a summary of the aggregated Cloud resource usage incurred by the specified organization at the specified time.
If Abacus is secured the response depends on the scopes of the oAuth token used to call the API. When system token is used the complete report with aggregated usage for the requested organization will be returned. When resource token is used than the report will contain only the resources specified by the resource token scopes.
HTTP response:
- 200 to indicate a success with a usage summary report JSON document
- 206 to alert that usage summary report JSON document contains partial content. For example missing consumer or space data for particular time of report
- 401 to report an unauthorized request
- 403 to report an insufficient scope error, encountered when the resource_id value is invalid
- 404 to report that usage is not found
- 500 to report a server error
- 503 to report that reporting is overloaded
{
"start": 1435622400000,
"end": 1435708799999,
"processed": 1435708800000,
"organization_id": "us-south:a3d7fe4d-3cb1-4cc3-a831-ffe98e20cf27",
"windows": [
[{
"charge": 46.09
}],
[{
"charge": 46.09
}],
[{
"charge": 46.09
}],
[{
"charge": 46.09
}],
[{
"charge": 46.09
}]
],
"id": "k-a3d7fe4d-3cb1-4cc3-a831-ffe98e20cf27-t-0001435622400000",
"spaces": [
{
"space_id": "aaeae239-f3f8-483c-9dd0-de5d41c38b6a",
"windows": [
[{
"charge": 46.09
}],
[{
"charge": 46.09
}],
[{
"charge": 46.09
}],
[{
"charge": 46.09
}],
[{
"charge": 46.09
}]
],
"consumers": [
{
"consumer_id": "app:d98b5916-3c77-44b9-ac12-045678edabae",
"windows": [
[{
"charge": 46.09
}],
[{
"charge": 46.09
}],
[{
"charge": 46.09
}],
[{
"charge": 46.09
}],
[{
"charge": 46.09
}]
],
"resources": [
{
"resource_id": "object-storage",
"charge": 46.09,
"aggregated_usage": [
{
"metric": "storage",
"windows": [
[{
"quantity": 1,
"summary": 1,
"charge": 1
}],
[{
"quantity": 1,
"summary": 1,
"charge": 1
}],
[{
"quantity": 1,
"summary": 1,
"charge": 1
}],
[{
"quantity": 1,
"summary": 1,
"charge": 1
}],
[{
"quantity": 1,
"summary": 1,
"charge": 1
}]
]
},
{
"metric": "thousand_light_api_calls",
"windows": [
[{
"quantity": 3,
"summary": 3,
"charge": 0.09
}],
[{
"quantity": 3,
"summary": 3,
"charge": 0.09
}],
[{
"quantity": 3,
"summary": 3,
"charge": 0.09
}],
[{
"quantity": 3,
"summary": 3,
"charge": 0.09
}],
[{
"quantity": 3,
"summary": 3,
"charge": 0.09
}]
]
},
{
"metric": "heavy_api_calls",
"windows": [
[{
"quantity": 300,
"summary": 300,
"charge": 45
}],
[{
"quantity": 300,
"summary": 300,
"charge": 45
}],
[{
"quantity": 300,
"summary": 300,
"charge": 45
}],
[{
"quantity": 300,
"summary": 300,
"charge": 45
}],
[{
"quantity": 300,
"summary": 300,
"charge": 45
}]
]
}
],
"plans": [
{
"plan_id": "basic",
"windows": [
[{
"charge": 46.09
}],
[{
"charge": 46.09
}],
[{
"charge": 46.09
}],
[{
"charge": 46.09
}],
[{
"charge": 46.09
}]
],
"aggregated_usage": [
{
"metric": "storage",
"windows": [
[{
"quantity": 1,
"summary": 1,
"cost": 1,
"charge": 1
}],
[{
"quantity": 1,
"summary": 1,
"cost": 1,
"charge": 1
}],
[{
"quantity": 1,
"summary": 1,
"cost": 1,
"charge": 1
}],
[{
"quantity": 1,
"summary": 1,
"cost": 1,
"charge": 1
}],
[{
"quantity": 1,
"summary": 1,
"cost": 1,
"charge": 1
}]
]
},
{
"metric": "thousand_light_api_calls",
"windows": [
[{
"quantity": 3,
"summary": 3,
"cost": 0.09,
"charge": 0.09
}],
[{
"quantity": 3,
"summary": 3,
"cost": 0.09,
"charge": 0.09
}],
[{
"quantity": 3,
"summary": 3,
"cost": 0.09,
"charge": 0.09
}],
[{
"quantity": 3,
"summary": 3,
"cost": 0.09,
"charge": 0.09
}],
[{
"quantity": 3,
"summary": 3,
"cost": 0.09,
"charge": 0.09
}]
]
},
{
"metric": "heavy_api_calls",
"windows": [
[{
"quantity": 300,
"summary": 300,
"cost": 45,
"charge": 45
}],
[{
"quantity": 300,
"summary": 300,
"cost": 45,
"charge": 45
}],
[{
"quantity": 300,
"summary": 300,
"cost": 45,
"charge": 45
}],
[{
"quantity": 300,
"summary": 300,
"cost": 45,
"charge": 45
}],
[{
"quantity": 300,
"summary": 300,
"cost": 45,
"charge": 45
}]
]
}
]
}
]
}
]
}
],
"resources": [
{
"resource_id": "object-storage",
"windows": [
[{
"charge": 46.09
}],
[{
"charge": 46.09
}],
[{
"charge": 46.09
}],
[{
"charge": 46.09
}],
[{
"charge": 46.09
}]
],
"aggregated_usage": [
{
"metric": "storage",
"windows": [
[{
"quantity": 1,
"summary": 1,
"charge": 1
}],
[{
"quantity": 1,
"summary": 1,
"charge": 1
}],
[{
"quantity": 1,
"summary": 1,
"charge": 1
}],
[{
"quantity": 1,
"summary": 1,
"charge": 1
}],
[{
"quantity": 1,
"summary": 1,
"charge": 1
}]
]
},
{
"metric": "thousand_light_api_calls",
"windows": [
[{
"quantity": 3,
"summary": 3,
"charge": 0.09
}],
[{
"quantity": 3,
"summary": 3,
"charge": 0.09
}],
[{
"quantity": 3,
"summary": 3,
"charge": 0.09
}],
[{
"quantity": 3,
"summary": 3,
"charge": 0.09
}],
[{
"quantity": 3,
"summary": 3,
"charge": 0.09
}]
]
},
{
"metric": "heavy_api_calls",
"windows": [
[{
"quantity": 300,
"summary": 300,
"charge": 45
}],
[{
"quantity": 300,
"summary": 300,
"charge": 45
}],
[{
"quantity": 300,
"summary": 300,
"charge": 45
}],
[{
"quantity": 300,
"summary": 300,
"charge": 45
}],
[{
"quantity": 300,
"summary": 300,
"charge": 45
}]
]
}
],
"plans": [
{
"plan_id": "basic",
"windows": [
[{
"charge": 46.09
}],
[{
"charge": 46.09
}],
[{
"charge": 46.09
}],
[{
"charge": 46.09
}],
[{
"charge": 46.09
}]
],
"aggregated_usage": [
{
"metric": "storage",
"windows": [
[{
"quantity": 1,
"summary": 1,
"charge": 1
}],
[{
"quantity": 1,
"summary": 1,
"charge": 1
}],
[{
"quantity": 1,
"summary": 1,
"charge": 1
}],
[{
"quantity": 1,
"summary": 1,
"charge": 1
}],
[{
"quantity": 1,
"summary": 1,
"charge": 1
}]
]
},
{
"metric": "thousand_light_api_calls",
"windows": [
[{
"quantity": 3,
"summary": 3,
"charge": 0.09
}],
[{
"quantity": 3,
"summary": 3,
"charge": 0.09
}],
[{
"quantity": 3,
"summary": 3,
"charge": 0.09
}],
[{
"quantity": 3,
"summary": 3,
"charge": 0.09
}],
[{
"quantity": 3,
"summary": 3,
"charge": 0.09
}]
]
},
{
"metric": "heavy_api_calls",
"windows": [
[{
"quantity": 300,
"summary": 300,
"charge": 45
}],
[{
"quantity": 300,
"summary": 300,
"charge": 45
}],
[{
"quantity": 300,
"summary": 300,
"charge": 45
}],
[{
"quantity": 300,
"summary": 300,
"charge": 45
}],
[{
"quantity": 300,
"summary": 300,
"charge": 45
}]
]
}
]
}
]
}
]
}
],
"resources": [
{
"resource_id": "object-storage",
"windows": [
[{
"charge": 46.09
}],
[{
"charge": 46.09
}],
[{
"charge": 46.09
}],
[{
"charge": 46.09
}],
[{
"charge": 46.09
}]
],
"aggregated_usage": [
{
"metric": "storage",
"windows": [
[{
"quantity": 1,
"summary": 1,
"charge": 1
}],
[{
"quantity": 1,
"summary": 1,
"charge": 1
}],
[{
"quantity": 1,
"summary": 1,
"charge": 1
}],
[{
"quantity": 1,
"summary": 1,
"charge": 1
}],
[{
"quantity": 1,
"summary": 1,
"charge": 1
}]
]
},
{
"metric": "thousand_light_api_calls",
"windows": [
[{
"quantity": 3,
"summary": 3,
"charge": 0.09
}],
[{
"quantity": 3,
"summary": 3,
"charge": 0.09
}],
[{
"quantity": 3,
"summary": 3,
"charge": 0.09
}],
[{
"quantity": 3,
"summary": 3,
"charge": 0.09
}],
[{
"quantity": 3,
"summary": 3,
"charge": 0.09
}]
]
},
{
"metric": "heavy_api_calls",
"windows": [
[{
"quantity": 300,
"summary": 300,
"charge": 45
}],
[{
"quantity": 300,
"summary": 300,
"charge": 45
}],
[{
"quantity": 300,
"summary": 300,
"charge": 45
}],
[{
"quantity": 300,
"summary": 300,
"charge": 45
}],
[{
"quantity": 300,
"summary": 300,
"charge": 45
}]
]
}
],
"plans": [
{
"plan_id": "basic",
"windows": [
[{
"charge": 46.09
}],
[{
"charge": 46.09
}],
[{
"charge": 46.09
}],
[{
"charge": 46.09
}],
[{
"charge": 46.09
}]
],
"aggregated_usage": [
{
"metric": "storage",
"windows": [
[{
"quantity": 1,
"summary": 1,
"charge": 1
}],
[{
"quantity": 1,
"summary": 1,
"charge": 1
}],
[{
"quantity": 1,
"summary": 1,
"charge": 1
}],
[{
"quantity": 1,
"summary": 1,
"charge": 1
}],
[{
"quantity": 1,
"summary": 1,
"charge": 1
}]
]
},
{
"metric": "thousand_light_api_calls",
"windows": [
[{
"quantity": 3,
"summary": 3,
"charge": 0.09
}],
[{
"quantity": 3,
"summary": 3,
"charge": 0.09
}],
[{
"quantity": 3,
"summary": 3,
"charge": 0.09
}],
[{
"quantity": 3,
"summary": 3,
"charge": 0.09
}],
[{
"quantity": 3,
"summary": 3,
"charge": 0.09
}]
]
},
{
"metric": "heavy_api_calls",
"windows": [
[{
"quantity": 300,
"summary": 300,
"charge": 45
}],
[{
"quantity": 300,
"summary": 300,
"charge": 45
}],
[{
"quantity": 300,
"summary": 300,
"charge": 45
}],
[{
"quantity": 300,
"summary": 300,
"charge": 45
}],
[{
"quantity": 300,
"summary": 300,
"charge": 45
}]
]
}
]
}
]
}
]
}{
"title": "organizationReport",
"type": "object",
"properties": {
"id": {
"type": "string"
},
"start": {
"type": "integer",
"format": "utc-millisec"
},
"end": {
"type": "integer",
"format": "utc-millisec"
},
"processed": {
"type": "integer",
"format": "utc-millisec"
},
"organization_id": {
"type": "string"
},
"windows": {
"type": "array",
"items": {
"title": "cwindow",
"type": "object",
"properties": {
"charge": {
"type": "number"
}
},
"required": [
"charge"
]
}
},
"resources": {
"type": "array",
"minItems": 1,
"items": {
"title": "resource",
"type": "object",
"properties": {
"resource_id": {
"type": "string"
},
"windows": {
"type": "array",
"items": {
"title": "cwindow",
"type": "object",
"properties": {
"charge": {
"type": "number"
}
},
"required": [
"charge"
]
}
},
"aggregated_usage": {
"type": "array",
"minItems": 1,
"items": {
"title": "rmetric",
"type": "object",
"properties": {
"metric": {
"type": "string"
},
"windows": {
"type": "array",
"items": {
"title": "rwindow",
"type": "object",
"properties": {
"quantity": {
"type": "number"
},
"summary": {
"type": "number"
},
"charge": {
"type": "number"
}
},
"required": [
"quantity",
"summary",
"charge"
]
}
}
},
"required": [
"metric",
"windows"
],
"additionalProperties": false
},
"additionalItems": false
},
"plans": {
"type": "array",
"minItems": 1,
"items": {
"title": "plan",
"type": "object",
"properties": {
"plan_id": {
"type": "string"
},
"windows": {
"type": "array",
"items": {
"title": "cwindow",
"type": "object",
"properties": {
"charge": {
"type": "number"
}
},
"required": [
"charge"
]
}
},
"aggregated_usage": {
"type": "array",
"minItems": 1,
"items": {
"title": "pmetric",
"type": "object",
"properties": {
"metric": {
"type": "string"
},
"windows": {
"type": "array",
"items": {
"title": "pwindow",
"type": "object",
"properties": {
"quantity": {
"type": "number"
},
"summary": {
"type": "number"
},
"cost": {
"type": "number"
},
"charge": {
"type": "number"
}
},
"required": [
"quantity",
"summary",
"cost",
"charge"
]
}
}
},
"required": [
"metric",
"windows"
],
"additionalProperties": false
},
"additionalItems": false
}
},
"required": [
"plan_id",
"windows",
"aggregated_usage"
],
"additionalProperties": false
},
"additionalItems": false
}
},
"required": [
"resource_id",
"windows",
"aggregated_usage",
"plans"
],
"additionalProperties": false
},
"additionalItems": false
},
"spaces": {
"type": "array",
"minItems": 1,
"items": {
"title": "space",
"type": "object",
"properties": {
"space_id": {
"type": "string"
},
"windows": {
"type": "array",
"items": {
"title": "cwindow",
"type": "object",
"properties": {
"charge": {
"type": "number"
}
},
"required": [
"charge"
]
}
},
"resources": {
"type": "array",
"minItems": 1,
"items": {
"title": "resource",
"type": "object",
"properties": {
"resource_id": {
"type": "string"
},
"windows": {
"type": "array",
"items": {
"title": "cwindow",
"type": "object",
"properties": {
"charge": {
"type": "number"
}
},
"required": [
"charge"
]
}
},
"aggregated_usage": {
"type": "array",
"minItems": 1,
"items": {
"title": "rmetric",
"type": "object",
"properties": {
"metric": {
"type": "string"
},
"windows": {
"type": "array",
"items": {
"title": "rwindow",
"type": "object",
"properties": {
"quantity": {
"type": "number"
},
"summary": {
"type": "number"
},
"charge": {
"type": "number"
}
},
"required": [
"quantity",
"summary",
"charge"
]
}
}
},
"required": [
"metric",
"windows"
],
"additionalProperties": false
},
"additionalItems": false
},
"plans": {
"type": "array",
"minItems": 1,
"items": {
"title": "plan",
"type": "object",
"properties": {
"plan_id": {
"type": "string"
},
"windows": {
"type": "array",
"items": {
"title": "cwindow",
"type": "object",
"properties": {
"charge": {
"type": "number"
}
},
"required": [
"charge"
]
}
},
"aggregated_usage": {
"type": "array",
"minItems": 1,
"items": {
"title": "pmetric",
"type": "object",
"properties": {
"metric": {
"type": "string"
},
"windows": {
"type": "array",
"items": {
"title": "pwindow",
"type": "object",
"properties": {
"quantity": {
"type": "number"
},
"summary": {
"type": "number"
},
"cost": {
"type": "number"
},
"charge": {
"type": "number"
}
},
"required": [
"quantity",
"summary",
"cost",
"charge"
]
}
}
},
"required": [
"metric",
"windows"
],
"additionalProperties": false
},
"additionalItems": false
}
},
"required": [
"plan_id",
"windows",
"aggregated_usage"
],
"additionalProperties": false
},
"additionalItems": false
}
},
"required": [
"resource_id",
"windows",
"aggregated_usage",
"plans"
],
"additionalProperties": false
},
"additionalItems": false
},
"consumers": {
"type": "array",
"minItems": 1,
"items": {
"title": "consumer",
"type": "object",
"properties": {
"consumer_id": {
"type": "string"
},
"windows": {
"type": "array",
"items": {
"title": "cwindow",
"type": "object",
"properties": {
"charge": {
"type": "number"
}
},
"required": [
"charge"
]
}
},
"resources": {
"type": "array",
"minItems": 1,
"items": {
"title": "resource",
"type": "object",
"properties": {
"resource_id": {
"type": "string"
},
"windows": {
"type": "array",
"items": {
"title": "cwindow",
"type": "object",
"properties": {
"charge": {
"type": "number"
}
},
"required": [
"charge"
]
}
},
"aggregated_usage": {
"type": "array",
"minItems": 1,
"items": {
"title": "rmetric",
"type": "object",
"properties": {
"metric": {
"type": "string"
},
"windows": {
"type": "array",
"items": {
"title": "rwindow",
"type": "object",
"properties": {
"quantity": {
"type": "number"
},
"summary": {
"type": "number"
},
"charge": {
"type": "number"
}
},
"required": [
"quantity",
"summary",
"charge"
]
}
}
},
"required": [
"metric",
"windows"
],
"additionalProperties": false
},
"additionalItems": false
},
"plans": {
"type": "array",
"minItems": 1,
"items": {
"title": "plan",
"type": "object",
"properties": {
"plan_id": {
"type": "string"
},
"windows": {
"type": "array",
"items": {
"title": "cwindow",
"type": "object",
"properties": {
"charge": {
"type": "number"
}
},
"required": [
"charge"
]
}
},
"aggregated_usage": {
"type": "array",
"minItems": 1,
"items": {
"title": "pmetric",
"type": "object",
"properties": {
"metric": {
"type": "string"
},
"windows": {
"type": "array",
"items": {
"title": "pwindow",
"type": "object",
"properties": {
"quantity": {
"type": "number"
},
"summary": {
"type": "number"
},
"cost": {
"type": "number"
},
"charge": {
"type": "number"
}
},
"required": [
"quantity",
"summary",
"cost",
"charge"
]
}
}
},
"required": [
"metric",
"windows"
],
"additionalProperties": false
},
"additionalItems": false
}
},
"required": [
"plan_id",
"windows",
"aggregated_usage"
],
"additionalProperties": false
},
"additionalItems": false
}
},
"required": [
"resource_id",
"windows",
"aggregated_usage",
"plans"
],
"additionalProperties": false
},
"additionalItems": false
}
},
"required": [
"consumer_id",
"windows",
"resources"
],
"additionalProperties": false
},
"additionalItems": false
}
},
"required": [
"space_id",
"windows",
"resources",
"consumers"
],
"additionalProperties": false
},
"additionalItems": false
}
},
"required": [
"id",
"organization_id",
"start",
"end",
"processed",
"windows",
"resources",
"spaces"
],
"additionalProperties": false
}The resource instance usage summary report API can be used to retrieve aggregated usage summary report documents for a resource instance from Abacus.
HTTP request:
GET /v1/metering/organizations/:organization_id/spaces/:space_id/resource_id/:resource_id/resource_instances/:resource_instance_id/consumers/:consumer_id/plans/:plan_id/metering_plans/:metering_plan_id/rating_plans/:rating_plan_id/pricing_plans/:pricing_plan_id/t/:t/aggregated/usage/:time
Description: Retrieves a usage report document containing a summary of the aggregated Cloud resource usage incurred by the specified resource instance within an organization and the specific set of plans at the specified time.
HTTP response:
- 200 to indicate a success with a usage summary report JSON document
- 206 to alert that usage summary report JSON document contains partial content. For example missing consumer or space data for particular time of report
- 401 to report an unauthorized request
- 403 to report an insufficient scope error, encountered when the resource_id value is invalid
- 404 to report that usage is not found
- 500 to report a server error
- 503 to report that reporting is overloaded
{
"start": 1435622400000,
"end": 1435708799999,
"processed": 1435708800000,
"organization_id": "us-south:a3d7fe4d-3cb1-4cc3-a831-ffe98e20cf27",
"plan_id": "basic",
"metering_plan_id": "test-metering-plan",
"rating_plan_id": "test-rating-plan",
"pricing_plan_id": "test-pricing-basic",
"consumer_id": "app:d98b5916-3c77-44b9-ac12-045678edabae",
"resource_instance_id": "0b39fa70-a65f-4183-bae8-385633ca5c87",
"space_id": "aaeae239-f3f8-483c-9dd0-de5d41c38b6a",
"resource_id": "object-storage",
"accumulated_usage": [
{
"metric": "storage",
"windows": [
[{
"quantity": 1,
"summary": 1,
"cost": 1,
"charge": 1
}],
[{
"quantity": 1,
"summary": 1,
"cost": 1,
"charge": 1
}],
[{
"quantity": 1,
"summary": 1,
"cost": 1,
"charge": 1
}],
[{
"quantity": 1,
"summary": 1,
"cost": 1,
"charge": 1
}],
[{
"quantity": 1,
"summary": 1,
"cost": 1,
"charge": 1
}]
]
},
{
"metric": "thousand_light_api_calls",
"windows": [
[{
"quantity": 3,
"summary": 3,
"cost": 0.09,
"charge": 0.09
}],
[{
"quantity": 3,
"summary": 3,
"cost": 0.09,
"charge": 0.09
}],
[{
"quantity": 3,
"summary": 3,
"cost": 0.09,
"charge": 0.09
}],
[{
"quantity": 3,
"summary": 3,
"cost": 0.09,
"charge": 0.09
}],
[{
"quantity": 3,
"summary": 3,
"cost": 0.09,
"charge": 0.09
}]
]
},
{
"metric": "heavy_api_calls",
"windows": [
[{
"quantity": 300,
"summary": 300,
"cost": 45,
"charge": 45
}],
[{
"quantity": 300,
"summary": 300,
"cost": 45,
"charge": 45
}],
[{
"quantity": 300,
"summary": 300,
"cost": 45,
"charge": 45
}],
[{
"quantity": 300,
"summary": 300,
"cost": 45,
"charge": 45
}],
[{
"quantity": 300,
"summary": 300,
"cost": 45,
"charge": 45
}]
]
}
],
"windows": [
[{
"charge": 46.09,
}],
[{
"charge": 46.09,
}],
[{
"charge": 46.09,
}],
[{
"charge": 46.09,
}],
[{
"charge": 46.09,
}]
],
"id": "k/us-south:a3d7fe4d-3cb1-4cc3-a831-ffe98e20cf27/0b39fa70-a65f-4183-bae8-385633ca5c87/app:d98b5916-3c77-44b9-ac12-045678edabae/basic/test-metering-plan/test-rating-plan/test-pricing-basic/t/0001435622400000",
}{
"title": "resourceInstanceReport",
"type": "object",
"properties": {
"id": {
"type": "string"
},
"start": {
"type": "integer",
"format": "utc-millisec"
},
"end": {
"type": "integer",
"format": "utc-millisec"
},
"processed": {
"type": "integer",
"format": "utc-millisec"
},
"organization_id": {
"type": "string"
},
"space_id": {
"type": "string"
},
"resource_instance_id": {
"type": "string"
},
"consumer_id": {
"type": "string"
},
"plan_id": {
"type": "string"
},
"metering_plan_id": {
"type": "string"
},
"rating_plan_id": {
"type": "string"
},
"pricing_plan_id": {
"type": "string"
},
"accumulated_usage": {
"type": "array",
"items": {
"title": "accumulated",
"type": "object",
"properties": {
"metric": {
"type": "string"
},
"windows": {
"type": "array",
"items": {
"title": "pwindow",
"type": "object",
"properties": {
"quantity": {
"type": "number"
},
"summary": {
"type": "number"
},
"cost": {
"type": "number"
},
"charge": {
"type": "number"
}
},
"required": [
"quantity",
"summary",
"cost",
"charge"
]
}
}
}
},
"required": [
"metric",
"windows"
]
},
"windows": {
"type": "array",
"items": {
"title": "cwindow",
"type": "object",
"properties": {
"charge": {
"type": "number"
}
},
"required": [
"charge"
]
}
}
},
"required": [
"id",
"organization_id",
"space_id",
"resource_instance_id",
"consumer_id",
"resource_id",
"plan_id",
"metering_plan_id",
"rating_plan_id",
"pricing_plan_id",
"start",
"end",
"processed",
"accumulated_usage",
"windows"
],
"additionalProperties": false
}The GraphQL usage query API can be used to query aggregated usage using the GraphQL query language.
Abacus defines a GraphQL schema for aggregated usage, allowing users to navigate and query the graph of aggregated usage within organizations and the spaces and resources they contain using the GraphQL query language.
The GraphQL schema listed below describes the graph used to represent aggregated usage, as well as the supported usage queries.
See the GraphQL documentation for more information on the GraphQL schema and query languages.
HTTP request:
GET /v1/metering/aggregated/usage/graph/:query
Description: Retrieves a usage report document containing a summary of the Cloud resource usage matching the specified GraphQL query.
HTTP response:
- 200 to indicate a success with a usage summary report JSON document
- 206 to alert that usage summary report JSON document contains partial content. For example missing consumer or space data for particular time of report
- 401 to report an unauthorized request
- 403 to report an insufficient scope error, encountered when the resource_id value is invalid
- 404 to report that usage is not found
- 500 to report a server error
- 503 to report that reporting is overloaded
{
organization(
organization_id: "us-south:a3d7fe4d-3cb1-4cc3-a831-ffe98e20cf27",
time: 1435622400000) {
organization_id,
resources {
resource_id,
aggregated_usage {
metric,
windows {
quantity
}
}
}
}
}
{
organization(
organization_id: "us-south:a3d7fe4d-3cb1-4cc3-a831-ffe98e20cf27",
time: 1435622400000) {
organization_id,
spaces {
space_id,
resources {
resource_id,
aggregated_usage {
metric,
windows {
quantity
}
}
}
}
}
}
{
organization(
organization_id: "us-south:a3d7fe4d-3cb1-4cc3-a831-ffe98e20cf27",
time: 1435622400000) {
organization_id,
spaces {
space_id,
consumers {
consumer_id,
resources {
resource_id,
aggregated_usage {
metric,
windows {
quantity
}
}
}
}
}
}
}
{
organization(
organization_id: "us-south:a3d7fe4d-3cb1-4cc3-a831-ffe98e20cf27",
time: 1435622400000) {
organization_id,
spaces {
space_id,
consumers {
consumer_id
}
}
}
}
{
organization(
organization_id: "us-south:a3d7fe4d-3cb1-4cc3-a831-ffe98e20cf27",
time: 1435622400000) {
organization_id,
resources {
resource_id,
aggregated_usage {
metric,
windows {
quantity
}
}
}
}
}
{
organizations(
organization_ids: [
"us-south:a3d7fe4d-3cb1-4cc3-a831-ffe98e20cf27",
"us-south:b3d7fe4d-3cb1-4cc3-a831-ffe98e20cf28"],
time: 1435622400000) {
organization_id,
resources {
resource_id,
aggregated_usage {
metric,
windows {
quantity
}
}
}
}
}
{
account(
account_id: "1234",
time: 1435622400000) {
organization_id,
resources {
resource_id,
aggregated_usage {
metric,
windows {
quantity
}
}
}
}
}
{
resource_instance(
organization_id: "us-south:a3d7fe4d-3cb1-4cc3-a831-ffe98e20cf27",
consumer_id: "bbeae239-f3f8-483c-9dd0-de6781c38bab",
resource_instance_id: "0b39fa70-a65f-4183-bae8-385633ca5c87",
plan_id: "basic",
time: time: 1435622400000) {
organization_id,
space_id,
resource_id,
resource_instance_id,
plan_id,
accumulated_usage {
metric,
windows {
summary,
charge
}
}
}
}type ChargeWindow {
charge: Float
}
type PlanWindow {
quantity: Float
cost: Float
summary: Float
charge: Float
}
type PlanMetric {
metric: String
windows: [[PlanWindow]]
}
type Plan {
plan_id: String
windows: [[ChargeWindow]]
aggregated_usage: [PlanMetric]
}
type ResourceWindow {
quantity: Float
summary: Float
charge: Float
}
type ResourceMetric {
metric: String
windows: [[ResourceWindow]]
}
type Resource {
resource_id: String
windows: [[ChargeWindow]]
aggregated_usage: [ResourceMetric]
plans: [Plan]
}
type Consumer {
consumer_id: String
windows: [[ChargeWindow]]
resources: [Resource]
}
type Space {
space_id: String
windows: [[ChargeWindow]]
resources: [Resource]
consumers: [Consumer]
}
type OrganizationReport {
id: String
start: Int
end: Int
organization_id: String
windows: [[ChargeWindow]]
resources: [Resource]
spaces: [Space]
}
type resourceInstanceReport {
id: String
start: Int
end: Int
organization_id: String
space_id: String
resource_id: String
resource_instance_id: String
consumer_id: String
plan_id: String
windows: [[ChargeWindow]]
accumulated_usage: [PlanMetric]
}
type Query {
organization(
organization_id: String!,
time: Int) : OrganizationReport
organizations(
organization_ids: [String],
time: Int) : [OrganizationReport]
account(
account_id: String!,
time: Int) : [OrganizationReport]
}