---
title: "Runs, events and metered interactions"
method: GET
path: "/v1/usage"
tags: ["Usage"]
---

# Runs, events and metered interactions

`GET /v1/usage`

## Request

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

Counts the organisation's runs started in the window and the events those runs recorded, by type, plus how many runs are active now. The window defaults to the current UTC calendar month to date and may span at most 92 days. Where unified billing runs, `billing` adds the organisation's `rig.interaction` meter for the current billing period (the UTC calendar month, whatever the window) from the billing ledger: the free allowance, how many interactions were used and are reserved, and the charge so far before tax. One interaction is one accepted inbound email, inbound callback or mock exchange with its response; a transport retry carrying the same identity (an email's Message-ID with the same bytes, a callback's `Idempotency-Key` or `Webhook-Id` with the same request) counts once, so `used` can be below the event counts. Creating projects, suites, runs and resources, faults, replays, waits, reads and assertions are never metered. `billing` is null where interactions are not metered. Reading usage is never metered. Needs rig.read.

## Query parameters

- `since` string, date-time
- `until` string, date-time

## Response `200`

The counts

- Usage
  - `billing` object, nullable, required: The rig.interaction meter in the current billing period, from the billing ledger; null where interactions are not metered.
    - `allowance` integer, required: Free interactions this period.
    - `billable` integer, required: Interactions beyond the free allowance.
    - `catalogue_version` string, required: The rate catalogue version that prices the period.
    - `charge` string, required: The exact charge so far in pounds before tax.
    - `currency` 'GBP', required
    - `exempt` boolean, required: The account is exempt from settlement for Ironfang Rig.
    - `free_used` integer, required
    - `meter` 'rig.interaction', required
    - `mode` 'free' | 'setup_pending' | 'enabled' | 'paused' | 'closed', required: The billing account's mode: free accounts stop at the free allowance.
    - `period` object, required
      - `end` string, date-time, required
      - `start` string, date-time, required
    - `remaining_free` integer, required
    - `reserved` integer, required: Interactions admitted and not yet settled; normally 0.
    - `unit` string, required
    - `unit_plural` string, required
    - `used` integer, required: Interactions counted this period.
  - `events` object, required: Events recorded by the runs started in the window; by_type carries every type seen.
    - `by_type` object, required
    - `callback_received` integer, required
    - `callback_replayed` integer, required
    - `connector_request_completed` integer, required
    - `email_received` integer, required
    - `fault_injected` integer, required
    - `mock_request_received` integer, required
    - `total` integer, required
    - `usage_refused` integer, required: Inbound interactions the billing ledger refused; they were not recorded.
  - `period` object, required
    - `end` string, date-time, required
    - `start` string, date-time, required
  - `runs` object, required: Runs started in the window by how they ended, plus the number active right now.
    - `active_now` integer, required
    - `cancelled` integer, required
    - `expired` integer, required
    - `failed` integer, required
    - `finished` integer, required
    - `no_outcome` integer, required
    - `passed` integer, required
    - `started` integer, required

## Other responses

- `400`: An unknown, repeated or malformed query parameter (`invalid_query`).
- `401`: No credential, an invalid one, or a delegated token where none is accepted (`unauthorized`, `invalid_api_key`, `delegated_not_allowed`).
- `403`: The credential lacks the permission or scope, or names another organisation (`forbidden`, `insufficient_scope`).

---

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