Read your quota · PDFgine

What this endpoint answers

One call tells you where the month stands: how many pages the plan includes, how many are spent and whether overage is allowed. It is meant for your own dashboard and for the check you run before a bulk job.

Reads your monthly quota, consumption and overage state — suitable for surfacing inside your own dashboard.

Request

curl https://api.pdfgine.com/api/v1/usage \
  -H "X-PDFgine-Key: $PDFGINE_KEY"

Response

{
  "organizationName": "Northwind Trading Ltd.",
  "planCode": "business",
  "monthlyPageQuota": 5000,
  "usedPages": 1284,
  "quotaRemaining": 3716,
  "monthlyPreviewPageAllowance": 250,
  "usedPreviewPages": 32,
  "allowsOverage": true,
  "monthlyOverageCap": 1000,
  "overagePages": 0,
  "meteringBasis": "pdf-equivalent"
}

Field by field

Every count is for the current billing month and resets when it rolls over.

Field	What it means
`monthlyPageQuota`	Pages the plan includes this month.
`usedPages`	Pages produced so far this month.
`quotaRemaining`	monthlyPageQuota minus usedPages, as of this response.
`monthlyPreviewPageAllowance`	Preview pages the plan includes on top of the page quota; a preview does not eat the production quota.
`allowsOverage`	Whether renders continue once the quota is spent. When false, the next render answers 402.
`monthlyOverageCap`	How far past the quota renders may go when overage is allowed.
`meteringBasis`	What a page means for billing. pdf-equivalent counts a docx or html output as the same number of pages the PDF would have.

People and child companies

Two more ceilings come with the plan and are counted per tenant: how many people can be in the workspace, and how many child companies it can manage.

Plan	People	Child companies
Free	2	0
Go	3	0
Pro	10	5
Max	Unlimited	Unlimited

An invitation beyond the seat limit is refused when it is sent, not when it is accepted - so nobody spends time on an invitation that could never work.

What usually goes wrong

Do not call this endpoint after every render. Each render already answers with X-PDFgine-Quota-Remaining, which is the same number without a second round trip.
Previews and production renders are counted separately. A preview that did not move usedPages did not fail; it moved usedPreviewPages.
allowsOverage false and a spent quota means 402 on the next render, not a slower queue. Watch quotaRemaining, not the error.
Quota and rate limit are different ceilings. A key may call 120 times per 60 seconds however much quota is left; over that the answer is 429 with Retry-After.
Counters follow the billing month, not the calendar month. On a plan bought on the 12th the month rolls over on the 12th.