---
title: "Usage, cost and limits for the current period"
method: GET
path: "/v1/usage"
tags: ["Account"]
---

# Usage, cost and limits for the current period

`GET /v1/usage`

## Request

- Base URL: `https://api.galleyrender.com`
- URL: `https://api.galleyrender.com/v1/usage`
- Auth: HTTP bearer

## Response `200`

The account's position this billing period.

- Usage
  - `object` 'usage', required
  - `account` string, required
  - `plan` 'free' | 'solo' | 'starter' | 'growth' | 'scale', required
  - `period` string, required: The period the numbers cover. On a paid plan, the Stripe billing period — the one its invoice and spend cap cover — named by the instant it began, `YYYY-MM-DDTHH:MM:SSZ` in UTC. On a free account or a keyless trial, the calendar month, `YYYY-MM` in UTC.
  - `period_resets_on` string, date: The day the period turns over, in UTC: the renewal date on a paid plan, the 1st of next month otherwise.
  - `renders` integer, required
  - `billable_units` integer, required
  - `by_format` object
  - `cost_usd` number, required
  - `limits` object, required
    - `free_renders_per_month` integer
    - `free_renders_used` integer, nullable: Billable units charged against the free allowance this period. On an account that came up from a keyless trial this is lower than `billable_units`: the trial's renders stay in the period counters and are credited back (`trial_units_credited`). Null on a paid plan.
    - `free_renders_remaining` integer, nullable
    - `trial_units_credited` integer: Units spent before this account verified, which the free tier does not count. 0 for an account that never had a keyless trial, and reset when the period rolls over.
    - `monthly_spend_cap_usd` number: The monthly spend cap on overage — usage past the plan's included units, at the plan's own rate. An annual plan's cap is twelve of these over its billing year. Not enforced on a free account or a keyless trial, which cannot be billed.
    - `spend_remaining_usd` number: This period's cap less the overage run up so far, floored at 0. Included units spend none of it; on a free account or a trial it is always the whole cap.
  - `trial` object, nullable: Present only on a keyless trial account.
    - `renders_limit` integer
    - `renders_used` integer
    - `renders_remaining` integer
    - `upgrade` string
  - `prices` object, required
    - `png_usd` number
    - `pdf_page_usd` number
    - `meter_event_name` string
  - `imports` object: Document imports this period against the plan's count. Failed and refused imports are not counted.
    - `used` integer
    - `included` integer: 0 on Free: import is for paid plans.
    - `resets_on` string, date
  - `lifetime_renders` integer
  - `current_period` string: The period at the moment of the call. Identical to `period`.

## Other responses

- `401`: `authentication_error`.

---

[API](https://skmtc.dev/galleyrender/apis/galley-render-api.md) · [All operations](https://skmtc.dev/galleyrender/apis/galley-render-api/llms.txt) · [OpenAPI document](https://skmtc.dev/galleyrender/apis/galley-render-api/revisions/a85d68468cd2?raw)