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

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

• Pricing

• Limits and quotas

• Authentication