Skip to content
API Enriched

List usage details.

POST
/api/web/namespaces/{namespace}/usage_details
curl --request POST \
  --url https://example-corp.console.ves.volterra.io/api/v1/api/production/us-east-1/namespaces/default/api/web/namespaces/example/usage_details \
  --header 'Authorization: <Authorization>' \
  --header 'Content-Type: application/json' \
  --data '{ "from": "2026-04-15T12:00:00Z", "namespace": "example", "to": "2026-04-15T12:00:00Z" }'

List usage details per tenant and namespace. Some usage have only sense in the system namespace and this selector has no effect on it.

Examples of this operation.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
namespace
required
string

Namespace Namespace to be considered.

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json
List usage details request

Request message to GET usage details.

object
from
Timestamp from

Indicates the “from” part of the request.

string format: date-time
<= 1024 characters
namespace
Namespace

Namespace to be considered.

string
>= 6 characters <= 1024 characters
to
Timestamp to

Indicates the “to” part of the request.

string format: date-time
<= 1024 characters
Examplegenerated
{
  "from": "2026-04-15T12:00:00Z",
  "namespace": "example",
  "to": "2026-04-15T12:00:00Z"
}

Responses

Section titled “Responses”

200

Section titled “200”

A successful response.

Media typeapplication/json
List usage details response

Response message to GET usage details.

object
usage_items
Usage items

Collection of usage items, lines of response.

Array<object>
Usage item

Usage item represents a line in a usage report, including quantity and resource incurring usage.

object
end_timestamp
Timestamp end

End of the time unit.

string format: date-time
<= 1024 characters
hourly_breakdown
Hourly breakdown

An array of HourlyItem with usage per hour. The sum of these items will result into the parent’s object quantity Deprecated: use /hourly_usage_details along with hourly_breakdown_query.

Array<object>
Hourly usage item

One line of usage by an hour. One hour as the least resolution.

object
container
Container

Container name if this item correspond to the container usage. Otherwise it’s empty.

string
<= 1024 characters
deployment
Deployment

[x-required] Deployment name if this item correspond to the container usage. Otherwise it’s empty.

string
<= 1024 characters
end_timestamp
Timestamp end

End of the time unit.

string format: date-time
<= 1024 characters
quantity
Quantity

Quantity incurred.

number format: double
start_timestamp
Timestamp start

Beginning of the time unit.

string format: date-time
<= 1024 characters
unit_name
Unit name

Name of the quantity unit.

string
<= 1024 characters
hourly_breakdown_query
Hourly breakdown query

[x-required] A base64 encoded JSON which should be passed as is to /hourly_usage_details to GET hourly items for this aggregated usage.

string
<= 1024 characters
metric_label
Metric label

[x-required] ID of the usage type. As Usage type is shown for user and is a subject of frequent changes, this metric_label should be static and should be usage for mapping between calculated usage and aggregated_usage.

string
<= 1024 characters
namespace
Namespace

Namespace where the usage occurred.

string
>= 6 characters <= 1024 characters
object_name
Object name

Name of the object where the usage occurred.

string
<= 1024 characters
quantity
Quantity

Quantity incurred.

number format: double
start_timestamp
Timestamp start

Beginning of the time unit.

string format: date-time
<= 1024 characters
unit_name
Unit name

Name of the quantity unit.

string
<= 1024 characters
usage_type
Usage type

Type of the resource.

string
<= 1024 characters
Examplegenerated
{
  "usage_items": [
    {
      "end_timestamp": "2026-04-15T12:00:00Z",
      "hourly_breakdown": [
        {
          "container": "example",
          "deployment": "example",
          "end_timestamp": "2026-04-15T12:00:00Z",
          "quantity": 1,
          "start_timestamp": "2026-04-15T12:00:00Z",
          "unit_name": "example"
        }
      ],
      "hourly_breakdown_query": "example",
      "metric_label": "example",
      "namespace": "example",
      "object_name": "example",
      "quantity": 1,
      "start_timestamp": "2026-04-15T12:00:00Z",
      "unit_name": "example",
      "usage_type": "example"
    }
  ]
}

401

Section titled “401”

Returned when operation is not authorized.

Media typeapplication/json
string format: string
Examplegenerated
example

403

Section titled “403”

Returned when there is no permission to access resource.

Media typeapplication/json
string format: string
Examplegenerated
example

404

Section titled “404”

Returned when resource is not found.

Media typeapplication/json
string format: string
Examplegenerated
example

409

Section titled “409”

Returned when operation on resource is conflicting with current value.

Media typeapplication/json
string format: string
Examplegenerated
example

429

Section titled “429”

Returned when operation has been rejected as it is happening too frequently.

Media typeapplication/json
string format: string
Examplegenerated
example

500

Section titled “500”

Returned when server encountered an error in processing API.

Media typeapplication/json
string format: string
Examplegenerated
example

503

Section titled “503”

Returned when service is unavailable temporarily.

Media typeapplication/json
string format: string
Examplegenerated
example

504

Section titled “504”

Returned when server timed out processing request.

Media typeapplication/json
string format: string
Examplegenerated
example