Skip to main content
GET
https://api.blockdb.io
/
v1
/
usage
curl -X GET "https://api.blockdb.io/v1/usage" \
  -H "Authorization: Bearer $BLOCKDB_API_KEY"

{
  "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
    }
  }
}

​
Description

Retrieves your current Compute Unit (CU) consumption, remaining quota, usage statistics, and billing period information. This endpoint helps you monitor your API usage and plan your consumption accordingly.
This endpoint does not consume Compute Units - it’s free to query your usage at any time.

​
Parameters

This endpoint does not require a request body. All usage data is scoped to the API key used for authentication.

​
Response Fields

​
Data

​
data
object
Wrapper for usage details scoped to the authenticated API key.
​
data.compute_units
object
Current billing-period compute unit summary.
​
data.compute_units.consumed
number
Total CU consumed in the current billing period.
​
data.compute_units.remaining
number
CU remaining in your monthly allowance.
​
data.compute_units.limit
number
Total CU limit for your plan.
​
data.compute_units.percentage_used
number
Percentage of CU limit used (0-100).
​
data.billing_period
object
Current billing period window.
​
data.billing_period.start
string
Start of current billing period (ISO-8601).
​
data.billing_period.end
string
End of current billing period (ISO-8601).
​
data.billing_period.days_remaining
number
Days remaining in the current billing period.
​
data.usage_by_dataset
object
Map of dataset IDs to usage statistics (requests, compute_units).
​
data.rate_limits
object
Configured rate limits for the API key.
​
data.rate_limits.requests_per_second
number
Configured RPS limit for your API key.
​
data.rate_limits.current_usage
number
Current RPS usage (rolling window).
​
data.rate_limits.burst_available
boolean
Whether burst capacity is currently available.
​
data.projected_monthly_usage
object
Projected usage for the full month based on current rate.
​
data.projected_monthly_usage.compute_units
number
Projected CU consumption for the full month.
​
data.projected_monthly_usage.percentage_of_limit
number
Projected percentage of CU limit that will be used.

​
Best Practices

Query this endpoint periodically (e.g., daily) to monitor your usage and avoid unexpected overages.
Monitor usage_by_dataset to identify which endpoints consume the most CUs and optimize your queries accordingly.
This endpoint does not consume Compute Units, but it does count toward your rate limit (RPS). Use it judiciously in automated monitoring systems.

​
See Also

curl -X GET "https://api.blockdb.io/v1/usage" \
  -H "Authorization: Bearer $BLOCKDB_API_KEY"

{
  "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
    }
  }
}