# Get billing usage statistics

Returns usage statistics for the current billing period including encounters, peer reviews, and documents

Endpoint: GET /v1/billing/usage/{module}
Version: 1.0.0
Security: bearerAuth

## Path parameters:

  - `module` (string, required)
    The billing module to get usage for (e.g., 'notes')
    Example: "notes"

## Response 200 fields (application/json):

  - `plan` (object, required)
    Current subscription plan details

  - `plan.name` (string)
    Name of the subscribed plan
    Example: "pro"

  - `plan.status` (string)
    Current subscription status
    Enum: "active", "past_due", "canceled", "incomplete", "incomplete_expired", "trialing", "paused"

  - `plan.ends_at` (string,null)
    Date when the subscription ends (if canceled)

  - `plan.active` (boolean)
    Whether the subscription is currently active
    Example: true

  - `plan.past_due` (boolean)
    Whether the subscription has past due payments

  - `plan.trial` (object)

  - `plan.trial.has_expired_trial` (boolean)
    Whether the user had a trial that has expired

  - `plan.trial.on_trial` (boolean)
    Whether the user is currently on a trial

  - `plan.trial.trial_ends_at` (string,null)
    Date when the trial ends

  - `usage` (object, required)
    Usage statistics for the current billing period

  - `usage.used` (number)
    Total usage count (weighted sum of all items)
    Example: 125

  - `usage.peer_reviews` (string)
    Weighted count of peer reviews (0.25 per review)
    Example: "25.00"

  - `usage.encounters` (string)
    Count of encounters (1.0 per encounter)
    Example: "75.00"

  - `usage.documents` (string)
    Weighted count of documents (0.5 per document)
    Example: "25.00"

  - `usage.period_start` (string)
    Start date of the current billing period
    Example: "Jan 1st, 2026"

  - `usage.period_end` (string)
    End date of the current billing period
    Example: "Jan 31st, 2026"

  - `usage.resets_at` (string)
    Date when usage resets
    Example: "2026-01-31"

  - `usage.limit` (integer)
    Maximum allowed usage for the current plan
    Example: 1000

  - `usage.updated` (string)
    Timestamp when usage was last calculated
    Example: "Jan 16 2026 10:30 AM"

## Response 401 fields (application/json):

  - `message` (string, required)
    Error message
    Example: "Validation failed"

  - `errors` (object)
    Detailed validation errors by field
    Example: {"email":["The email must be a valid email address","The email has already been taken"],"password":["The password must be at least 8 characters"],"template_name":["This field is required"]}