Granular Usage

Admin-only endpoints that return per-event usage records (up to 100 most recent) from the billing-usage-tracking index. Use these to audit individual rate-limit hits or quota consumptions within your customer account. Both endpoints require the caller to hold the billing_admin role (owner or admin).

Events are always scoped to the caller’s customer account — resolved from the authenticated session, not from a request parameter. There is no way to query another customer’s events.

Table of Content:

• Get granular rate-limit events
• Get granular quota events

Shared query parameters

Parameter	Location	Type	Required	Description	Example
userId	query	UUID	No	Narrow the results to a single user within the caller’s customer account.	“5f35d2c4-5633-4b16-bbf0-5ca22ef8ea2e”

A malformed userId returns 400. Omitting it returns events for all users in the caller’s customer.

Shared headers

Header	Required	Description
Authorization	Yes	Bearer token.
api-key	No	API key (alternative).
api-secret	No	API secret.

Shared response shape

{
  "total": 1274,
  "events": [
    {
      "userId": "5f35d2c4-5633-4b16-bbf0-5ca22ef8ea2e",
      "customerId": "5f35d2c4-5633-4b16-bbf0-5ca22ef8ea2e",
      "serviceName": "compute-api",
      "featureKey": "scans",
      "amount": 1,
      "type": "rate_limit",
      "timestamp": 1674492894,
      "uniqueMembers": ["member-id-1"],
      "window": "minute"
    }
  ]
}

• total is the number of matching events in the index (not the size of the events array).
• events is the 100 most recent events ordered by @timestamp descending. Paging is not supported; narrow the filter if you need older results.
• uniqueMembers and window are only populated for unique_limit events.
• If the billing-usage-tracking OpenSearch index does not exist yet (e.g., fresh environment with no traffic), the response is 200 with {"total": 0, "events": []} rather than an error.

Get granular rate-limit events

Returns per-event rate-limit records for the caller’s customer. type on each event will be "rate_limit".

Endpoint: https://apis.threatwinds.com/api/billing/v1/limits/usage/users

curl -X 'GET' \
  'https://apis.threatwinds.com/api/billing/v1/limits/usage/users' \
  -H 'Authorization: Bearer <token>'

Narrow to a single user within your customer:

curl -X 'GET' \
  'https://apis.threatwinds.com/api/billing/v1/limits/usage/users?userId=abcdef12-3456-7890-abcd-ef1234567890' \
  -H 'Authorization: Bearer <token>'

Returns

See Shared response shape.

Get granular quota events

Returns per-event quota consumption records for the caller’s customer. type on each event will be "quota".

Endpoint: https://apis.threatwinds.com/api/billing/v1/quotas/usage/users

curl -X 'GET' \
  'https://apis.threatwinds.com/api/billing/v1/quotas/usage/users' \
  -H 'Authorization: Bearer <token>'

Returns

See Shared response shape.