> For the complete documentation index, see [llms.txt](https://docs.parasail.io/parasail-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.parasail.io/parasail-docs/api-reference/billing-api.md). # 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-- ``` You can generate an API key from the Parasail dashboard under **Settings > API Keys**. ## Endpoints ### 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 /v1/billing/invoices/current ``` **Example** ```bash curl -H "Authorization: Bearer psk--" \ https://api.parasail.io/v1/billing/invoices/current ``` **Response** ```json { "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. ``` GET /v1/billing/invoices/breakdowns ``` **Query Parameters** | Parameter | Required | Description | | -------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `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** ```bash # Get daily breakdowns for May 1, 2026 at 12:00 AM UTC to May 2, 2026 at 12:00 AM UTC curl -H "Authorization: Bearer psk--" \ "https://api.parasail.io/v1/billing/invoices/breakdowns?limit=35&starting_on=2026-05-01T00:00:00Z&ending_before=2026-05-02T00:00:00Z&window_size=day" ``` ```bash # Get hourly breakdowns for May 1, 2026 at 12:00 AM UTC to May 2, 2026 at 12:00 AM UTC curl -H "Authorization: Bearer psk--" \ "https://api.parasail.io/v1/billing/invoices/breakdowns?limit=24&starting_on=2026-05-01T00:00:00Z&ending_before=2026-05-02T00:00:00Z&window_size=hour" ``` **Response** ```json { "breakdowns": [ { "id": "3fa1c306-5258-5ac0-8905-8b90c6a6396f", "status": "DRAFT", "type": "USAGE", "total": 18.42, "subtotal": 18.42, "start_timestamp": "2026-05-01T00:00:00+00:00", "end_timestamp": "2026-06-01T00:00:00+00:00", "breakdown_start_timestamp": "2026-05-01T00:00:00+00:00", "breakdown_end_timestamp": "2026-05-02T00:00:00+00:00", "line_items": [ { "name": "Serverless Input (Per Million Tokens)", "quantity": 1.49, "total": 0.75, "unit_price": 50.0, "type": "usage", "product_id": "5c1f40cd-9ff8-4e90-ae53-5f81b0e9d1e8", "pricing_group_values": { "DeploymentName": "my-deployment" }, "presentation_group_values": { "ModelName": "meta-llama/Llama-3.1-8B-Instruct" } }, { "name": "Dedicated GPU Hours", "quantity": 0.11, "total": 17.60, "unit_price": 160.0, "type": "usage", "pricing_group_values": { "gpuType": "A10080GB" } } ] } ], "next_page": "7b226e6578745f72616e67655f637572736f72223a7b2273746172745f74696d657374616d70223a22323032362d30352d32315430303a30303a30302e3030305a227d7d" } ``` 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=` to fetch the next page. ```bash curl -H "Authorization: Bearer psk--" \ "https://api.parasail.io/v1/billing/invoices/breakdowns?starting_on=2026-05-01T00:00:00Z&ending_before=2026-06-01T00:00:00Z&window_size=day&limit=35&next_page=7b226e6578745f72616e67655f637572736f72223a7b2273746172745f74696d657374616d70223a22323032362d30352d32315430303a30303a30302e3030305a227d7d" ``` 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. ``` GET /v1/billing/invoices ``` **Query Parameters** | Parameter | Required | Description | | --------------- | -------- | ------------------------------------------------------------------------------------------- | | `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** ```bash # Get all finalized invoices for April 2026 curl -H "Authorization: Bearer psk--" \ "https://api.parasail.io/v1/billing/invoices?status=FINALIZED&starting_on=2026-04-01T00:00:00Z&ending_before=2026-05-01T00:00:00Z" ``` **Response** ```json { "invoices": [ { "id": "3fa1c306-5258-5ac0-8905-8b90c6a6396f", "status": "FINALIZED", "type": "USAGE", "total": 1240.50, "start_timestamp": "2026-04-01T00:00:00+00:00", "end_timestamp": "2026-05-01T00:00:00+00:00", "line_items": [ ... ], "issued_at": "2026-05-02T00:00:00+00:00", "billable_status": "billable" } ] } ``` *** ### Get Invoice by ID Returns a specific invoice by its unique identifier. ``` GET /v1/billing/invoices/{invoice_id} ``` **Path Parameters** | Parameter | Required | Description | | ------------ | -------- | ------------------------------------ | | `invoice_id` | Yes | The unique identifier of the invoice | **Example** ```bash curl -H "Authorization: Bearer psk--" \ https://api.parasail.io/v1/billing/invoices/3fa1c306-5258-5ac0-8905-8b90c6a6396f ``` *** ## Invoice Object | Field | Type | Description | | --------------------------- | ------ | -------------------------------------------------------------------------------------------- | | `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 | Field | Type | Description | | --------------------------- | ------ | -------------------------------------------------------------------------------------- | | `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 | Status Code | Description | | ----------- | ---------------------------------------------------------------- | | `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 * [Pricing](/parasail-docs/billing/pricing.md) * [Limits and quotas](/parasail-docs/operate-in-production/limits-and-quotas.md) * [Authentication](/parasail-docs/api-reference/authentication.md)