Usage Summary

Return the authenticated account's current plan, billing period, credit balances, and credit usage by operation.

Execution model

Synchronous read

Returns the current account summary in the same request.

Credit weight

Not charged

Reading usage does not consume credits or create billing rows.

Usage Summary Endpoint

Read the current plan, billing period, available credits, and per-operation credit usage.

Getting Started

Send your API key as a bearer token. Start with the smallest request below.

Get Current Usage

Send an API key and read the current account summary.

curl -X GET "https://api.datablue.dev/v1/usage/summary" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example response

{
  "success": true,
  "as_of": "2026-08-25T12:00:00Z",
  "plan": {
    "id": "ef7ea042-2366-4f52-9298-b51dd03524c0",
    "name": "starter",
    "display_name": "Starter",
    "access_status": "active",
    "access_source": "razorpay",
    "concurrency_limit": 5,
    "features": {
      "scrape": true,
      "crawl": true
    }
  },
  "subscription": {
    "status": "active",
    "billing_cycle": "monthly",
    "cancel_at_period_end": false,
    "pending_plan": null
  },
  "billing_period": {
    "id": "0fae1ec8-726e-494b-8f7f-60b94666ef88",
    "status": "active",
    "starts_at": "2026-08-01T00:00:00Z",
    "ends_at": "2026-09-01T00:00:00Z",
    "timezone": "Asia/Kolkata"
  },
  "credits": {
    "included": 1000,
    "used": 125,
    "remaining": 875,
    "payg_balance": 50,
    "payg_used_this_period": 25,
    "total_used_this_period": 150,
    "total_available": 925,
    "unlimited": false
  },
  "usage": {
    "by_operation": {
      "scrape": {
        "credits_used": 100
      },
      "data_api": {
        "credits_used": 50
      }
    }
  }
}

Response

Unlimited plans return null for finite included, remaining, and total-available values. If no active billing period exists, period-scoped measurements are also null rather than zero.

Error Handling

Handle 401 for missing or invalid authentication. A temporary 503 means the active billing balance could not be measured safely; retry later without substituting zero values.

Response fields

Field	Type	Description
success	boolean	True when the summary was returned.
as_of	string (date-time)	UTC time when the summary was calculated.
plan	object \| null	Current plan identity, access status, concurrency limit, and feature flags.
subscription	object \| null	Active subscription state and any pending plan change.
billing_period	object \| null	Active billing-period dates, status, and timezone.
credits.included	integer \| null	Credits included in the current period. Null for unlimited plans or when no finite value is available.
credits.used	integer \| null	Included credits used in the active period.
credits.remaining	integer \| null	Included credits remaining in the active period. Null for unlimited plans or when no active period exists.
credits.payg_balance	integer	Current top-up credit balance.
credits.payg_used_this_period	integer \| null	Top-up credits used in the active period.
credits.total_used_this_period	integer \| null	Included and top-up credits used in the active period.
credits.total_available	integer \| null	Remaining included credits plus the current top-up balance. Null for unlimited plans.
credits.unlimited	boolean	Whether the active plan has unlimited included credits.
usage.by_operation	object	Credit charges grouped by operation for the active billing period.

Request and response

curl -X GET "https://api.datablue.dev/v1/usage/summary" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example response

{
  "success": true,
  "as_of": "2026-08-25T12:00:00Z",
  "plan": {
    "id": "ef7ea042-2366-4f52-9298-b51dd03524c0",
    "name": "starter",
    "display_name": "Starter",
    "access_status": "active",
    "access_source": "razorpay",
    "concurrency_limit": 5,
    "features": {
      "scrape": true,
      "crawl": true
    }
  },
  "subscription": {
    "status": "active",
    "billing_cycle": "monthly",
    "cancel_at_period_end": false,
    "pending_plan": null
  },
  "billing_period": {
    "id": "0fae1ec8-726e-494b-8f7f-60b94666ef88",
    "status": "active",
    "starts_at": "2026-08-01T00:00:00Z",
    "ends_at": "2026-09-01T00:00:00Z",
    "timezone": "Asia/Kolkata"
  },
  "credits": {
    "included": 1000,
    "used": 125,
    "remaining": 875,
    "payg_balance": 50,
    "payg_used_this_period": 25,
    "total_used_this_period": 150,
    "total_available": 925,
    "unlimited": false
  },
  "usage": {
    "by_operation": {
      "scrape": {
        "credits_used": 100
      },
      "data_api": {
        "credits_used": 50
      }
    }
  }
}