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 /api/v1/billing/invoices/current

Example

curl -H "Authorization: Bearer psk-<accessKey>-<secretKey>" \
  https://api.parasail.io/api/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 /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

Example

# Get daily breakdowns for May 1, 2026
curl -H "Authorization: Bearer psk-<accessKey>-<secretKey>" \
  "https://api.parasail.io/api/v1/billing/invoices/breakdowns?starting_on=2026-05-01T00:00:00Z&ending_before=2026-05-02T00:00:00Z&window_size=day&status=DRAFT&skip_zero_qty_line_items=true"

# Get hourly breakdowns for May 1, 2026
curl -H "Authorization: Bearer psk-<accessKey>-<secretKey>" \
  "https://api.parasail.io/api/v1/billing/invoices/breakdowns?starting_on=2026-05-01T00:00:00Z&ending_before=2026-05-02T00:00:00Z&window_size=hour&status=DRAFT&skip_zero_qty_line_items=true"

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)",
                  "product_id": "cbb406bd-5beb-4b17-8c76-35051025e521",
                  "credit_type": {
                    "id": "2714e483-4ff1-48e4-9e25-ac732e8f24f2",
                    "name": "USD (cents)"
                  },
                  "quantity": 81.934034,
                  "total": 10.45,
                  "unit_price": 0.13,
                  "type": "usage",
                  "starting_at": "2026-05-01T00:00:00+00:00",
                  "ending_before": "2026-06-01T00:00:00+00:00",
                  "pricing_group_values": {
                    "DeploymentName": "parasail-corp-qwen3vl-8b"
                  },
                  "presentation_group_values": {
                    "ModelName": "qwen/qwen3-vl-8b-instruct"
                  }
                },
                {
                  "name": "Prepaid Commit applied",
                  "product_id": "cbb406bd-5beb-4b17-8c76-35051025e521",
                  "credit_type": {
                    "id": "2714e483-4ff1-48e4-9e25-ac732e8f24f2",
                    "name": "USD (cents)"
                  },
                  "total": -10.45,
                  "type": "applied_commit_or_credit",
                  "starting_at": "2026-05-01T00:00:00+00:00",
                  "ending_before": "2026-06-01T00:00:00+00:00"
                },
                {
                  "name": "Serverless Output (Per Million Tokens)",
                  "product_id": "18d9acf3-7f0d-4eca-ba00-7ea7aa7ea257",
                  "credit_type": {
                    "id": "2714e483-4ff1-48e4-9e25-ac732e8f24f2",
                    "name": "USD (cents)"
                  },
                  "quantity": 1.983286,
                  "total": 1.18,
                  "unit_price": 0.60,
                  "type": "usage",
                  "starting_at": "2026-05-01T00:00:00+00:00",
                  "ending_before": "2026-06-01T00:00:00+00:00",
                  "pricing_group_values": {
                    "DeploymentName": "parasail-corp-qwen3vl-8b"
                  },
                  "presentation_group_values": {
                    "ModelName": "qwen/qwen3-vl-8b-instruct"
                  }
                },
                {
                  "name": "Prepaid Commit applied",
                  "product_id": "18d9acf3-7f0d-4eca-ba00-7ea7aa7ea257",
                  "credit_type": {
                    "id": "2714e483-4ff1-48e4-9e25-ac732e8f24f2",
                    "name": "USD (cents)"
                  },
                  "total": -1.18,
                  "type": "applied_commit_or_credit",
                  "starting_at": "2026-05-01T00:00:00+00:00",
                  "ending_before": "2026-06-01T00:00:00+00:00"
                }
              ],
        }
    ]
}

For large ranges, the API automatically follows Metronome pagination and returns the combined breakdowns in one response. Metronome limits daily breakdown pages to up to 35 days and hourly breakdown pages to up to 24 hours.

---

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

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

{
    "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

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