Skip to main content

​
Compute Unit (CU) Pricing Model

BlockDB uses a Compute Unit (CU) pricing model that charges based on the computational complexity of each API endpoint. This ensures you only pay for what you use, without being forced into expensive plans for simple queries.

​
How Compute Units Work

Each API request consumes a certain number of Compute Units based on the dataset level and endpoint complexity:
Need the per-endpoint CU matrix? Open pricing/compute-units for the detailed cost breakdown. This page focuses on the technical mechanics of CU enforcement.

​
CU Metering Details

  • The CU charge is evaluated before the API gateway streams data, so rejected requests still consume CUs.
  • Pagination depth, response size, or filter complexity do not change the CU cost—only the endpoint family matters.
  • Retries count as new requests; use idempotent mutation endpoints and exponential backoff to avoid duplicate CU consumption.
  • Background jobs calling multiple endpoints must account for the cumulative CU cost per workflow; there is no bulk discount at the API layer.

​
Distributed CU Budgets

CU allowances mirror the Distributed Rate Limits model: you can carve up the monthly allowance per key and per region.
  1. Assign each API key a CU slice (static or auto-scaling) in the Admin Panel.
  2. Bind the key to a region (US, EU, AP) to keep CU accounting local to that gateway.
  3. Rotate keys for separate applications or environments so noisy workloads cannot drain the shared CU pool.
# Key 1: Research cluster (US) 250,000 CU
Authorization: Bearer key_us_research

# Key 2: Production trading (EU) 600,000 CU
Authorization: Bearer key_eu_prod

# Key 3: APAC analytics (AP) 150,000 CU
Authorization: Bearer key_ap_analytics

# Organization pool: 1,000,000 CU/month → 250k + 600k + 150k allocation
CU allocations are enforced independently per key. Exhausting the CU slice on one key does not reduce the allowance on other keys, but those requests will begin returning 429 responses with RATE_LIMIT_EXCEEDED.

​
Tracking CU Consumption

​
Usage Endpoint

Call GET /usage to retrieve per-key CU data.
Usage Snapshot
{
  "data": {
    "compute_units": {
      "consumed": 1250,
      "remaining": 8750,
      "limit": 10000,
      "percentage_used": 12.5
    },
    "billing_period": {
      "start": "2025-11-01T00:00:00Z",
      "end": "2025-11-30T23:59:59Z",
      "days_remaining": 19
    },
    "usage_by_dataset": {
      "0101": { "requests": 450, "compute_units": 450 },
      "0102": { "requests": 320, "compute_units": 320 },
      "0103": { "requests": 150, "compute_units": 300 },
      "0401": { "requests": 200, "compute_units": 400 },
      "0501": { "requests": 50, "compute_units": 150 }
    },
    "rate_limits": {
      "requests_per_second": 100
    }
  }
}
The /usage endpoint is free to call and does not consume Compute Units. Poll it to drive dashboards or automated alerts.

​
Best Practices

  1. Split workloads: Give ingestion, research, and production separate keys to prevent noisy neighbors.
  2. Pin to region: Keep workloads local to reduce latency and avoid double-counting during multi-region retries.
  3. Use cheaper datasets first: Filter with 01xx datasets before querying higher-CU analytics endpoints.
  4. Automate alerts: Pair /usage with your observability stack to catch spikes early.
Think of CUs as the compute equivalent of your distributed rate limits—allocate, monitor, and adjust per key and per region to keep mission-critical systems online.