Billing API
Programmatically retrieve invoices, real-time month-to-date spend, and hourly or daily usage breakdowns with the Parasail Billing API.
The Parasail Billing API allows you to programmatically access your invoices, including real-time month-to-date spend and hourly or daily usage breakdowns for your current billing period.
Authentication
All billing endpoints require authentication using your Parasail API key in the Authorization header:
Authorization: Bearer psk-<accessKey>-<secretKey>You can generate an API key from the Parasail dashboard under Settings > API Keys.
Endpoints
Billing endpoints live on the Parasail control-plane base URL https://api.parasail.io/api/v1, not the OpenAI-compatible inference base https://api.parasail.io/v1. Calling https://api.parasail.io/v1/billing/... returns a 404.
Get Current Invoice
Returns the active draft invoice for your current billing period. This invoice is continuously updated in real time as usage is reported, giving you up-to-date visibility into your spend.
GET /api/v1/billing/invoices/currentExample
curl -H "Authorization: Bearer psk-<accessKey>-<secretKey>" \
https://api.parasail.io/api/v1/billing/invoices/currentResponse
{
"id": "3fa1c306-5258-5ac0-8905-8b90c6a6396f",
"status": "DRAFT",
"type": "USAGE",
"total": 52.89,
"start_timestamp": "2026-04-01T00:00:00+00:00",
"end_timestamp": "2026-05-01T00:00:00+00:00",
"line_items": [
{
"name": "Serverless Input (Per Million Tokens)",
"quantity": 1.49,
"total": 0.75,
"unit_price": 50.0,
"type": "usage",
"starting_at": "2026-04-01T00:00:00+00:00",
"ending_before": "2026-05-01T00:00:00+00:00",
"pricing_group_values": {
"DeploymentName": "my-deployment"
},
"presentation_group_values": {
"ModelName": "meta-llama/Llama-3.1-8B-Instruct"
}
},
{
"name": "Dedicated GPU Hours",
"quantity": 0.33,
"total": 52.80,
"unit_price": 160.0,
"type": "usage",
"starting_at": "2026-04-01T00:00:00+00:00",
"ending_before": "2026-05-01T00:00:00+00:00",
"pricing_group_values": {
"gpuType": "A10080GB"
}
}
],
"issued_at": "2026-05-02T00:00:00+00:00",
"billable_status": "billable"
}Returns 404 if no active draft invoice exists for the account.
List Invoice Breakdowns
Returns granular invoice breakdowns for a time range. Use this endpoint to inspect hourly or daily usage and spend within the current or historical billing period.
Query Parameters
starting_on
Yes
Only return breakdown windows starting on or after this timestamp (RFC 3339 format)
ending_before
Yes
Only return breakdown windows ending on or before this timestamp (RFC 3339 format)
window_size
No
Breakdown granularity: hour or day. Defaults to day
status
No
Filter by invoice status: DRAFT, FINALIZED, or VOID
skip_zero_qty_line_items
No
Set to true to omit zero-quantity line items
limit
No
We strongly recommend utilizing the limit parameter in order to avoid excessively large response payloads. Max number of breakdown windows returned. Daily breakdowns can return up to 35 days per response. Hourly breakdowns can return up to 24 hours per response. If omitted, defaults to the maximum for the selected window_size. Also not, the limit parameter specifies the number of units of the window_size type (ex: Day) for which results will be returned. It is possible the max number of items returned in a single pagination request could differ from the limit value
next_page
No
Cursor that indicates where the next page of results should start. Use the next_page value returned by the previous response
Examples
Response
For large ranges, the API returns one page at a time. If next_page is not null, call the endpoint again with the same filters and append next_page=<cursor> to fetch the next page.
Metronome limits daily breakdown pages to up to 35 days and hourly breakdown pages to up to 24 hours. Parasail clamps larger limit values to those maximums before forwarding requests to Metronome.
List Invoices
Returns all invoices matching the specified filters. Use status=DRAFT to get current billing period invoices, or status=FINALIZED to retrieve historical invoices.
Query Parameters
status
No
Filter by invoice status: DRAFT, FINALIZED, or VOID
starting_on
No
Only return invoices with a billing period starting on or after this date (RFC 3339 format)
ending_before
No
Only return invoices with a billing period ending before this date (RFC 3339 format)
Example
Response
Get Invoice by ID
Returns a specific invoice by its unique identifier.
Path Parameters
invoice_id
Yes
The unique identifier of the invoice
Example
Invoice Object
id
string
Unique invoice identifier
status
string
DRAFT (current period, updating in real time), FINALIZED (closed), or VOID (cancelled)
type
string
Invoice type: USAGE, SCHEDULED, or USAGE_CONSOLIDATED
total
number
Total invoice amount in USD
subtotal
number
Subtotal invoice amount in USD
start_timestamp
string
Start of the billing period (RFC 3339)
end_timestamp
string
End of the billing period (RFC 3339)
breakdown_start_timestamp
string
Start of the breakdown window (only returned by /invoices/breakdowns)
breakdown_end_timestamp
string
End of the breakdown window (only returned by /invoices/breakdowns)
line_items
array
Itemized charges (see below)
issued_at
string
When the invoice was or will be issued (RFC 3339)
billable_status
string
billable or unbillable
Line Item Object
name
string
Description of the charge (for example, "Serverless Input (Per Million Tokens)")
quantity
number
Amount consumed
total
number
Line item cost in USD
unit_price
number
Price per unit in USD
type
string
usage, subscription, scheduled, commit_purchase, or applied_commit_or_credit
starting_at
string
Start of the line item period (RFC 3339)
ending_before
string
End of the line item period (RFC 3339)
pricing_group_values
object
Pricing dimensions (for example, deployment name, GPU type)
presentation_group_values
object
Display dimensions (for example, model name)
Error Responses
401
Missing or invalid API key
403
Account not found or billing not configured
404
Invoice not found (for /invoices/current and /invoices/{id})
502
Upstream billing service error
Next steps
Last updated