API reference

Usage

GET /v1/usage returns what your account used in a range of days, per meter and per day.

Endpoint

GET/v1/usage

Returns the requests, quantities and amounts of the calling account for a range of days: totals for the whole range, and the same figures for each day. A live key sees live usage. A test key sees test usage.

Request

Query parameter	Type	Description
from	string	The first day of the range, as YYYY-MM-DD. Default: the first day of the current month.
to	string	The last day of the range, as YYYY-MM-DD. Default: today.

Days are in UTC. Both ends of the range are included.
from must not be after to, and the range can cover at most 366 days.
With no parameters you get the current month so far.

bash

curl "https://api.smolmac.com/v1/usage?from=2026-10-01&to=2026-10-02" \
  -H "Authorization: Bearer $SMOL_API_KEY"

Response

200 OK

{
  "object": "usage",
  "livemode": true,
  "from": "2026-10-01",
  "to": "2026-10-02",
  "totals": {
    "requests": 210,
    "amount_usd": 2.28,
    "input_bytes": 364904448,
    "output_bytes": 123731968,
    "meters": {
      "images": { "requests": 200, "quantity": 200, "amount_usd": 2 },
      "unbilled": { "requests": 6, "quantity": 0, "amount_usd": 0 },
      "pdfs": { "requests": 4, "quantity": 7, "amount_usd": 0.28 }
    }
  },
  "daily": [
    {
      "day": "2026-10-01",
      "requests": 126,
      "amount_usd": 1.2,
      "input_bytes": 201326592,
      "output_bytes": 71303168,
      "meters": {
        "images": { "requests": 120, "quantity": 120, "amount_usd": 1.2 },
        "unbilled": { "requests": 6, "quantity": 0, "amount_usd": 0 }
      }
    },
    {
      "day": "2026-10-02",
      "requests": 84,
      "amount_usd": 1.08,
      "input_bytes": 163577856,
      "output_bytes": 52428800,
      "meters": {
        "images": { "requests": 80, "quantity": 80, "amount_usd": 0.8 },
        "pdfs": { "requests": 4, "quantity": 7, "amount_usd": 0.28 }
      }
    }
  ]
}

Fields

Field	Type	Description
object	string	Always "usage".
livemode	boolean	true when the figures are for live keys, false for test keys.
from	string	The first day of the range.
to	string	The last day of the range.
totals	object	The figures for the whole range.
daily	array	One entry for each day that had at least one request, oldest first. Each has day and the same fields as totals. A day with no requests has no entry.

totals and each entry of daily have these fields:

Field	Type	Description
requests	integer	The number of requests and jobs recorded, whether they succeeded or failed.
amount_usd	number	The value of the billable usage in US dollars, at the unit prices.
input_bytes	integer	The total size of the files received.
output_bytes	integer	The total size of the files returned.
meters	object	The same figures split by billing meter. Only meters that were used appear. Each value has requests, quantity (the units billed on that meter) and amount_usd.

Meter	Counts
`images`	Images compressed or converted, PDF pages rendered to images, and metadata removals. Quantity: files.
`pdfs`	PDFs compressed. Quantity: started hundreds of pages.
`documents`	Office documents converted. Quantity: files.
`audio_minutes`	Audio compressed or converted. Quantity: started minutes.
`video_units`	Video compressed or converted. Quantity: video units.
`files`	Fonts and tables converted. Quantity: files.
`unbilled`	Requests that were free: failed requests, kept-original results, and everything done with a test key. Quantity and amount are 0.

Reading the numbers

Counted. Direct requests and jobs. A job is counted on the day it finishes. A direct request refused before any work started, for example with 401 or 429, is not counted. Nor are requests that process nothing, such as reading a job or creating an upload.
Delay. A request appears here a few seconds after it finishes.
Amounts are usage, not invoices. amount_usd is the value of the usage at the unit prices in Billing. It is before any usage included in your plan and before any credit, and it does not contain plan fees or tax.
Test usage is all on the unbilled meter.

Errors

Code	Status	When
`bad_request`	400	from or to is not a real date in the form YYYY-MM-DD, from is after to, or the range is longer than 366 days.
`missing_key`, `invalid_key`, `revoked_key`	401	The API key is missing, wrong or revoked.
`no_payment_method`, `payment_required`	402	A live key on an account with no plan, or with an unpaid invoice.
`account_suspended`, `ip_not_allowed`	403	The account is suspended, or the key may not be used from this IP address.