​
Usage & Meters API

await accend.usage.createEvent({
  customerId: "cus_123",
  meterId: "meter_123",
  quantity: 1,
  idempotencyKey: "req_123"
});

​
Endpoints

  • POST /v1/usage/events
  • GET /v1/usage/events
  • POST /v1/usage/meters
  • GET /v1/usage/meters
  • POST /v1/access/check

​
POST /v1/usage/events

Scopes: write or usage:write
Idempotency-Key: via idempotencyKey field 
{
  "customerId": "cus_abc123",
  "meterId": "meter_abc123",
  "quantity": 1,
  "idempotencyKey": "evt_req_abc123",
  "metadata": { "endpoint": "/v1/analyze" }
}
  • customerId string required
  • meterId string required
  • quantity number required (must be positive)
  • idempotencyKey string required
  • metadata object optional
Response 200 
{
  "data": {
    "id": "evt_abc123",
    "customerId": "cus_abc123",
    "meterId": "meter_abc123",
    "quantity": 1,
    "status": "recorded",
    "createdAt": "2025-01-15T10:00:00Z"
  },
  "error": null,
  "success": true
}

​
GET /v1/usage/meters

Scopes: read Response 200 
{
  "data": {
    "items": [
      {
        "id": "meter_abc123",
        "name": "API Requests",
        "aggregation": "sum",
        "unit": "request",
        "resetPeriod": "month",
        "createdAt": "2025-01-15T10:00:00Z"
      }
    ],
    "hasMore": false,
    "nextCursor": null
  },
  "error": null,
  "success": true
}

​
POST /v1/usage/meters

Scopes: write
Idempotency-Key: required 
{
  "name": "API Requests",
  "aggregation": "sum",
  "unit": "request",
  "resetPeriod": "month"
}
  • name string required
  • aggregation enum required: sum | count
  • unit string required: request | token | run | query
  • resetPeriod enum required: month | week | never
Response 201 
{
  "data": {
    "id": "meter_abc123",
    "name": "API Requests",
    "slug": "api_requests",
    "aggregation": "sum",
    "unit": "request",
    "resetPeriod": "month",
    "createdAt": "2025-01-15T10:00:00Z"
  },
  "error": null,
  "success": true
}

​
POST /v1/access/check

Scopes: write or usage:write 
{
  "customerId": "cus_abc123",
  "meterId": "meter_abc123",
  "quantity": 1
}
Response 200 (allowed) 
{
  "data": {
    "allowed": true,
    "reason": "credits_available"
  },
  "error": null,
  "success": true
}
Response 200 (denied) 
{
  "data": {
    "allowed": false,
    "reason": "insufficient_credits",
    "paymentUrl": "https://accend.now/pay/cs_xyz"
  },
  "error": null,
  "success": true
}
Reason values:
  • credits_available
  • insufficient_credits
  • no_entitlement
  • entitlement_expired
  • entitlement_past_due

​
GET /v1/usage/events

Scopes: read Query params:
  • customerId string optional
  • meterId string optional
  • limit int (default 100, max 500)
  • before string (cursor)
Response 200 
{
  "data": {
    "items": [
      {
        "id": "evt_abc123",
        "customerId": "cus_abc123",
        "meterId": "meter_abc123",
        "quantity": 1,
        "status": "recorded",
        "createdAt": "2025-01-15T10:00:00Z"
      }
    ],
    "hasMore": false,
    "nextCursor": null
  },
  "error": null,
  "success": true
}