---
title: "Usage and cost for a calendar month"
method: GET
path: "/v1/usage"
tags: ["Accounts"]
---

# Usage and cost for a calendar month

`GET /v1/usage`

## Request

- Base URL: `https://api.cadencercs.com`
- URL: `https://api.cadencercs.com/v1/usage`
- Auth: HTTP bearer

Sandbox conversations are counted and never billed.

## Query parameters

- `monthsAgo` integer

## Response `200`

Usage.

- Usage
  - `periodStart` string, required
  - `periodEnd` string, required
  - `lines` object[], required
    - `channel` 'rcs' | 'sms', required
    - `market` string, required: How **carriers** bill in the destination geography — `perMessage` or `session`. A property of the country, not of this line: a US RCS line reads `perMessage` while it is charged a flat rate per conversation, because the US is a per-message market and RCS is priced per conversation regardless. Reconcile against `billedPer`, not this.
    - `billedPer` 'conversation' | 'message', required: How this line was actually charged. RCS is per conversation everywhere; SMS is per message everywhere, because no carrier sells an SMS session.
    - `conversations` number, required
    - `unitPriceCents` number, nullable: Per-conversation list price, or null if unpriceable.
    - `priceCents` number, required
  - `sandboxConversations` number: Never billed.
  - `totalConversations` number
  - `totalPriceCents` number, required
  - `unpricedConversations` number: Live conversations with no list price — billed as zero, and worth knowing about.
  - `note` string

## Other responses

- `401`: Not signed in, and no account-linked API key was sent.
- `500`: Unexpected server error. The body is always JSON.

---

[API](https://skmtc.dev/cadencercs/apis/cadence-api.md) · [All operations](https://skmtc.dev/cadencercs/apis/cadence-api/llms.txt) · [OpenAPI document](https://skmtc.dev/cadencercs/apis/cadence-api/revisions/9438443c2081?raw)