Name

Usage

Series of the storage used (GB-months and cost) per day, month or hour.

HTTP method and path

GET/api/v6/storage/usage

https://developers.hablame.co/api/v6/storage/usage

What happens when you run it

Read only: it does not change your organization’s data.
The call is not charged.

What it does

Returns a series with what you used in each period, the total of the range and the one of the previous range of the same length, to compare. Per day or month, from and to are YYYY-MM-DD dates (Colombia time, to excluded) and the range is up to 400 days; without them, the current month. Per hour, they are ISO-8601 instants (without a zone they are read in Colombia time), the range is up to 7 days and the cost of each point comes as null: cost is computed per day.

byteSeconds is the exact storage (bytes times seconds stored) and comes as a string because it can exceed the largest integer JSON represents without losing precision.

Amounts are in micros of your organization’s currency (currency, ISO 4217): units multiplied by 10⁶ (1000000 is 1.00). Storage is billed per GB-month (decimal GB, 10⁹ bytes) according to how long each file was stored.

Availability and prerequisites

Published and available in the production API v6.
Every path starts at https://developers.hablame.co.
You need a Hablame API key to call it.

Create your API key

Authentication and permissions

Send your API key in the Authorization header with the Bearer scheme.

Who can call it: An API key with the storage service enabled.

Limits and operational notes

Usage limit: 10 requests per second.

The six Storage queries (summary, usage, list, detail, retention and pricing) share this per-organization quota: it is not a per-endpoint quota.

Path parameters

This endpoint has no path parameters.

Query parameters

Name	Type	Description and rules
`group`Optional	`string`	How the series is grouped. Allowed values:`day` `month` `hour`Default value:`day`
`from`Optional	`string`	Start of the range (included). Example:`2026-10-01`
`to`Optional	`string`	End of the range (excluded). Example:`2026-10-19`
`service`Optional	`string`	Code of the service that stored the files (the `service` of the responses). An unknown code answers `400 INVALID_FILTER`. Example:`callblasting`
`scope`Optional	`string`	Code of the file type within the service (the `scope` of the responses). Requires `service`. Example:`recordings`

HTTP headers

Name Type Description and rules

Name	Type	Description and rules
`Authorization`Required	`string`	Your API key with the Bearer scheme. Example:`Bearer hk_TU_API_KEY`

AuthorizationRequired

string

Your API key with the Bearer scheme.

Example:Bearer hk_TU_API_KEY

Request body

This endpoint takes no request body.

Successful responses

200

Usage series. The amounts in the example are illustrative.

Response example

{
  "success": true,
  "data": {
    "currency": "COP",
    "series": [
      { "period": "2026-10-01", "byteSeconds": "463856467968000", "gbMonths": "0.178957", "costMicro": 178957, "averageBytes": 5368709120 }
    ],
    "total": { "byteSeconds": "463856467968000", "gbMonths": "0.178957", "costMicro": 178957, "averageBytes": 5368709120 },
    "comparison": { "previous": { "byteSeconds": "0", "gbMonths": "0.000000", "costMicro": 0, "averageBytes": 0 } }
  },
  "meta": {
    "requestId": "5d0f3a9c7b2e41a8",
    "clientIp": "203.0.113.10",
    "timestamp": "2026-10-19T15:30:00+00:00",
    "responseTimeMs": 12.4
  }
}

The example values are illustrative.

Response fields

Name	Type	Description and rules
`success`Always present	`boolean`
`data`Always present	`object`
`data.currency`Always present	`string`	May come as `null`.
`data.series`Always present	`array<object>`
`data.series[].period`Always present	`string`	Day (`YYYY-MM-DD`), month (`YYYY-MM`) or hour (ISO-8601).
`data.series[].byteSeconds`Always present	`string`
`data.series[].gbMonths`Always present	`string`
`data.series[].costMicro`Always present	`integer`	May come as `null`.
`data.series[].averageBytes`Always present	`integer`	Average bytes stored in the period.
`data.total`Always present	`object`
`data.total.byteSeconds`Always present	`string`
`data.total.gbMonths`Always present	`string`
`data.total.costMicro`Always present	`integer`	May come as `null`.
`data.total.averageBytes`Always present	`integer`	Average bytes stored in the period.
`data.comparison`Always present	`object`
`data.comparison.previous`Always present	`object`
`data.comparison.previous.byteSeconds`Always present	`string`
`data.comparison.previous.gbMonths`Always present	`string`
`data.comparison.previous.costMicro`Always present	`integer`	May come as `null`.
`data.comparison.previous.averageBytes`Always present	`integer`	Average bytes stored in the period.
`meta`Always present	`object`	Response metadata.
`meta.requestId`Always present	`string`	Unique request identifier (16 hexadecimal characters). It matches the `X-Request-Id` header. Quote it when contacting support. Example:`b9b1704baffab211`
`meta.clientIp`Always present	`string`	IP the API saw your request come from. Useful if your API key only accepts certain networks. Example:`203.0.113.45`
`meta.timestamp`Always present	`string`	Date and time the response was built (ISO 8601 with offset). Format:`date-time`Example:`2026-06-04T19:43:59+00:00`
`meta.responseTimeMs`Always present	`number`	Time (ms) the server took to process the request. Example:`4.24`

Error codes

Every error response has the same shape: success set to false and an error object whose code says what happened. They are grouped here by kind, with the codes this endpoint can return.

Shape of an error response

Name	Type	Description and rules
`success`Always present	`boolean`	Fixed value:`false`
`meta`Always present	`object`	Response metadata.
`meta.requestId`Always present	`string`	Unique request identifier (16 hexadecimal characters). It matches the `X-Request-Id` header. Quote it when contacting support. Example:`b9b1704baffab211`
`meta.clientIp`Always present	`string`	IP the API saw your request come from. Useful if your API key only accepts certain networks. Example:`203.0.113.45`
`meta.timestamp`Always present	`string`	Date and time the response was built (ISO 8601 with offset). Format:`date-time`Example:`2026-06-04T19:43:59+00:00`
`meta.responseTimeMs`Always present	`number`	Time (ms) the server took to process the request. Example:`4.24`
`error`Always present	`object`
`error.code`Always present	`string`	Stable UPPER_SNAKE_CASE identifier. Clients branch on this value. Example:`AUTH_REQUIRED`
`error.legacyCode`	`integer`	Legacy v5 numeric code, only when a bridge exists. Omitted for codes born in v6. Example:`40002`
`error.type`Always present	`string`	URL to the error documentation. Format:`uri`Example:`https://developers.hablame.co/docs/v6/errors/auth-required`
`error.message`Always present	`string`	Human readable text, in English. It is for the developer log, not the end user: do not parse it.
`error.details`Always present	`array<object>`	Structured context (validation issues, affected resource). Empty array when there is no extra context.

Validation

400A parameter is not valid.

400INVALID_FILTER
A query parameter is not valid.

Authentication

401Invalid or missing credentials.

401AUTH_REQUIRED
No Bearer token was sent, and every call requires one.
Message the API returns: Authentication is required. Send your API key as `Authorization: Bearer <token>`.
401AUTH_INVALID_KEY
The API key is not recognized: wrong format, revoked or expired.
Message the API returns: The provided API key is invalid or has expired. Please verify the value sent in the `Authorization: Bearer` header.

Permissions

403The API key does not have the Storage service (storage), cannot be used from the request network, or the organization is not active.

403AUTH_SERVICE_NOT_ALLOWED
The key is not allowed to use the service behind this endpoint.
Message the API returns: This API key is not authorized to use the requested service.
403AUTH_IP_NOT_ALLOWED
The key only works from certain networks and your IP is not one of them.
Message the API returns: This API key cannot be used from this IP address. The address we saw is in `meta.clientIp`: call from one of the networks allowed for the key, or use a key that allows this one.
403ACCOUNT_NOT_ACTIVE
Your organization is suspended or closed.
Message the API returns: The organization associated with this API key is not active. Please contact support.

Usage limits

429Request limit exceeded.

429RATE_TPS_EXCEEDED
You exceeded your organization quota for this endpoint.
Message the API returns: You have exceeded the allowed request rate for this endpoint. Please wait before retrying.

Resource not found

This endpoint does not declare responses of this kind.

Internal errors and availability

503Storage is not responding right now. Retry after Retry-After.

503SERVICE_UNAVAILABLE
Generic 503: a service we depend on is not responding.

Other responses