# 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-- ``` 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** ``` curl -H "Authorization: Bearer psk--" \ https://api.parasail.io/v1/billing/invoices/current ``` **Response** ``` { "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 | Max number of breakdown windows returned. Defaults to the maximum for the selected `window_size`. | | `next_page` | No | Cursor that indicates where the next page of results should start. | **Examples** ``` # 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" ``` **Response** ``` { "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" } ``` ### 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** ``` # 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** ``` { "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** ``` 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](https://docs.parasail.io/parasail-docs/billing/pricing) - [Limits and quotas](https://docs.parasail.io/parasail-docs/operate-in-production/limits-and-quotas) - [Authentication](https://docs.parasail.io/parasail-docs/api-reference/authentication)