Skip to main content
POST
/
v1
/
usage
/
cost
Get 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"
}

Authorizations

​
Authorization
string
header
required

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

Body

application/json
​
startDate
string<date-time>
required

Start of the date range (inclusive). ISO 8601 format.

​
endDate
string<date-time>
required

End of the date range (exclusive). ISO 8601 format.

​
customerId
string<uuid>

Internal customer UUID. Provide this or externalCustomerId.

​
externalCustomerId
string

Your external customer reference. Provide this or customerId.

​
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
​
creditRateCents
integer

When provided, converts the USD total to credits. Value is cents per credit (e.g., 750 = $7.50/credit). Response will use unit: credits instead of unit: currency.

Required range: x >= 1

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.

​
unit
enum<string>

currency for USD responses, credits when creditRateCents was provided.

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.