Usage and limits / GET /v1/usage
Check API usage and remaining document quota
How many documents have been used this billing period, what the limit is, and what the plans are, all readable from the API rather than from a dashboard.
What it is for
Because a document generation feature that stops working at the end of the month is a support problem, and the only way to avoid it is to know the number before you hit it. Usage is also returned on every render as response headers, so a caller can track it without a second request.
The request
Sent to GET /v1/usage. Everything else on this page is what happens around it.
curl https://api.pdfpipe.xyz/v1/usage \
-H "Authorization: Bearer $PDFPIPE_KEY"
# Every render also returns these headers:
# X-PDFPipe-Plan
# X-PDFPipe-Usage
# X-PDFPipe-LimitThe actual limits
Read from the implementation rather than remembered, so these are the numbers the API enforces rather than the ones a roadmap intends.
- Usage is counted per billing period rather than per calendar month, so the reset date follows the subscription rather than the first of the month.
- A failed render is refunded, so the counter reflects documents produced rather than requests attempted.
- Each item in a batch counts as one document.
- GET /v1/plans returns the plan ladder and their limits without needing a key of that plan.
What failure looks like
Exceeding the limit returns a quota error on the render rather than a warning in advance. Nothing pushes a notification at the ninety per cent mark, so if the limit matters to you, read the headers on renders you are already making and act on them rather than waiting to be told.
When this is the wrong tool
As a per-request check before every render. Reading usage from the headers of the render you just made costs nothing extra; a separate GET before each render doubles your request count to learn something the previous response already told you.
Frequently asked
Is usage and quota available on the free plan?
Yes. There is no plan gate on this one: it behaves the same on the free plan as on every paid plan, and the only limit that applies is the monthly document allowance.
Where do these numbers come from?
The running implementation. Every figure on this page, from payload ceilings to per-plan limits, is what the API enforces today rather than what a specification says it should. If one of them is wrong, the API is the thing to believe.
Related capabilities
Options that come up in the same request, and one from each of the other groups.
Render an HTML string to PDF over an API
Send a complete HTML document in the request body and get the PDF bytes back in the response.
Set the PDF page size in an API request
Six named paper sizes, passed in the request options, with A4 as the default when nothing is given.
Print background colours and images in a PDF
Controls whether background colours and images survive into the PDF. On by default here, which is the opposite of a browser's own default.
Render many PDFs in one API call
Up to several hundred documents in one request, each stored and returned as a link, with per-item success or failure rather than one all-or-nothing result.
Password protect a generated PDF
Encrypts the output so a reader is asked for a password before the document opens.
Everything the API does
The full list, grouped by which part of the request it belongs to.
API reference
The complete parameter documentation, including the parts with nothing interesting to say about them.
100 free documents a month, and a playground that runs a real render without a key.