# 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 /api/v1/billing/invoices/current ``` **Example** ```bash curl -H "Authorization: Bearer psk--" \ https://api.parasail.io/api/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 /api/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/api/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/api/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/api/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 /api/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/api/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 /api/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/api/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 (e.g., "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 (e.g., deployment name, GPU type) | | `presentation_group_values` | object | Display dimensions (e.g., 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 | --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.parasail.io/parasail-docs/billing/billing-api.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.