Model usage meters, ingest high-throughput customer consumption events with idempotency, and query logs.

Meters & Usage Ingestion API

The Meters & Usage Ingestion API allows you to charge customers based on their active consumption of your service. Usage-based billing (or metered billing) requires creating Meters that represent the metric you want to track (e.g. database disk size, API calls, active users), and Usage Events to ingest consumption data in real-time as users interact with your system.

Define a Meter

Create a new meter to track a billable metric.

Detail	Description
API Endpoint	`https://api.xtopay.co/v1/meters`
Request Type	`POST`
Content Type	`application/json`
Authentication	`Basic Base64(clientId:clientSecret)`
Required Scope	`meters:write`

Request Parameters

Parameter	Type	Required	Description
`name`	`String`	Yes	Human-readable name of the meter (e.g. `"AI GPT-4 Token Meter"`).
`eventName`	`String`	Yes	The exact event name you will use when sending events (e.g. `"gpt4_tokens"`). Must be unique.
`aggregation`	`String`	No	Strategy to sum/aggregate usage: `SUM`, `COUNT`, `MAX`, `LAST`. Defaults to `SUM`.
`valueField`	`String`	No	The JSON key in the event payload containing the quantity. Defaults to `"value"`.

Code Examples

curl https://api.xtopay.co/v1/meters \
  -u "YOUR_CLIENT_ID:YOUR_CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "AI Text Ingestion",
    "eventName": "ai_words_processed",
    "aggregation": "SUM",
    "valueField": "value"
  }'

Sample Response

201 Created

{
  "success": true,
  "data": {
    "id": "met_cl8z2e9z50000y",
    "name": "AI Text Ingestion",
    "eventName": "ai_words_processed",
    "aggregation": "SUM",
    "valueField": "value",
    "active": true,
    "createdAt": "2026-06-05T12:00:00Z",
    "updatedAt": "2026-06-05T12:00:00Z"
  }
}

Retrieve a Meter

Retrieve details of an existing meter.

Detail	Description
API Endpoint	`https://api.xtopay.co/v1/meters/:id`
Request Type	`GET`
Authentication	`Basic Base64(clientId:clientSecret)`
Required Scope	`meters:read`

Path Parameters

Parameter	Type	Required	Description
`:id`	`String`	Yes	Unique Meter ID (e.g. `met_cl8z2e...`).

Ingest a Usage Event

Submit usage data in real-time as a customer consumes services. Xtopay supports high-throughput event ingestion.

Detail	Description
API Endpoint	`https://api.xtopay.co/v1/meters/:id/events`
Request Type	`POST`
Content Type	`application/json`
Authentication	`Basic Base64(clientId:clientSecret)`
Required Scope	`meters:write`

Request Parameters

Parameter	Type	Required	Description
`customerId`	`String`	No	The customer ID to associate with the usage.
`value`	`Number`	No	The numeric count/quantity to ingest. Defaults to `1`.
`timestamp`	`String`	No	ISO 8601 date string when the event occurred. Defaults to the current server time.
`idempotencyKey`	`String`	No	A unique string to prevent double-ingesting the exact same event. Duplicate keys are safely ignored.
`metadata`	`Object`	No	Optional key-value object containing transaction metadata.

Code Examples

curl https://api.xtopay.co/v1/meters/met_cl8z2e9z50000y/events \
  -u "YOUR_CLIENT_ID:YOUR_CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "customerId": "cust_cl8z2e9z50000a",
    "value": 150,
    "idempotencyKey": "evt_unique_1289182391283",
    "metadata": {
      "modelUsed": "gpt-4o"
    }
  }'

Sample Response

201 Created

{
  "success": true,
  "data": {
    "id": "mte_cl8z2f8z80000x",
    "meterId": "met_cl8z2e9z50000y",
    "customerId": "cust_cl8z2e9z50000a",
    "value": 150,
    "idempotencyKey": "evt_unique_1289182391283",
    "timestamp": "2026-06-05T12:05:00Z",
    "metadata": {
      "modelUsed": "gpt-4o"
    },
    "createdAt": "2026-06-05T12:05:00Z"
  }
}

Query Ingested Events

Fetch logs of usage events recorded by a specific meter.

Detail	Description
API Endpoint	`https://api.xtopay.co/v1/meters/:id/events`
Request Type	`GET`
Authentication	`Basic Base64(clientId:clientSecret)`
Required Scope	`meters:read`

Query Parameters

Parameter	Type	Required	Description
`customerId`	`String`	No	Filter logs by customer ID.
`from`	`String`	No	ISO 8601 date string. Filter events created on or after this date.
`to`	`String`	No	ISO 8601 date string. Filter events created on or before this date.
`limit`	`Integer`	No	Maximum results to return per page (range 1–100, default `20`).
`cursor`	`String`	No	Pagination cursor from a previous response.

Meters & Usage Ingestion API

On this page