Estimate Usage Revocation Refund

Estimates the scope of a revocation before create. For ID selectors, totals come from PostgreSQL UsageFundDebitDetail rows. For filter, the response returns the Doris match count and whether it exceeds the 100,000-event create limit.

POST /v1/projects/:project_id/usage/revocations/estimate

Authentication

Authorization: Bearer <api-key>

Requires usage:revocation.

Path Parameters

Field	Required	Description
project_id	Yes	Project that owns the events.

Request Body

Provide exactly one selector: raw_event_ids or filter. Do not combine IDs with filter.

Field	Required	Description
raw_event_ids	No	Raw event IDs to estimate (max 1000).
filter	No	Same whitelist as create-revocation filter. Returns match count only. occurred_at.from and occurred_at.to are required inside filter; all other keys are optional.

Example

By raw event IDs (includes refund totals):

curl -X POST 'http://127.0.0.1:8080/v1/projects/proj_gateway/usage/revocations/estimate' \
  -H 'Authorization: Bearer <api-key>' \
  -H 'Content-Type: application/json' \
  -d '{
    "raw_event_ids": ["raw_001", "raw_002"]
  }'

By filter (count before create):

curl -X POST 'http://127.0.0.1:8080/v1/projects/proj_gateway/usage/revocations/estimate' \
  -H 'Authorization: Bearer <api-key>' \
  -H 'Content-Type: application/json' \
  -d '{
    "filter": {
      "subject_type": "user",
      "source": "gateway",
      "occurred_at": { "from": 1719792000, "to": 1722470400 }
    }
  }'

Response

200 OK

{
  "event_count": 2,
  "max_event_count": 100000,
  "exceeds_limit": false,
  "refundable_count": 3,
  "occupied_count": 0,
  "already_revoked_count": 1,
  "totals": [
    { "currency": "USD", "amount": "12.50", "detail_count": 3 }
  ],
  "details": []
}

For filter, totals / details / refund counters are empty; use event_count, max_event_count, and exceeds_limit to decide whether create is allowed. Create rejects filters with exceeds_limit: true.

already_revoked details are excluded from totals. Occupied but unfinished fund details are counted separately and also excluded from totals.