Skip to main content
POST
/
v1
/
usage
/
cost
curl --request POST \
  --url https://api.monk.com/v1/usage/cost \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "startDate": "2026-03-01T00:00:00Z",
  "endDate": "2026-03-31T23:59:59Z",
  "customerId": "550e8400-e29b-41d4-a716-446655440000",
  "eventNames": [
    "token_used"
  ],
  "propertyFilters": [
    {
      "key": "sub_org_id",
      "value": "org_xyz"
    }
  ]
}
'
{
  "totalAmount": 12.5,
  "currency": "USD",
  "unit": "currency",
  "startDate": "2026-03-01T00:00:00.000Z",
  "endDate": "2026-03-31T23:59:59.000Z",
  "queriedAt": "2026-03-30T12:00:00.000Z"
}

Documentation Index

Fetch the complete documentation index at: https://docs.monk.com/llms.txt

Use this file to discover all available pages before exploring further.

Authorizations

​
Authorization
string
header
required

API key passed as Bearer token. Requires usage:read scope.

Body

application/json
​
startDate
string<date-time>

Start of the date range (inclusive). ISO 8601 format. Required unless contractId is provided (defaults to contract effective date).

​
endDate
string<date-time>

End of the date range (exclusive). ISO 8601 format. Required unless contractId is provided (defaults to contract termination date, or today for rolling contracts).

​
customerId
string<uuid>

Internal customer UUID. Provide this, externalCustomerId, or contractId.

​
externalCustomerId
string

Your external customer reference. Provide this, customerId, or contractId.

​
contractId
string<uuid>

Contract UUID. When provided, pricing uses the contract's specific rate cards and pricing items (matching invoice generation exactly), and customerId and date range are derived from the contract. If the contract has no termination date (rolling/month-to-month), the end date defaults to today. You can still provide explicit startDate/endDate to override the contract dates. If customerId is also provided, it must match the contract owner.

​
eventNames
string[]

Filter to specific event names. Only meters matching these event names will be queried. When omitted, all active meters are included.

Maximum array length: 50
​
propertyFilters
object[]

Additional property filters applied to the query. Each filter adds a WHERE condition on event properties. Useful for tenant isolation (sub_org_id), environment filtering, or feature attribution.

Maximum array length: 20
​
unit
enum<string>
default:currency

Response unit. currency returns USD amounts. credits converts USD to credits using the rate from the customer's most recent credit grant. If no grant with a credit rate exists, falls back to currency.

Available options:
currency,
credits

Response

Usage cost calculated successfully

​
totalAmount
number

Total cost. In USD when unit is currency, in credits when unit is credits.

​
currency
enum<string>

Currency code. Only present when unit is currency.

Available options:
USD
​
creditRateCents
integer

The credit rate used for conversion (cents per credit). Only present when unit is credits. Auto-resolved from the customer's most recent credit grant.

​
unit
enum<string>

currency for USD responses, credits when credit conversion was applied.

Available options:
currency,
credits
​
startDate
string<date-time>

Start of the queried date range.

​
endDate
string<date-time>

End of the queried date range.

​
queriedAt
string<date-time>

Timestamp when the query was executed.

​
contractId
string<uuid>

The contract ID used for the query. Only present when contractId was provided in the request.