coss.comdocs
GitHub

List usage

GET
/v1/billing/usage

Billable usage over a range (the current billing month by default), per meter, dimension and bucket (hour, day or month, UTC), oldest first; with group_by=environment, per environment too. Only live environments are billed, so only they appear. Usage counts when it becomes billable (an email when the provider accepts it) and is kept for 400 days.

Authorization

bearerAuth
headerAuthorizationBearer <token>

A secret API key from the dashboard: coss_live_… for production environments, coss_test_… for sandbox environments.

Query Parameters

from?string

Start (inclusive). Defaults to the start of the current billing month.

Formatdate-time
to?string

End (exclusive). Defaults to now. At most 400 days after from (7 by hour).

Formatdate-time
granularity?string

Bucket size (UTC). Defaults to day.

Value in"hour""day""month"
group_by?"environment"

Split each bucket per environment.

Value in"environment"
meter?string

Only this meter.

Value in"email.recipients""sms.segments""video.participant_minutes""scheduling.bookings"

Header Parameters

Coss-Version?"2026-10-10"

The API version (a date) to use for this request. Defaults to your organization's version, pinned to the latest one when it first used the API and upgraded from the dashboard. The SDK always sends the version it was built for.

Value in"2026-10-10"

Response Body

Usage, oldest first.

application/json
  1. response
object*"list"
Value in"list"
data*array<>
has_more*false
Value infalse
import { Coss } from "coss";const coss = new Coss({  apiKey: process.env.COSS_API_KEY,  baseUrl: "https://api.coss.com",});const { data, error } = await coss.billing.usage();
{  "object": "list",  "data": [    {      "object": "usage",      "meter": "email.recipients",      "dimension": null,      "environment_id": null,      "start": "2026-10-12T00:00:00.000Z",      "end": "2026-10-13T00:00:00.000Z",      "quantity": 4200    }  ],  "has_more": false}