Skip to main content
Two HTTP endpoints expose everything you need to track spend:
  • GET /accounts/:owner_id — point-in-time wallet snapshot + tier state
  • GET /accounts/:owner_id/usage — cost and scan counts over a time range
Both are authenticated with your standard X-API-Key header. You can only read your own account — requests for a different owner ID return 403.

​
Account snapshot

GET /accounts/:owner_id
Returns the current account + wallet snapshot. 
curl https://api.declaw.ai/accounts/acct_abc123 \
  -H "X-API-Key: YOUR_API_KEY"

​
Response

​
owner_id
string
Account identifier.
​
email
string
Account email.
​
tier
string
One of free, pro, enterprise.
​
created_at
string
Account creation timestamp (RFC3339, UTC).
​
tier_changed_at
string | null
When the account last moved to its current paid tier. null for Free accounts. Used as the billing-cycle anchor for the monthly recharge commitment.
​
grace_deadline
string | null
Set when a Pro / Enterprise account misses its monthly commitment. While non-null, the paid tier stays active; after the deadline passes without a qualifying deposit, the account is downgraded to Free.
​
sandbox_free_micros
integer
Remaining sandbox free credits in microdollars. Starts at 100000000 (100)ataccountcreation.</ResponseField><ResponseFieldname="guardrailsfreemicros"type="integer">Remainingguardrailsfreecreditsinmicrodollars.Startsat200000000(100) at account creation.</ResponseField> <ResponseField name="guardrails_free_micros" type="integer">Remaining guardrails free credits in microdollars. Starts at 200000000 (200).
​
balance_micros
integer
Paid balance in microdollars. Topped up by deposits.
Response
{
  "owner_id": "acct_abc123",
  "email": "you@example.com",
  "tier": "pro",
  "created_at": "2026-02-01T10:00:00Z",
  "tier_changed_at": "2026-02-05T14:22:00Z",
  "grace_deadline": null,
  "sandbox_free_micros": 74300000,
  "guardrails_free_micros": 198850000,
  "balance_micros": 950000000
}
To compute your effective sandbox balance (what’s available for sandbox compute charges), sum sandbox_free_micros + balance_micros. Same for guardrails. The wallet drains sandbox free first, then paid; guardrails free first, then paid.

​
Usage over a time range

GET /accounts/:owner_id/usage
Returns aggregated cost + scan counts for a time range.

​
Query parameters

​
start
string
Window start (RFC3339). Defaults to 30 days ago.
​
end
string
Window end (RFC3339). Defaults to now.
​
since
string
Backward-compatible alias for start. Ignored if start is set.

​
Response

​
owner_id
string
Account identifier.
​
since
string
Effective window start (RFC3339 UTC).
​
total_cost_micros
integer
Total sandbox compute cost for the window, in microdollars.
​
total_cost_usd
string
Convenience string: total_cost_micros / 1000000 formatted to 2 decimal places.
​
sandbox_count
integer
Number of distinct sandboxes metered in the window.
​
total_seconds
integer
Total sandbox-seconds consumed.
​
sandbox_balance_remaining_micros
integer
Sum of sandbox_free_micros + balance_micros at the time of the query.
​
guardrails_cost_micros
integer
Total guardrails scan cost in the window. Present only when the guardrails store is available.
​
guardrails_cost_usd
string
USD-formatted equivalent.
​
guardrails_balance_remaining_micros
integer
Sum of guardrails_free_micros + balance_micros.
​
guardrails_breakdown
object
Per-scanner scan counts: pii_ml_scans, injection_ml_scans, toxicity_ml_scans, code_security_scans, language_ml_scans, invisible_text_scans.
Response
{
  "owner_id": "acct_abc123",
  "since": "2026-03-15T00:00:00Z",
  "total_cost_micros": 25700000,
  "total_cost_usd": "25.70",
  "sandbox_count": 143,
  "total_seconds": 508800,
  "sandbox_balance_remaining_micros": 1024300000,
  "guardrails_cost_micros": 1150000,
  "guardrails_cost_usd": "1.15",
  "guardrails_balance_remaining_micros": 1148850000,
  "guardrails_breakdown": {
    "pii_ml_scans": 1200,
    "injection_ml_scans": 845,
    "toxicity_ml_scans": 50,
    "code_security_scans": 0,
    "language_ml_scans": 0,
    "invisible_text_scans": 12
  }
}

​
Example — monthly spend

curl "https://api.declaw.ai/accounts/acct_abc123/usage?start=2026-04-01T00:00:00Z&end=2026-05-01T00:00:00Z" \
  -H "X-API-Key: YOUR_API_KEY"

​
Managing API keys

Every key-management action is scoped to your own owner ID.
  • POST /accounts/:owner_id/api-keys — create a new key. Optional JSON body with a name field. Returns the raw key string exactly once — store it.
  • GET /accounts/:owner_id/api-keys — list your keys (key ID, name, created-at, revoked state — never the raw key).
  • DELETE /accounts/:owner_id/api-keys/:key_id — revoke a key. Future requests using that key return 401.
The same endpoints power the key-management screen on the Declaw dashboard. Use them directly if you need to rotate keys programmatically (e.g. from CI).

​
Patterns

Low-balance alerting. Poll the account snapshot endpoint once an hour and fire an alert when sandbox_free_micros + balance_micros drops below your threshold. For Pro accounts, sub-$10 is a reasonable “top up soon” signal. Month-close reconciliation. Call the usage endpoint with start / end aligned to your accounting period. total_cost_usd and guardrails_cost_usd are pre-formatted for reports. Per-scanner cost attribution. Multiply each entry in guardrails_breakdown by the per-scan rate from Billing & Pricing to get scanner-level spend — useful when deciding whether to disable an expensive scanner in low-risk environments.