billing api.md

For the complete documentation index, see llms.txt. Markdown versions of documentation pages are available by appending .md to page URLs; this page is available as Markdown.

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

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-<accessKey>-<secretKey>" \
  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 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

# 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-<accessKey>-<secretKey>" \
  "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"

# 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-<accessKey>-<secretKey>" \
  "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

{
    "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=<cursor> to fetch the next page.

curl -H "Authorization: Bearer psk-<accessKey>-<secretKey>" \
  "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

# Get all finalized invoices for April 2026
curl -H "Authorization: Bearer psk-<accessKey>-<secretKey>" \
  "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-<accessKey>-<secretKey>" \
  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