Entity entitlement usage exceeded

Fired when reported usage crosses a usage threshold on an entity entitlement. One event covers every threshold crossed by the same report.

WEBHOOK entity.entitlement.usage_exceeded

default

{
  "type": "entity.entitlement.usage_exceeded",
  "messageId": "a6ce...",
  "traceId": "549a...",
  "timestamp": "2026-10-29T10:00:00.000Z",
  "eventId": "7d2f...",
  "id": "team-eng",
  "actor": {
    "type": "APP_SERVER"
  },
  "customer": {
    "id": "cus-acme"
  },
  "data": {
    "object": {
      "entityId": "team-eng",
      "entityTypeId": "team",
      "featureId": "feature-ai-tokens",
      "scopeEntityIds": [],
      "limit": 200000,
      "thresholds": [
        80
      ],
      "previousUsage": 150000,
      "currentUsage": 165000,
      "usageUsedPercentage": 82.5,
      "usagePeriodStart": "2026-10-01T00:00:00.000Z",
      "usagePeriodEnd": "2026-11-01T00:00:00.000Z",
      "cadence": "P1M"
    }
  }
}

Body

application/json

type · string · required

Event type discriminator.

messageId · string · required

Unique webhook message ID. Differs per webhook endpoint; use eventId to deduplicate.

traceId · string · required

Correlation ID for tracing.

timestamp · string<date-time> · required

Time the event was sent.

eventId · string · required

Unique event ID, the same ID shown in the activity log.

id · string · required

ID of the entity or entity type the event is about.

customer · object · required

The customer that owns the entity.

Show child attributes

data · object · required

Show child attributes

actor · object

Who made the change, when known, e.g. { "type": "APP_SERVER" }.