---
title: "This month's metered use, capacity and hosted evidence"
method: GET
path: "/v1/usage"
tags: ["Usage"]
---

# This month's metered use, capacity and hosted evidence

`GET /v1/usage`

## Request

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

The month (UTC) as the organisation's billing account has it for Ironfang
Audit's meters - `captures` (`audit.capture`) and `retention_extension`
(`audit.retention_extension`): the free allowance, what has been settled,
what admitted audits still hold, and the charge so far before tax. Both are
null where unified billing is not running (`billing_enabled` false): audits
are then admitted on capacity alone and nothing is metered. Beside them, the
facts that are not billing: `sites` against `site_limit` and
`max_pages_per_audit` (capacity limits, the same for everyone), the
standard hosted retention new audits get, hosted bytes and the next expiry,
the `projection` of captures the active scheduled monitors may ask for this
month (pages x runs, an upper bound), and `daily` captures by UTC day of
admission. `quota` is deprecated: the launch-era shape, now captures
against the month's free allowance only.

## Response `200`

Usage

- Usage
  - `audits` integer, required
  - `billing_enabled` boolean, required: False where unified billing is not running; nothing is metered then.
  - `billing_mode` string: The billing account's mode: free, setup_pending, enabled, paused or closed.
  - `captures` MeterUsage, required
    - `charge` string, required: The month's charge for the meter so far, exact, before tax, in pounds.
    - `charge_minor` integer, required: The charge rounded to pence.
    - `currency` 'GBP', required
    - `exempt` boolean, required
    - `free_allowance` integer, required
    - `free_remaining` integer, required
    - `meter` string, required
    - `reserved` integer, required: Held by admitted work that has not finished.
    - `unit` string, required
    - `used` integer, required: Settled this month.
  - `catalogue_version` string: The rate catalogue version pricing the month.
  - `credits_consumed` integer: Page captures every audit of the organisation has been charged (and launch-era credits).
  - `daily` object[], required
    - `captures` integer, required
    - `day` string, date, required
  - `earliest_expiry` string, date-time
  - `max_pages_per_audit` integer, required: The per-audit page cap; each site's own page limit applies within it.
  - `period_end` string, date-time, required
  - `period_start` string, date-time, required
  - `projection` object, required
    - `captures` integer, required
    - `monitors` object[], required
  - `quota` object, required: The launch-era quota shape, kept for existing readers - captures against the month's free allowance only. Use captures.
  - `retained_bytes` integer, required
  - `retention_extension` MeterUsage, required
    - `charge` string, required: The month's charge for the meter so far, exact, before tax, in pounds.
    - `charge_minor` integer, required: The charge rounded to pence.
    - `currency` 'GBP', required
    - `exempt` boolean, required
    - `free_allowance` integer, required
    - `free_remaining` integer, required
    - `meter` string, required
    - `reserved` integer, required: Held by admitted work that has not finished.
    - `unit` string, required
    - `used` integer, required: Settled this month.
  - `retention_purchases` RetentionQuote[], required: Retention extensions bought this month, newest first, without their deadlines.
    - `amount` string, required: The fixed price, exact, before tax, in pounds.
    - `amount_minor` integer, required: The price rounded to pence.
    - `artifacts` integer, required
    - `audit_ids` string[], required
    - `bytes` integer, required: Hosted bytes the quote covers.
    - `catalogue_version` string, required
    - `created_at` string, date-time, required
    - `currency` 'GBP', required
    - `deadlines` object[]
      - `artifact_id` string, uuid, required
      - `audit_id` string, uuid, required
      - `byte_length` integer, required
      - `expires_after` string, date-time, required
      - `expires_before` string, date-time, required
    - `expires_at` string, date-time, required: The quote can be bought until then.
    - `id` string, uuid, required
    - `meter` 'audit.retention_extension', required
    - `months` integer, required
    - `prices_exclude_tax` true, required
    - `purchased_at` string, date-time
    - `quantity` integer, required: In the meter's unit (unit): the bytes rounded up to the unit's share of a decimal gigabyte, times months, at least ten GB-months.
    - `status` 'open' | 'expired' | 'purchased', required
    - `unit` string, required: The meter's unit, for example 0.1 GB-month.
  - `site_limit` integer, required: The site capacity limit; the same for every organisation.
  - `sites` integer, required
  - `standard_retention_days` integer, required: The hosted retention a new audit is promised.

## Other responses

- `401`: Problem response
- `403`: Problem response

---

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