comecerodocs
Usage billing runs

List an agreement's billing runs

GET
/usage/agreements/{agreement_id}/runs

Newest period first. For the next page, set before to the oldest period_start you got. 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

agreement_id*string

The agreement id.

Query Parameters

before?string

A date: only runs whose period_start is before it.

limit?integer

1 to 100, default 25.

Response Body

Success.

application/json
  1. response
data?array<>

The list.

has_more?boolean

true when there is another page.

Example Request
curl -X GET 'https://api.comecero.com/api/v1/usage/agreements/string/runs'
Example Response
{  "data": [    {      "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    }  ],  "has_more": false}

Overview

Previous Page

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`).