comecerodocs
Usage billing runs

Get a billing run

GET
/usage/runs/{billing_run_id}

One billed period, with its invoice lines. URL-encode the id. Secret and trusted tokens may call it; a limited token may not (403).

Authorization

headerAuthorizationBearer <token>

A secret, trusted or limited token. See Authentication.

Path Parameters

billing_run_id*string

The billing run id.

Query Parameters

billing_region?string

The agreement's region. Defaults to us.

Response Body

Success.

application/json
  1. response

One billed period of one agreement. See https://docs.comecero.com/docs/usage-billing/how-usage-is-billed#billing-runs

object?string

Always billing_run.

billing_run_id?string

billing_run:{agreement_id}:{period_start}, sometimes with a suffix. URL-encode it in paths.

billing_agreement_id?string

The agreement.

period_start?string

Start of the period billed.

Formatdate-time
period_end?string

End of the period billed.

Formatdate-time
kind?string

final_late is the last late-usage pass after an agreement ends.

Value in"period""final_late"
status?string

The run's state.

Value in"pending""completed""failed"
invoice_id?string

The invoice the usage is on: usually the subscription's renewal invoice, otherwise a separate usage invoice. Empty when nothing was charged or the amount waits for the minimum.

carried_forward?boolean

true when the amount was under the minimum and waits for the next invoice.

prepared_lines?array<>

The invoice lines.

failure_code?|

Set when failed. You can fix and retry, from the dashboard: currency_mismatch, missing_metric_or_plan, hard_limit_exceeded, subscription_not_found, invalid_customer_id, missing_credit_entitlement, funding_not_a_credit, credit_region_mismatch. needs_review (over 5,000 USD, or over 10 times the last invoice) is approved by Comecero.

failure_message?|

Set when failed.

billing_region?string

Billing region. Defaults to us.

Value in"us""uk""eu"
test?boolean

Test or live.

Example Request
curl -X GET 'https://api.comecero.com/api/v1/usage/runs/string'
Example Response
{  "object": "billing_run",  "billing_run_id": "billing_run:agr_cust_8412:2026-11-01T00:00:00Z",  "billing_agreement_id": "agr_cust_8412",  "period_start": "2026-11-01T00:00:00Z",  "period_end": "2026-12-01T00:00:00Z",  "kind": "period",  "status": "completed",  "invoice_id": "IN0123456789",  "carried_forward": false,  "prepared_lines": [    {      "kind": "usage",      "name": "AI tokens (token): 500000 used, 1 Nov 2026 00:00 to 1 Dec 2026 00:00 UTC",      "quantity": 500000,      "rated_amount": 8,      "credit_debit": 5,      "amount": 3    }  ],  "failure_code": null,  "failure_message": null,  "billing_region": "us",  "test": false}

List bills that need attention GET

Billing runs that are stuck, up to 100: held for Comecero's review (`needs_review`), failed (`failed`), or waiting for prepaid credit (`waiting_for_credit`). Failures you can fix are retried from the dashboard, under Usage Billing. Secret and trusted tokens may call it; a limited token may not (`403`).

Overview

Next Page