Billing API

The VARICON Billing API provides a programmable interface for usage tracking, attribution, and anomaly-based billing.

It exposes billing as a first-class system surface.

Use it to:

• record anomaly usage events
• retrieve usage summaries
• inspect billing events
• attribute usage by service or team
• understand how enriched anomalies become billable units

Core billing model

VARICON billing is based on a single unit:

1 enriched anomaly = 1 billable unit

Only anomalies that cross the intelligence boundary become billable.

This means:

• detection is not billed
• extraction is not billed
• fingerprinting is not billed
• enrichment is billed

API surface

1. Record usage events

POST /v1/usage/events

Records anomaly usage events that may become billable.

Request

{
  "events": [
    {
      "fingerprint": "fp_hidden_error",
      "timestamp": 1710000000,
      "count": 42,
      "type": "enriched_anomaly",
      "service": "payments-api",
      "team": "Payments",
      "environment": "production"
    }
  ]
}

Fields

Response

{
  "status": "accepted",
  "processed_events": 1,
  "billable_events": 1
}

2. Retrieve usage summary

GET /v1/usage/summary?month=2026-03

Returns aggregate monthly usage information.

Response

{
  "month": "2026-03",
  "total_anomalies": 82000,
  "enriched_anomalies": 72000,
  "billable_anomalies": 62000,
  "free_allowance": 10000,
  "cost_usd": 62.0
}

Notes

This endpoint is useful for:

• monthly usage reporting
• pricing visibility
• cost monitoring
• billing reconciliation

3. List billing events

GET /v1/events

Returns a list of billing events.

Supported query parameters

Example

GET /v1/events?service=payments-api&environment=production&billable=true&limit=2

Response

{
  "data": [
    {
      "id": "evt_001",
      "timestamp": "2026-03-30T18:01:00Z",
      "service": "payments-api",
      "team": "Payments",
      "environment": "production",
      "fingerprint": "fp_hidden_error",
      "event_type": "enriched_anomaly",
      "count": 42,
      "billable": true,
      "cost_usd": 4.2
    },
    {
      "id": "evt_002",
      "timestamp": "2026-03-30T18:11:00Z",
      "service": "payments-api",
      "team": "Payments",
      "environment": "production",
      "fingerprint": "fp_contract_drift",
      "event_type": "enriched_anomaly",
      "count": 18,
      "billable": true,
      "cost_usd": 1.8
    }
  ],
  "next_cursor": "evt_cursor_002"
}

4. Retrieve a billing event

GET /v1/events/:id

Returns a single billing event.

Example

GET /v1/events/evt_001

Response

{
  "id": "evt_001",
  "timestamp": "2026-03-30T18:01:00Z",
  "service": "payments-api",
  "team": "Payments",
  "environment": "production",
  "fingerprint": "fp_hidden_error",
  "event_type": "enriched_anomaly",
  "count": 42,
  "billable": true,
  "cost_usd": 4.2
}

5. Usage attribution by service

GET /v1/usage/by-service?month=2026-03

Returns attributed usage grouped by service.

Response

{
  "data": [
    {
      "service": "payments-api",
      "team": "Payments",
      "environment": "production",
      "total_anomalies": 32000,
      "enriched_anomalies": 28000,
      "cost_usd": 28.0
    },
    {
      "service": "auth-service",
      "team": "Identity",
      "environment": "production",
      "total_anomalies": 14000,
      "enriched_anomalies": 9000,
      "cost_usd": 9.0
    }
  ]
}

6. Usage attribution by team

GET /v1/usage/by-team?month=2026-03

Returns attributed usage grouped by team.

Response

{
  "data": [
    {
      "team": "Payments",
      "enriched_anomalies": 28000,
      "cost_usd": 28.0
    },
    {
      "team": "Identity",
      "enriched_anomalies": 9000,
      "cost_usd": 9.0
    }
  ]
}

Event types

Common event types include:

• enriched_anomaly
• free_allowance_applied
• usage_summary_rollup

Event type semantics

enriched_anomaly

Represents usage that crossed the intelligence boundary and may be billable.

free_allowance_applied

Represents anomaly usage that was visible but absorbed by the free allowance.

usage_summary_rollup

Represents summary-level accounting or aggregation activity.

Idempotency

Usage event ingestion must be idempotent.

Deduplication should be based on:

• fingerprint
• timestamp
• service
• environment

Repeated submissions of the same logical event must not increase billable usage.

Idempotency key example

Idempotency-Key: usage-fp_hidden_error-1710000000-payments-api-production

Pagination

List endpoints should support cursor-based pagination.

Example

GET /v1/events?limit=50&cursor=evt_cursor_002

Response shape

{
  "data": [],
  "next_cursor": "evt_cursor_003"
}

Metering boundary

Billing starts only after enrichment.

This means the Billing API operates after the anomaly pipeline has crossed the metering boundary.

Not billed

• detection
• extraction
• fingerprinting
• report generation

Billed

• enriched anomaly usage
• intelligence-layer processing

This keeps billing aligned with delivered value rather than raw system activity.

Fail-open behavior

The Billing API follows the VARICON fail-open model.

If the Billing API is unavailable:

• pipeline execution continues
• anomaly extraction is unaffected
• usage can be cached locally
• retries can be performed asynchronously

Billing only occurs when events are successfully processed.

Attribution model

The Billing API supports attribution because billable usage is more useful when linked to ownership.

Typical attribution dimensions include:

• service
• team
• environment
• fingerprint

This allows downstream billing and reporting surfaces to answer:

• where usage came from
• which owner generated it
• what behavior drove cost

Error model

Typical error responses may include:

Invalid request

{
  "error": {
    "type": "invalid_request",
    "message": "Missing required field: service"
  }
}

Unauthorized

{
  "error": {
    "type": "unauthorized",
    "message": "Invalid billing token"
  }
}

Conflict / duplicate submission

{
  "error": {
    "type": "duplicate_event",
    "message": "This event has already been recorded"
  }
}

Design principles

The Billing API is designed to be:

• deterministic — fingerprints produce stable billing semantics
• usage-based — billing follows anomaly intelligence
• attributable — usage can be mapped to service and team
• fail-open — CI pipelines are never blocked by billing failures
• transparent — billable usage can be explained through summaries and events

Related pages

• Pricing
• Billing Overview
• Billing Events
• Usage Attribution

Summary

The VARICON Billing API turns billing into a transparent, programmable system surface.

It enables:

• usage ingestion
• billing event inspection
• attribution by service and team
• predictable anomaly-based billing

Billing is not based on traffic. It is based on understanding anomalies.