Ironfang Analytics Usage API

openapi: 3.2.0
info:
  title: Ironfang Analytics Usage API
  version: 0.1.0
  summary: Sites, origins, public keys and capture settings for session replay and web analytics.
  description: 'Ironfang Analytics follows each visit to your website as a session:

    the pages a visitor saw, in every tab, with how long they stayed, the

    errors and failed requests they met, the events your pages tracked, and

    the recordings that let you replay it, live or afterwards.'
  contact:
    name: Ironfang
    email: hello@ironfang.uk
    url: https://ironfang.com/contact
  termsOfService: https://ironfang.com/legal/terms
  license:
    name: Proprietary - use governed by the Ironfang terms of service
    url: https://ironfang.com/legal/terms
servers:
- url: https://api.ironfang.com/analytics
security:
- apiKey: []
- bearerAuth: []
tags:
- name: Usage
  description: This month's recordings as the organisation's billing account counts them, and whether new recordings are being admitted.
paths:
  /v1/usage:
    get:
      tags:
      - Usage
      operationId: getUsage
      summary: Get this month's usage
      description: '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.'
      responses:
        '200':
          description: This month's usage
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Usage'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
components:
  schemas:
    Meter:
      type: object
      required:
      - meter
      - free_allowance
      - used
      - free_used
      - billable
      - reserved
      - remaining_free
      - charge
      - currency
      - exempt
      - budget
      properties:
        meter:
          type: string
          enum:
          - analytics.recording
        free_allowance:
          type: integer
          description: Recordings the month includes free.
        used:
          type: integer
          description: Kept recordings counted in the month.
        free_used:
          type: integer
          description: How many of them the free allowance covers.
        billable:
          type: integer
          description: How many are charged.
        reserved:
          type: integer
          description: Recordings admitted and not yet ended; each holds its unit until then.
        remaining_free:
          type: integer
          description: Free recordings neither used nor held.
        charge:
          type: string
          description: The exact charge for used, before tax, in major units (for example "1.25").
        currency:
          type: string
          description: 'ISO 4217 currency code: GBP.'
        exempt:
          type: boolean
          description: True when the account's Ironfang Analytics usage is counted and not charged.
        budget:
          type:
          - string
          - 'null'
          description: The monthly limit set for Ironfang Analytics before tax; null when it shares the account's.
    Error:
      type: object
      required:
      - error
      properties:
        error:
          type: object
          required:
          - code
          - message
          - docs
          properties:
            code:
              type: string
              description: Stable machine-readable code.
            message:
              type: string
              description: Human-readable explanation; do not parse.
            docs:
              type: string
              format: uri
        request_id:
          type: string
    Usage:
      type: object
      required:
      - period_start
      - period_end
      - recordings
      - billing
      - collection
      - open_recordings
      - stored_bytes
      - max_stored_bytes
      - max_sites
      - max_open_recordings
      properties:
        period_start:
          type: string
          format: date-time
          description: The first instant of the UTC calendar month the figures are for.
        period_end:
          type: string
          format: date-time
        recordings:
          type: integer
          description: 'Recordings admitted in the month and kept: the billing count when billing is on.'
        billing:
          description: The analytics.recording meter of the organisation's billing account; null when this deployment does not bill yet.
          oneOf:
          - $ref: '#/components/schemas/Meter'
          - type: 'null'
        collection:
          type: object
          required:
          - state
          properties:
            state:
              type: string
              enum:
              - recording
              - paused
              - storage_limit
              - billing_paused
              description: 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.
            code:
              type: string
              description: 'The refusal code, as the collector answers a new recording: storage_limit, or the billing code; only with storage_limit and billing_paused.'
            message:
              type: string
              description: What to do about it; do not parse.
        open_recordings:
          type: integer
          description: Recordings admitted and not yet ended.
        stored_bytes:
          type: integer
          description: What the organisation's unexpired recordings hold.
        max_stored_bytes:
          type: integer
          description: '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.'
        max_sites:
          type: integer
          description: Sites the organisation may have.
        max_open_recordings:
          type:
          - integer
          - 'null'
          description: Recordings the organisation may have open at once; null for no limit of its own.
  responses:
    Forbidden:
      description: 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`).
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: 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`).
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    apiKey:
      type: http
      scheme: bearer
      bearerFormat: if_live_ platform API key
      description: 'A platform API key minted in the portal. Its scopes are its

        permissions - `analytics:sites:read`, `analytics:sites:write` and the

        other `analytics:` scopes, or `analytics:*` - and it acts only in the

        organisation it was minted for. Keys without the scope a route needs

        are refused with 403.

        '
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: Warden JWT
      description: 'A Warden user token. Each route also requires a tenant permission in

        the acting tenant (`X-Ironfang-Tenant`), resolved live from Warden,

        which each operation names: sites need `analytics.sites.read` to read

        and `analytics.sites.write` to change; sessions, recordings and

        heatmaps need `analytics.sessions.read`, and deleting a session or a

        recording `analytics.sessions.delete`. A missing permission is 403; a

        permission lookup failure is 503.

        '
externalDocs:
  description: Ironfang Analytics documentation
  url: https://ironfang.com/analytics/docs
x-provenance:
  method: harvested
  publisher: Ironfang
  source: https://api.ironfang.com/analytics/openapi.yaml
  note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
    stamped by stamp-openapi-provenance.py (roadmap#793)