Get Credit Usage

Get your current billing cycle credit usage at a glance -- plan info, credits used, credits remaining, and a breakdown by entity type.

Request example

12curl https://api.v2.dealmachine.com/v1/usage \
  -H "Authorization: Bearer dm_sk_live_xxx"

Response example

123456789101112131415161718192021222324252627282930313233{
  "plan": {
    "name": "Pro",
    "is_paid": true
  },
  "billing_cycle": {
    "start": "2025-06-01T00:00:00.000Z",
    "end": "2025-07-01T00:00:00.000Z"
  },
  "credits": {
    "included": 20000,
    "total_cap": 21000,
    "total_available": 19477,
    "base_included": 20000,
    "monthly_credit_grant_cap": 0,
    "monthly_included": 20000,
    "additional_credit_balance": 1000,
    "used": 1523,
    "remaining": 19477,
    "monthly_remaining": 18477,
    "additional_remaining": 1000,
    "overage": 0,
    "pools": {
      "monthly": { "included": 20000, "used": 1523, "remaining": 18477 },
      "additional": { "available": 1000, "used": 0, "remaining": 1000 }
    },
    "breakdown": {
      "properties": 847,
      "people": 676,
      "companies": 0
    }
  }
}

Response Fields

`plan`

Field	Type	Description
`name`	string	Plan name (e.g. `No plan`, `Basic`, `Pro`)
`is_paid`	boolean	Whether this is a paid plan

`billing_cycle`

Field	Type	Description
`start`	string	ISO 8601 start of the current billing cycle
`end`	string	ISO 8601 end of the current billing cycle (credits reset at this time)

`credits`

Field	Type	Description
`included`	number	Monthly credits included in the current cycle
`total_cap`	number	Total current-cycle capacity, including additional credits
`total_available`	number	Live spendable balance remaining across all pools
`base_included`	number	Plan credits before temporary grants
`monthly_credit_grant_cap`	number	Temporary credits granted for this cycle
`monthly_included`	number	Plan credits plus temporary monthly grants
`additional_credit_balance`	number	Current durable additional-credit wallet balance
`used`	number	Credits consumed so far this billing cycle
`remaining`	number	Same live spendable balance as `total_available`
`monthly_remaining`	number	Monthly credits remaining
`additional_remaining`	number	Additional credits remaining after pending reservations
`overage`	number	Historical usage recorded beyond total capacity

`credits.breakdown`

Field	Type	Description
`properties`	number	Unique properties accessed this billing cycle
`people`	number	Unique people accessed this billing cycle
`companies`	number	Unique companies accessed this billing cycle

Credits are deduplicated within your billing period. Accessing the same property or contact multiple times in one billing cycle only counts once.

total_available and remaining are live balances. They reconcile the shared Redis reservation counter with the durable credit ledger. total_cap is the allowance; do not treat it as the remaining balance.

Call this endpoint before large batch operations to check your remaining credits and avoid partial results or credit-limit errors.