Nombre

Consumo

Serie del almacenamiento usado (GB al mes y costo) por día, por mes o por hora.

Método HTTP y ruta

GET/api/v6/storage/usage

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

Qué pasa al ejecutarlo

Solo consulta: no cambia datos de tu organización.
La llamada no se cobra.

Qué hace

Devuelve una serie con lo que usaste en cada periodo, el total del rango y el del rango anterior de la misma duración, para comparar. Por día o por mes, from y to son fechas YYYY-MM-DD (hora de Colombia, to excluido) y el rango es de hasta 400 días; sin ellos, el mes en curso. Por hora, son instantes ISO-8601 (sin zona se leen en hora de Colombia), el rango es de hasta 7 días y el costo de cada punto llega en null: el costo se calcula por día.

byteSeconds es el almacenamiento exacto (bytes por segundos guardados) y llega como texto porque puede pasar del entero más grande que JSON representa sin perder precisión.

Los importes van en micros de la moneda de tu organización (currency, ISO 4217): unidades multiplicadas por 10⁶ (1000000 es 1,00). El almacenamiento se cobra por GB al mes (GB decimal, 10⁹ bytes) según el tiempo que cada archivo estuvo guardado.

Disponibilidad y requisitos previos

Publicado y disponible en la API v6 de producción.
Todas las rutas parten de https://developers.hablame.co.
Necesitas una API key de Hablame para llamarlo.

Crea tu clave de API

Autenticación y permisos

Envía tu API key en la cabecera Authorization con el esquema Bearer.

Quién puede llamarlo: Una API key con el servicio storage habilitado.

Límites y consideraciones operativas

Límite de uso: 10 solicitudes por segundo.

Las seis consultas de Almacenamiento (resumen, consumo, listado, detalle, conservación y tarifa) comparten este cupo por organización: no es un cupo por endpoint.

Parámetros de ruta

Este endpoint no tiene parámetros de ruta.

Parámetros de consulta

Nombre	Tipo	Descripción y reglas
`group`Opcional	`string`	Cómo se agrupa la serie. Valores permitidos:`day` `month` `hour`Valor por omisión:`day`
`from`Opcional	`string`	Inicio del rango (incluido). Ejemplo:`2026-10-01`
`to`Opcional	`string`	Fin del rango (excluido). Ejemplo:`2026-10-19`
`service`Opcional	`string`	Código del servicio que guardó los archivos (el `service` de las respuestas). Un código que no existe responde `400 INVALID_FILTER`. Ejemplo:`callblasting`
`scope`Opcional	`string`	Código del tipo de archivo dentro del servicio (el `scope` de las respuestas). Exige `service`. Ejemplo:`recordings`

Encabezados HTTP

Nombre Tipo Descripción y reglas

Nombre	Tipo	Descripción y reglas
`Authorization`Obligatorio	`string`	Tu API key con el esquema Bearer. Ejemplo:`Bearer hk_TU_API_KEY`

AuthorizationObligatorio

string

Tu API key con el esquema Bearer.

Ejemplo:Bearer hk_TU_API_KEY

Cuerpo de la petición

Este endpoint no recibe cuerpo en la petición.

Respuestas satisfactorias

200

Serie de consumo. Los importes del ejemplo son ilustrativos.

Ejemplo de respuesta

{
  "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
  }
}

Los valores del ejemplo son ilustrativos.

Campos de la respuesta

Nombre	Tipo	Descripción y reglas
`success`Siempre presente	`boolean`
`data`Siempre presente	`object`
`data.currency`Siempre presente	`string`	Puede llegar en `null`.
`data.series`Siempre presente	`array<object>`
`data.series[].period`Siempre presente	`string`	Día (`YYYY-MM-DD`), mes (`YYYY-MM`) u hora (ISO-8601).
`data.series[].byteSeconds`Siempre presente	`string`
`data.series[].gbMonths`Siempre presente	`string`
`data.series[].costMicro`Siempre presente	`integer`	Puede llegar en `null`.
`data.series[].averageBytes`Siempre presente	`integer`	Bytes guardados en promedio en el periodo.
`data.total`Siempre presente	`object`
`data.total.byteSeconds`Siempre presente	`string`
`data.total.gbMonths`Siempre presente	`string`
`data.total.costMicro`Siempre presente	`integer`	Puede llegar en `null`.
`data.total.averageBytes`Siempre presente	`integer`	Bytes guardados en promedio en el periodo.
`data.comparison`Siempre presente	`object`
`data.comparison.previous`Siempre presente	`object`
`data.comparison.previous.byteSeconds`Siempre presente	`string`
`data.comparison.previous.gbMonths`Siempre presente	`string`
`data.comparison.previous.costMicro`Siempre presente	`integer`	Puede llegar en `null`.
`data.comparison.previous.averageBytes`Siempre presente	`integer`	Bytes guardados en promedio en el periodo.
`meta`Siempre presente	`object`	Metadatos de la respuesta.
`meta.requestId`Siempre presente	`string`	Identificador único de la solicitud (16 caracteres hexadecimales). Es el mismo de la cabecera `X-Request-Id`. Cítalo al contactar soporte. Ejemplo:`b9b1704baffab211`
`meta.clientIp`Siempre presente	`string`	IP con la que la API vio tu solicitud. Útil si tu API key solo admite ciertas redes. Ejemplo:`203.0.113.45`
`meta.timestamp`Siempre presente	`string`	Fecha y hora en que se construyó la respuesta (ISO 8601 con offset). Formato:`date-time`Ejemplo:`2026-06-04T19:43:59+00:00`
`meta.responseTimeMs`Siempre presente	`number`	Tiempo (ms) que tomó procesar la solicitud en el servidor. Ejemplo:`4.24`

Códigos de error

Todas las respuestas de error tienen la misma forma: success en false y un objeto error cuyo code dice qué pasó. Aquí están agrupadas por tipo, con los códigos que este endpoint puede devolver.

Forma de una respuesta de error

Nombre	Tipo	Descripción y reglas
`success`Siempre presente	`boolean`	Valor fijo:`false`
`meta`Siempre presente	`object`	Metadatos de la respuesta.
`meta.requestId`Siempre presente	`string`	Identificador único de la solicitud (16 caracteres hexadecimales). Es el mismo de la cabecera `X-Request-Id`. Cítalo al contactar soporte. Ejemplo:`b9b1704baffab211`
`meta.clientIp`Siempre presente	`string`	IP con la que la API vio tu solicitud. Útil si tu API key solo admite ciertas redes. Ejemplo:`203.0.113.45`
`meta.timestamp`Siempre presente	`string`	Fecha y hora en que se construyó la respuesta (ISO 8601 con offset). Formato:`date-time`Ejemplo:`2026-06-04T19:43:59+00:00`
`meta.responseTimeMs`Siempre presente	`number`	Tiempo (ms) que tomó procesar la solicitud en el servidor. Ejemplo:`4.24`
`error`Siempre presente	`object`
`error.code`Siempre presente	`string`	Identificador estable en UPPER_SNAKE_CASE. Los clientes ramifican sobre este valor. Ejemplo:`AUTH_REQUIRED`
`error.legacyCode`	`integer`	Código numérico legacy v5, solo cuando hay puente. Se omite en los códigos nacidos en v6. Ejemplo:`40002`
`error.type`Siempre presente	`string`	URL a la documentación del error. Formato:`uri`Ejemplo:`https://developers.hablame.co/docs/v6/errors/auth-required`
`error.message`Siempre presente	`string`	Texto legible en inglés. Es para el log del desarrollador, no para el usuario final: no lo parsees.
`error.details`Siempre presente	`array<object>`	Contexto estructurado (validaciones, recurso afectado). Arreglo vacío cuando no hay contexto extra.

Validación

400Un parámetro no es válido.

400INVALID_FILTER
Un parámetro de la consulta no es válido.

Autenticación

401Credenciales inválidas o faltantes.

401AUTH_REQUIRED
No se envió un token Bearer y cada llamada lo requiere.
Mensaje que devuelve la API: Authentication is required. Send your API key as `Authorization: Bearer <token>`.
401AUTH_INVALID_KEY
La clave de API no se reconoce: formato equivocado, revocada o vencida.
Mensaje que devuelve la API: The provided API key is invalid or has expired. Please verify the value sent in the `Authorization: Bearer` header.

Permisos

403La API key no tiene el servicio Almacenamiento (storage), no se puede usar desde la red de la petición, o la organización no está activa.

403AUTH_SERVICE_NOT_ALLOWED
La clave no tiene permitido el servicio detrás de este endpoint.
Mensaje que devuelve la API: This API key is not authorized to use the requested service.
403AUTH_IP_NOT_ALLOWED
La clave solo funciona desde ciertas redes y tu IP no está entre ellas.
Mensaje que devuelve la API: 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
Tu organización está suspendida o cerrada.
Mensaje que devuelve la API: The organization associated with this API key is not active. Please contact support.

Límites de uso

429Se excedió el límite de solicitudes.

429RATE_TPS_EXCEEDED
Excediste el cupo de tu organización para este endpoint.
Mensaje que devuelve la API: You have exceeded the allowed request rate for this endpoint. Please wait before retrying.

Recurso inexistente

Este endpoint no declara respuestas de este tipo.

Errores internos y disponibilidad

503Almacenamiento no responde en este momento. Reintenta tras Retry-After.

503SERVICE_UNAVAILABLE
503 genérico: un servicio del que dependemos no responde.

Endpoints