Skip to main content
GET
/
v0
/
usage
List
curl --request GET \
  --url https://api.paygentic.io/v0/usage \
  --header 'Authorization: Bearer <token>'
{
  "object": "list",
  "data": [
    {
      "id": "usg_f3g4h5i6j7k8l9m0",
      "object": "usageEvent",
      "billing": null,
      "consumerId": "org_v9w8x7y6z5a4b3c2",
      "createdAt": "2024-04-15T10:30:05Z",
      "customerId": "cus_n1o2p3q4r5s6t7u8",
      "description": "Claude language model text generation",
      "entitlementId": null,
      "idempotencyKey": "usg_2024_04_15_abc123",
      "merchantId": "org_v9w8x7y6z5a4b3c2",
      "metadata": {
        "input_tokens": "1500",
        "model_name": "claude-3-opus",
        "output_tokens": "800"
      },
      "properties": [
        {
          "billableMetricId": "bm_l5m6n7o8p9q0r1s2",
          "price": null,
          "quantity": 2500
        }
      ],
      "subscriptionId": "sub_d1e2f3g4h5i6j7k8",
      "timestamp": "2024-04-15T10:30:00Z"
    },
    {
      "id": "usg_t3u4v5w6x7y8z9a0",
      "object": "usageEvent",
      "billing": {
        "billingEventId": "bev_p1q2r3s4t5u6v7w8",
        "currency": "USD",
        "price": 6345000000000,
        "totalAmount": 6916050000000,
        "totalTax": 571050000000
      },
      "consumerId": "org_j9k0l1m2n3o4p5q6",
      "createdAt": "2024-05-20T14:45:35Z",
      "customerId": "cus_b1c2d3e4f5g6h7i8",
      "description": "Customer data warehouse storage allocation",
      "entitlementId": "com_z5a6b7c8d9e0f1g2",
      "idempotencyKey": "usg_2024_05_20_xyz789",
      "merchantId": "org_j9k0l1m2n3o4p5q6",
      "metadata": {
        "data_center": "eu-west-1",
        "encryption": "enabled",
        "storage_tier": "premium"
      },
      "properties": [
        {
          "billableMetricId": "bm_h3i4j5k6l7m8n9o0",
          "price": null,
          "quantity": 42
        }
      ],
      "subscriptionId": "sub_r7s8t9u0v1w2x3y4",
      "timestamp": "2024-05-20T14:45:30Z"
    }
  ],
  "pagination": {
    "limit": 10,
    "offset": 0,
    "total": 2
  }
}

Authorizations

​
Authorization
string
header
required

API key authentication

Query Parameters

​
consumerId
string

Filter by consumer ID. This is only available if the caller is member of the consumer organization. Unique identifier for an organization

Pattern: ^org_[a-zA-Z0-9]+$
​
customerId
string

Filter by customer ID. This is only available if the caller is member of the merchant organization owning this customer. Unique identifier for a customer

Pattern: ^cus_[a-zA-Z0-9]+$
​
endTime
string<date-time>
required

ISO 8601 date-time string filtering events up to this timestamp. Sample values: '2024-01-31T23:59:59Z', '2024-02-28T12:00:00Z'

​
limit
integer
default:10

Number of usage events to return

Required range: 1 <= x <= 100
​
merchantId
string

Filter by merchant ID. This is only available if the caller is member of the merchant organization. Unique identifier for an organization

Pattern: ^org_[a-zA-Z0-9]+$
​
offset
integer
default:0

Number of usage events to skip

Required range: x >= 0
​
startTime
string<date-time>
required

ISO 8601 date-time string filtering events from this timestamp onward. Sample values: '2024-01-15T00:00:00Z', '2024-02-01T10:30:00Z'

​
subscriptionId
string

Filter by subscription ID. This is only available if the caller is member of the consumer or merchant organization owning this subscription. Unique identifier for a subscription

Pattern: ^sub_[a-zA-Z0-9]+$

Response

List of usage events

​
object
enum<string>
Available options:
list
​
data
object[]
​
pagination
object

Offset-based pagination response.