Usage and statements

Get a month of usage

GET/api/v1/usage

The usage of the key's organization in a billing month, in the key's mode: for each product the billable transactions and those not billed (with the reason for each kind), the rate and the amount; for eligibility each tier's checks and price; the fees, the monthly minimum, and the amount due (the greater of the fees and the minimum, plus adjustments). A month still open is computed from the usage records as of now; a month that has been closed is read from its statement, which never changes. Months are calendar months in America/Denver for every partner. The default is the current month. An organization that is not live yet owes nothing (billing is pre_production, live is false); A test key sees test activity only: it is never priced, and a test key sees no statements.

Needs a key with read permission.

Request

Query parameters

Query parameters
Name	Type	Required	Description
month	string	optional	A billing month, YYYY-MM, not after the current one. Default: the current billing month.Matches `^[1-9][0-9]{3}-(0[1-9]\|1[0-2])$`.

Response

The month's usage. Status 200.

Response fields
Name	Type	Description
object	string	Always `usage`.
statement_id	string or null	The statement of the month, once it is closed.
month	string	The billing month, YYYY-MM.Matches `^\d{4}-\d{2}$`.
time_zone	string	The time zone months are counted in.
mode	string	One of: `test`, `live`.
live	boolean	true when this month is billed: live mode, in a month the organization was live. false for test activity and for a pre-production organization.
billing	string	billed; pre_production (live usage of an organization not yet live: not billed); test_activity (test mode: never billed).One of: `billed`, `pre_production`, `test_activity`.
note	value	In words, why the month is not billed; null when it is billed.
state	string	open: computed from the usage records as of now; issued: read from the stored statement, which never changes.One of: `open`, `issued`.
products	array of object
products[].product	string	One of: `eligibility`, `claims`, `attachments`, `eras`.
products[].billable	integer	Billable transactions of the month.At least -9007199254740991.
products[].not_billed	object	Transactions of the month that are not billed, with the reason for each kind.
products[].not_billed.total	integer	At least -9007199254740991.
products[].not_billed.reasons	array of object
products[].not_billed.reasons[].reason	string
products[].not_billed.reasons[].label	string
products[].not_billed.reasons[].count	integer	At least -9007199254740991.
products[].rate	string	The rate in words, from the price table in force.
products[].amount	string	The product's fees for the month; 0.00 when the month is not billed.Matches `^\d+\.\d{2}$`.
products[].tiers	array of object or null	Eligibility only, when the month is billed: the checks and amount of each tier.
products[].tiers[].from	integer	The first check of the month this tier covers.At least -9007199254740991.
products[].tiers[].to	integer or null	The last check of the month this tier covers; null for the last tier.At least -9007199254740991.
products[].tiers[].rate	string	The price of one check in this tier, in dollars.Matches `^\d+\.\d{2,6}$`.
products[].tiers[].checks	integer	How many of the month's billable checks fell in this tier.At least -9007199254740991.
products[].tiers[].amount	string	Matches `^\d+\.\d{2}$`.
adjustments	array of object	Usage of an earlier, closed month that arrived after its statement was issued, added to this month.
adjustments[].usage_month	string	Matches `^\d{4}-\d{2}$`.
adjustments[].description	string
adjustments[].products	array of object
adjustments[].products[].product	string	One of: `eligibility`, `claims`, `attachments`, `eras`.
adjustments[].products[].billable	integer	At least -9007199254740991.
adjustments[].products[].not_billed	object
adjustments[].products[].not_billed.total	integer	At least -9007199254740991.
adjustments[].products[].not_billed.reasons	array of object
adjustments[].products[].not_billed.reasons[].reason	string
adjustments[].products[].not_billed.reasons[].label	string
adjustments[].products[].not_billed.reasons[].count	integer	At least -9007199254740991.
adjustments[].amount	string	Matches `^\d+\.\d{2}$`.
fees	string	The sum of the products' fees.Matches `^\d+\.\d{2}$`.
adjustments_amount	string	Matches `^\d+\.\d{2}$`.
minimum	object or null	The monthly minimum that applies; null when the month is not billed.
minimum.amount	string	Matches `^\d+\.\d{2}$`.
minimum.introductory	boolean	true for the lower minimum of an organization's first live months.
minimum_applied	boolean	true when the minimum, not the fees, set the amount due.
amount_due	string	The greater of the fees and the minimum, plus adjustments; 0.00 when the month is not billed.Matches `^\d+\.\d{2}$`.

Errors

Errors
HTTP status	Code	What it means
401	UNAUTHORIZED	A valid API key is required. Send it as "Authorization: Bearer <key>".
403	PERMISSION_DENIED	This API key is not allowed to do that.
422	INVALID_REQUEST	The request is not valid.
504	TIMEOUT	The request took too long to finish. It may still have taken effect: look it up before sending it again with a new Idempotency-Key. What it made is found with GET /api/v1/eligibility?request_id=<this request_id>, and the same filter on /api/v1/claims and /api/v1/attachments (a key with read permission).
500	INTERNAL	Something went wrong on our side. Quote the request ID if you contact us.

Example

Example request

Shell

curl "https://sandbox.myclaimhouse.com/api/v1/usage?month=2026-09" \
  -H "Authorization: Bearer $CLAIMHOUSE_KEY"

Example response: 200

JSON

{
  "object": "usage",
  "statement_id": null,
  "month": "2026-09",
  "time_zone": "America/Denver",
  "mode": "live",
  "live": true,
  "billing": "billed",
  "note": null,
  "state": "open",
  "products": [
    {
      "product": "eligibility",
      "billable": 4000,
      "not_billed": {
        "total": 118,
        "reasons": [
          {
            "reason": "cache_hit",
            "label": "answer reused from a recent check",
            "count": 118
          }
        ]
      },
      "rate": "$0.30 for checks 1-250, $0.15 for 251-3,500, $0.10 for 3,501-10,000, $0.08 after",
      "amount": "612.50",
      "tiers": [
        {
          "from": 1,
          "to": 250,
          "rate": "0.30",
          "checks": 250,
          "amount": "75.00"
        },
        {
          "from": 251,
          "to": 3500,
          "rate": "0.15",
          "checks": 3250,
          "amount": "487.50"
        },
        {
          "from": 3501,
          "to": 10000,
          "rate": "0.10",
          "checks": 500,
          "amount": "50.00"
        },
        {
          "from": 10001,
          "to": null,
          "rate": "0.08",
          "checks": 0,
          "amount": "0.00"
        }
      ]
    },
    {
      "product": "claims",
      "billable": 1240,
      "not_billed": {
        "total": 0,
        "reasons": []
      },
      "rate": "$0.20 per claim",
      "amount": "248.00",
      "tiers": null
    },
    {
      "product": "attachments",
      "billable": 410,
      "not_billed": {
        "total": 0,
        "reasons": []
      },
      "rate": "$0.30 per attachment",
      "amount": "123.00",
      "tiers": null
    },
    {
      "product": "eras",
      "billable": 900,
      "not_billed": {
        "total": 3,
        "reasons": [
          {
            "reason": "estimate_only",
            "label": "estimate only",
            "count": 3
          }
        ]
      },
      "rate": "$0.05 per ERA",
      "amount": "45.00",
      "tiers": null
    }
  ],
  "adjustments": [],
  "fees": "1028.50",
  "adjustments_amount": "0.00",
  "minimum": {
    "amount": "500.00",
    "introductory": true
  },
  "minimum_applied": false,
  "amount_due": "1028.50"
}