SDK Usage and Jobs

Inspect usage and jobs

Read the current plan and credit balance, aggregate activity, filter job history, inspect top domains, or delete stored jobs.

Get plan and credit usage

API clients authenticate with Authorization: Bearer YOUR_API_KEY. The DataBlue dashboard calls the same endpoint with its existing JWT session cookie.

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

If no active billing period exists, period-scoped measurements are null. Unlimited plans also return null for finite included, remaining, and total-available values; clients must not treat those values as zero.

Get usage statistics

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

Example response

{
  "total_jobs": 24,
  "total_pages_scraped": 180,
  "avg_pages_per_job": 7.5,
  "avg_duration_seconds": 12.4,
  "success_rate": 95.8,
  "jobs_by_type": {
    "scrape": 18,
    "crawl": 6
  },
  "jobs_by_status": {
    "completed": 23,
    "failed": 1
  },
  "jobs_per_day": [
    {
      "date": "2026-07-20",
      "count": 4
    }
  ]
}

Filter job history

Example

# Python
history = client.get_usage_history(
    page=1,
    per_page=20,
    type="crawl",
    status="completed",
    search="example.com",
)

// Node.js
const history = await client.getUsageHistory({
  page: 1,
  perPage: 20,
  type: "crawl",
  status: "completed",
  search: "example.com",
});

Operational methods

Task	Python	Node.js
Plan and credits	`get_usage_summary()`	`getUsageSummary()`
Usage totals	`get_usage_stats()`	`getUsageStats()`
Paginated history	`get_usage_history()`	`getUsageHistory()`
Top domains	`get_top_domains()`	`getTopDomains()`
Delete a job	`delete_job()`	`deleteJob()`
Quota alias	`get_quota()`	`getQuota()`