> ## Documentation Index
> Fetch the complete documentation index at: https://docs.blockdb.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Usage & Limits

> Retrieve your subscription plan, compute unit (CU) balance, billing reset time, and configured RPS limit.

## Overview

Retrieves your current subscription plan, compute unit (CU) usage for the billing period, remaining allowance, when the CU counter resets, and your account’s configured requests-per-second ceiling. **CU and RPS limits are shared across every API key on the account**—see [Rate limiting](/api-reference/overview/rate-limiting). Use this endpoint to stay within quota and to align client throttling with your plan.

<Info>
  This endpoint is free to query and does not consume compute units.
</Info>

## Parameters

This endpoint does not require a request body. You may authenticate with any active key; the response describes **your account**, not a per-key slice of usage or RPS.

## Response Fields

<ResponseField name="plan" type="string">
  Your subscription plan identifier (for example `growth`).
</ResponseField>

<ResponseField name="cu_used" type="number">
  Compute units consumed in the current billing period.
</ResponseField>

<ResponseField name="cu_limit" type="number">
  Total compute units included in your plan for the current billing period.
</ResponseField>

<ResponseField name="cu_remaining" type="number">
  Compute units left before you hit `cu_limit` (`cu_limit` minus `cu_used`).
</ResponseField>

<ResponseField name="cu_reset_at" type="string">
  When the CU counter resets for the next billing period (ISO-8601 UTC).
</ResponseField>

<ResponseField name="rate_limit_rps" type="number">
  Configured maximum requests per second for **your account**. All keys share this same RPS budget; it is not split per key.
</ResponseField>

### Best Practices

<Tip>
  Query this endpoint periodically (for example daily) to monitor consumption and avoid unexpected throttling near the end of a billing period.
</Tip>

<Tip>
  Compare `cu_remaining` with expected workload so you can upgrade or reduce query volume before hitting `cu_limit`.
</Tip>

<Warning>
  While this endpoint does not consume CUs, automated polling should still use a reasonable interval so you do not hit management-endpoint rate limits.
</Warning>

### See Also

* [Health](/api-reference/account-and-usage/health) — API liveness check
* [Pricing](/pricing/home) — BlockDB subscription plans
* [Rate Limiting](/api-reference/overview/rate-limiting) — Understanding RPS limits and quotas
* [Authorization](/api-reference/overview/authorization) — API key management

<RequestExample>
  ```bash cURL theme={null}
  curl -X GET "https://api.blockdb.io/v1/usage" \
    -H "Authorization: Bearer $BLOCKDB_API_KEY"
  ```

  ```python Python theme={null}
  import requests
  import os

  response = requests.get(
      "https://api.blockdb.io/v1/usage",
      headers={
          "Authorization": f"Bearer {os.getenv('BLOCKDB_API_KEY')}"
      }
  )

  data = response.json()
  print(data)
  ```

  ```javascript Node.js theme={null}
  const response = await fetch("https://api.blockdb.io/v1/usage", {
    method: "GET",
    headers: {
      "Authorization": `Bearer ${process.env.BLOCKDB_API_KEY}`
    }
  });

  const data = await response.json();
  console.log(data);
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "plan": "growth",
    "cu_used": 0,
    "cu_limit": 4100000,
    "cu_remaining": 4100000,
    "cu_reset_at": "2026-05-22T11:53:12.000Z",
    "rate_limit_rps": 1000
  }
  ```

  ```json 400 theme={null}
  {
    "error": {
      "code": "BAD_REQUEST",
      "http_status": 400,
      "message": "The request contains invalid or missing parameters.",
      "hint": "Validate all required parameters against the endpoint specification before retrying.",
      "severity": "error",
      "retryable": false,
      "details": {
        "invalid_parameters": [
          {
            "name": "chain_id",
            "location": "query",
            "reason": "missing",
            "expected": "positive integer, e.g. 1"
          },
          {
            "name": "from_timestamp",
            "location": "query",
            "reason": "invalid_format",
            "expected": "ISO-8601 UTC timestamp, e.g. 2025-11-11T00:00:00Z"
          }
        ]
      },
      "docs_url": "https://docs.blockdb.io/api-reference/overview/home"
    }
  }
  ```

  ```json 401 theme={null}
  {
    "error": {
      "code": "UNAUTHORIZED",
      "http_status": 401,
      "message": "Invalid or missing API key.",
      "hint": "Ensure you send 'Authorization: Bearer <API_KEY>' in every request to this endpoint.",
      "severity": "error",
      "retryable": false,
      "details": {
        "auth_scheme": "bearer",
        "expected_header": "Authorization: Bearer <API_KEY>",
        "provided_header": "Authorization: <REDACTED_OR_MISSING>",
        "token_status": "invalid_or_missing",
        "recommendation": "Regenerate the API key if you suspect it is expired or compromised."
      },
      "docs_url": "https://docs.blockdb.io/api-reference/overview/authorization"
    }
  }
  ```

  ```json 403 theme={null}
  {
    "error": {
      "code": "FORBIDDEN",
      "http_status": 403,
      "message": "Your API key does not have permission to access this endpoint.",
      "hint": "Upgrade your subscription tier or request additional access.",
      "severity": "warning",
      "retryable": false,
      "details": {
        "required_plan": "production",
        "your_plan": null,
        "contact": "support@blockdb.io",
        "recommendation": "Contact BlockDB Support Team via email support@blockdb.io."
      },
      "docs_url": "https://docs.blockdb.io/api-reference/overview/error-codes"
    }
  }
  ```

  ```json 404 theme={null}
  {
    "error": {
      "code": "NOT_FOUND",
      "http_status": 404,
      "message": "The requested resource does not exist.",
      "hint": "Verify the API endpoint",
      "severity": "warning",
      "retryable": false,
      "docs_url": "https://docs.blockdb.io/api-reference/overview/error-codes"
    }
  }
  ```

  ```json 413 theme={null}
  {
    "error": {
      "code": "PAYLOAD_TOO_LARGE",
      "http_status": 413,
      "message": "The requested response exceeds the maximum allowed size of 10 MB.",
      "hint": "Reduce the limit, narrow the block or time window, or apply additional filters before retrying.",
      "details": {
        "max_allowed_bytes": 10485760,
        "estimated_response_bytes": 15360000,
        "recommended_actions": [
          "Decrease the 'limit' parameter value",
          "Shorten the block range or time window",
          "Filter by fewer pools or exchanges"
        ]
      },
      "docs_url": "https://docs.blockdb.io/api-reference/overview/pagination-and-limits"
    }
  }
  ```

  ```json 429 theme={null}
  {
    "error": {
      "code": "RATE_LIMIT_EXCEEDED",
      "http_status": 429,
      "message": "You have exceeded the allowed request rate.",
      "hint": "Introduce client-side throttling or exponential backoff and respect the retry_after_seconds value.",
      "details": {
        "limit_rps": 1000,
        "current_estimated_rps": 73,
        "retry_after_seconds": 2,
        "limit_scope": "api_key",
        "limit_window_seconds": 1
      },
      "docs_url": "https://docs.blockdb.io/api-reference/overview/rate-limiting"
    }
  }
  ```

  ```json 500 theme={null}
  {
    "error": {
      "code": "INTERNAL_SERVER_ERROR",
      "http_status": 500,
      "message": "An unexpected server error occurred.",
      "hint": "This error is not caused by your request. You may retry after a short delay.",
      "severity": "critical",
      "retryable": true,
      "details": {
        "incident_id": "INC-2025-11-11-123456",
        "temporary_issue": true,
        "expected_recovery_seconds": 5
      },
      "docs_url": "https://docs.blockdb.io/api-reference/overview/error-codes"
    }
  }
  ```

  ```json 503 theme={null}
  {
    "error": {
      "code": "SERVICE_UNAVAILABLE",
      "http_status": 503,
      "message": "The service is temporarily unable to handle the request.",
      "hint": "The database connection pool is briefly saturated. Retry after a short delay.",
      "severity": "warning",
      "retryable": true,
      "details": null,
      "docs_url": "https://docs.blockdb.io/api-reference/overview/error-codes"
    }
  }
  ```
</ResponseExample>