---
title: "Get this month's usage"
method: GET
path: "/v1/usage"
tags: ["Usage"]
---

# Get this month's usage

`GET /v1/usage`

## Request

- Base URL: `https://api.ironfang.com/analytics`
- URL: `https://api.ironfang.com/analytics/v1/usage`
- Auth: one of:
  - HTTP bearer
  - HTTP bearer

This calendar month's (UTC) recordings: the analytics.recording meter of the organisation's billing account (its free allowance, what is used, held and charged), whether a new recording would be admitted now and, if not, whether Ironfang paused it, the organisation holds its stored-bytes limit or billing refuses it, and the organisation's capacity: sites, open recordings, and what it stores against what it may. A recording belongs to the month it was admitted in. Needs analytics.usage.read.

## Response `200`

This month's usage

- Usage
  - `billing` Meter, required
    - `billable` integer, required: How many are charged.
    - `budget` string, nullable, required: The monthly limit set for Ironfang Analytics before tax; null when it shares the account's.
    - `charge` string, required: The exact charge for used, before tax, in major units (for example "1.25").
    - `currency` string, required: ISO 4217 currency code: GBP.
    - `exempt` boolean, required: True when the account's Ironfang Analytics usage is counted and not charged.
    - `free_allowance` integer, required: Recordings the month includes free.
    - `free_used` integer, required: How many of them the free allowance covers.
    - `meter` 'analytics.recording', required
    - `remaining_free` integer, required: Free recordings neither used nor held.
    - `reserved` integer, required: Recordings admitted and not yet ended; each holds its unit until then.
    - `used` integer, required: Kept recordings counted in the month.
  - `collection` object, required
    - `code` string: The refusal code, as the collector answers a new recording: storage_limit, or the billing code; only with storage_limit and billing_paused.
    - `message` string: What to do about it; do not parse.
    - `state` 'recording' | 'paused' | 'storage_limit' | 'billing_paused', required: recording when a new recording would be admitted now; paused when Ironfang paused the organisation's collection; storage_limit when its unexpired recordings hold max_stored_bytes, until expiry or deletion frees room; billing_paused when its billing account refuses new recordings (the free allowance is used without paid usage, a budget is reached, paid usage is paused, and so on). Recordings already open carry on.
  - `max_open_recordings` integer, nullable, required: Recordings the organisation may have open at once; null for no limit of its own.
  - `max_sites` integer, required: Sites the organisation may have.
  - `max_stored_bytes` integer, required: What the organisation's unexpired recordings may hold: once stored_bytes reaches it, no new recording is admitted (the collector answers 429 storage_limit) until expiry or deletion frees room. 10 GiB, unless a managed partner's agreement sets another figure; paying more does not lift it.
  - `open_recordings` integer, required: Recordings admitted and not yet ended.
  - `period_end` string, date-time, required
  - `period_start` string, date-time, required: The first instant of the UTC calendar month the figures are for.
  - `recordings` integer, required: Recordings admitted in the month and kept: the billing count when billing is on.
  - `stored_bytes` integer, required: What the organisation's unexpired recordings hold.

## Other responses

- `401`: No credential, an invalid one, an expired partner integration key, or a delegated token where none is accepted (`unauthorized`, `invalid_api_key`, `api_key_expired`, `delegated_not_allowed`).
- `403`: The credential lacks the permission or scope, names another organisation, or belongs to a partner integration that is not active (`forbidden`, `insufficient_scope`, `integration_inactive`).

---

[API](https://skmtc.dev/ironfang/apis/ironfang-analytics-api.md) · [All operations](https://skmtc.dev/ironfang/apis/ironfang-analytics-api/llms.txt) · [OpenAPI document](https://skmtc.dev/ironfang/apis/ironfang-analytics-api/revisions/08197080c3d7?raw)