API Reference
Monitor usage and operational health from /api/usage
This reference documents the usage monitoring surface for account routes: usage summary, usage export, request logs, and batch metrics. Use these routes to track monthly quota posture, investigate failures, and measure batch reliability.
The machine readable contract for these customer monitoring routes lives in /docs/account. This page remains the broader reference for range semantics, CSV behavior, and operational interpretation.
Auth and range model
Auth model
Authorization: Bearer ACCESS_TOKEN
All routes on this page are user-account routes and require bearer auth.
Window selection
period or from+to
Use period for relative lookback, or pass from and to together.
Future date guard
range validation
Explicit from/to values cannot be in the future.
Usage summary
GET /user/usage returns totals, reliability counters, limits, and optional key breakdowns.
Usage export
GET /user/usage/export streams CSV rows for a required owned API key.
Operational visibility
GET /user/request-logs and /user/batches/metrics support incident review and trend tracking.
Usage summary and export
Review quota state and export request-level history
GET /user/usage
Returns usage aggregates and current plan limit context.
period
optional query, 1-365 or 1d-365d
Relative lookback. Defaults to 30d when no explicit range is provided.
from
optional ISO date or datetime
Range start. Must be sent with to and cannot be in the future. Date-only values use UTC calendar-day boundaries.
to
optional ISO date or datetime
Range end. Must be sent with from. Today as a date-only value is capped at server time; explicit timestamps up to 2 seconds ahead are clamped to server time, while larger future values are rejected.
apiKeyId
optional UUID
Filters usage to one owned API key. Omit for account-wide summary.
includeBreakdown
optional boolean string
When true and apiKeyId is omitted, includes keyBreakdown[].
Response
plan
string
Resolved account plan used to compute limits in this response.
totalRequests
number
Total request count in the selected window.
totalSize
number
Total output size across the selected window.
avgProcessingTime
number
Average processing time in milliseconds.
usageByDay
object<date, number>
Daily volume for all requests in range.
successCount
number
Successful request count in range.
failedCount
number
Failed request count in range.
successByDay
object<date, number>
Daily success totals.
failureByDay
object<date, number>
Daily failure totals.
errorsByCategory
object<string, number>
Failure category counts for troubleshooting.
from
ISO timestamp
Effective range start used by aggregation.
to
ISO timestamp
Effective range end used by aggregation.
periodDays
number
Final period length after range normalization.
limit
number
Effective monthly quota, including purchased overage units.
remaining
number
Remaining monthly requests in the current quota cycle.
resetDate
YYYY-MM-DD
Date when the monthly quota cycle resets.
requestsPerMinute
number
Plan request-rate limit.
concurrentRenders
number
Plan concurrent render limit.
maxInputSizeBytes
number
Maximum input payload size for plan.
maxOutputSizeBytes
number
Maximum output size for plan.
maxTimeoutMs
number
Maximum execution timeout for plan.
purchasedOveragePdfs
number
Extra purchased monthly units currently applied.
keyBreakdown[]
optional array
Per-key totals and failure counts when includeBreakdown=true.
GET /user/usage/export
Streams a CSV export for one owned key in the selected time range.
apiKeyId
required UUID
Must be an API key owned by the authenticated account.
period
optional query, 1-365 or 1d-365d
Relative lookback window when no explicit range is provided.
from
optional ISO date or datetime
Range start. Must be sent with to and cannot be in the future. Date-only values use UTC calendar-day boundaries.
to
optional ISO date or datetime
Range end. Must be sent with from. Today as a date-only value is capped at server time; explicit timestamps up to 2 seconds ahead are clamped to server time, while larger future values are rejected.
Response
Content-Type
text/csv; charset=utf-8
Route returns CSV, not JSON.
Content-Disposition
attachment; filename=...
Filename is usage-{safePrefix}-{YYYY-MM-DD}.csv.
CSV columns
header row
timestamp, apiKeyId, endpoint, inputMode, outputMode, format, requestSize, pdfSize, processingTimeMs, success, errorCategory, errorMessage.
Request logs
Audit recent request outcomes and filter incident windows
GET/user/request-logs
Request
period
optional query, default 30d
Lookback window, capped by plan retention (free=7, starter=30, professional=90, business=365 days).
limit
optional integer, 1-500
Record count per page. Defaults to 25.
offset
optional integer, 0+
Pagination offset for deeper history scans.
apiKeyId
optional UUID
Filter to one owned key. Unknown or non-owned keys return 404.
search
optional string
Case-insensitive search over key prefix, endpoint, IP, status text, and error reason.
status
optional enum: success | failed
Filters to one terminal request status.
endpoint
optional string
Filter to one endpoint path such as /v1/pdf.
sort
optional enum
Sort by created time, key prefix, endpoint, success status, or error reason.
revealIp
optional boolean
When true, returns full IPs only if the account can reveal IP addresses for its plan.
Response
total
number
Total records matching the applied filters.
limit
number
Applied page size.
offset
number
Applied offset.
endpointOptions[]
array<string>
Distinct endpoints for filter UIs in the current filtered range.
summary.successCount
number
Successful request count for current filters.
summary.failedCount
number
Failed request count for current filters.
logs[]
array<object>
Each item includes id, apiKeyId, apiKeyPrefix, endpoint, ipAddress, status, errorReason, and createdAt.
canRevealIp
boolean
Indicates whether the account plan can receive unmasked IP values.
Batch metrics
Track queue depth, completion quality, and webhook delivery health
GET/user/batches/metrics
Request
period
optional query, 1-365 or 1d-365d
Lookback window for queue, item, and webhook metric aggregation.
Response
queueDepth
number
Current queued batch count (same value as queuedBatches).
activeBatches
number
Batches currently queued or processing.
queuedBatches
number
Queued batch count in current snapshot.
processingBatches
number
Processing batch count in current snapshot.
completionRatePercent
number
Percent of terminal batches that completed with zero failed items.
itemSuccessRatePercent
number
Percent of completed items across recent eligible batch items.
itemEligibleCount
number
Count of batch items included in item level calculations.
averageItemsPerBatch
number
Average batch size for jobs in the lookback window.
averageBatchProcessingTimeMs
number
Average terminal batch processing duration in milliseconds.
webhookSuccessRatePercent
number
Percent of terminal webhook-eligible batches with a delivered webhook notification.
webhookEligibleCount
number
Terminal batches in range that declared a webhook URL.
webhookDeliveredCount
number
Webhook-eligible terminal batches with recorded delivery.
commonFailureReasons[]
array<object>
Top failed item error codes with counts, sorted descending.
lookbackDays
number
Effective lookback length after period parsing.
generatedAt
ISO timestamp
Server timestamp when metrics were produced.
Next steps
Use these pages with /api/usage to complete monitoring, limits, and recovery workflows.