Historic usage by container

Edit online

This API provides an interface to view historic usage for a container on the system.

The historic usage reports are broken down by day. You must provide the earliest time and the latest time (in milliseconds) you want reported through the query. The API will return the historic usage between the two specified dates (Inclusive). Date boundaries are defined by midnight UTC. By default the system holds up to 397 day's worth of historic usage, but may be able to report more if a container hasn't changed its usage over a long period of time. This API does not report the historic usage for the current day.

Byte-Hours and Object-Hours are calculated by (Usage * Duration of Usage In Hours). For example, if a container has 1000 bytes stored in it for the first 12 hours of a day, and 2000 bytes stored in it for the latter 12 hours, the Byte-Hours of the container is (1000 bytes * 12 hours) + (2000 bytes * 12 hours) = 36000 Byte-Hours.

Base command

GET <accesser>:8338/container/{container.name}/historic-usage?earliest-timestamp={timestamp}&latest-timestamp={timestamp}

Request

Table 1. Request parameters
Request parameter Style Type Description
earliest-timestamp

(required)

 query Integer A timestamp in milliseconds since the epoch representing the earliest date the API will return historic usage for.

The timestamp can be any time between midnight and 23:59:59.999 in a given day. This value must be less-than or equal to latest-timestamp.

Example:
  • Timestamp: 1605811893895
  • Interpreted Date: 19 Nov 2020

Midnight boundaries are determined in UTC time. For example, timestamp 1605830340000 is Nov 20 2020 for UTC-06:00, but the interpreted date would be Nov 19 2020 UTC.
latest-timestamp

(required)

 query Integer

A timestamp in milliseconds since the epoch representing the latest date the API will return historic usage for.

This date may a future date; however the response will only include historic usage up until the day previous to the time of the request.

The timestamp can be any time between midnight and 23:59:59.999 in a given day. This value must be greater-than or equal to earliest-timestamp.

Example:
  • Timestamp: 1605811893895
  • Interpreted Date: 19 Nov 2020

Midnight boundaries are determined in UTC time. For example, timestamp 1605830340000 is Nov 20 2020 for UTC-06:00, but the interpreted date would be Nov 19 2020 UTC.

Response

Table 2. Response parameters
Response Parameter Style Type Description
common request headers      
container_name Body String The name of the container.
start_date Body Date The parsed date specified in the query in YYYY-MM-DD format. This is the earliest date that can possibly appear in the response body.
end_date Body Date The parsed date specified in the query in YYYY-MM-DD format. This is the latest date that can possibly appear in the response body.
daily_usage_metrics Body List of Daily Usage Metrics A list of daily usage metrics for the specified container. There is an entry for each day if the historic usage exists for that date. An empty list means that no historic usage data was available between start_date and end_date. Historic Usage is not reported for the current date.

Table 3. Daily usage metrics response parameters
Response Parameter Style Type Description
date Body Date The day (YYYY-MM-DD format) that this daily usage entry corresponds to. Midnight-aligned in UTC timezone.
byte_hours Body Integer The byte hours of this container for the given date. This number is unbounded, and may be larger than a 64-bit number.
object_hours Body Integer The object hours of this container for the given date. This number is unbounded, and may be larger than a 64-bit number.

Table 4. HTTP response codes
HTTP Response Code Description
200 OK The Request was completed successfully.
400 Bad Request There is a syntax or semantic error with the request. Please see the response body for the specifics.
403 Forbidden The user does not have the proper permissions to access the Service API.
404 Not Found The specified account was not found on the system.

Example

Request
(Assuming request was sent some time during 2020-11-20)
GET <accesser>:8338/container/container0/historic-usage?earliest-timestamp=1601528411111&latest-timestamp=1605852000000
Response
{
  "container_name": "container0",
  "start_date": "2020-10-01",
  "end_date": "2020-11-20",
  "daily_usage_metrics": [
    {
      "date": "2020-10-01",
      "byte_hours": 80474767,
      "object_hours": 260798
    },
    {
      "date": "2020-10-02",
      "byte_hours": 65212935,
      "object_hours": 812852
    },
    {
      "date": "2020-10-03",
      "byte_hours": 45495447,
      "object_hours": 984610
    },
    {
      "date": "2020-10-04",
      "byte_hours": 86928129,
      "object_hours": 309734
    },
     
    (Dates Removed for brevity)
 u
    {
      "date": "2020-11-19",
      "byte_hours": 82735731592613,
      "object_hours": 23481537
    }
  ]
}