> ## Documentation Index
> Fetch the complete documentation index at: https://docs.declaw.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Usage & Monitoring
> Read your account's balances, aggregate cost over a time range, and break down guardrails scans by scanner. Useful for budget dashboards, alerts, and reconciling invoices.
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.
```bash theme={null}
curl https://api.declaw.ai/accounts/acct_abc123 \
-H "X-API-Key: YOUR_API_KEY"
```
### Response
Account identifier.
Account email.
One of `free`, `pro`, `enterprise`.
Account creation timestamp (RFC3339, UTC).
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.
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.
Remaining sandbox free credits in microdollars. Starts at 100000000 ($100) at account creation. Remaining guardrails free credits in microdollars. Starts at 200000000 ($200).
Paid balance in microdollars. Topped up by deposits.
```json Response theme={null}
{
"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
Window start (RFC3339). Defaults to 30 days ago.
Window end (RFC3339). Defaults to now.
Backward-compatible alias for `start`. Ignored if `start` is set.
### Response
Account identifier.
Effective window start (RFC3339 UTC).
Total sandbox compute cost for the window, in microdollars.
Convenience string: `total_cost_micros / 1000000` formatted to 2 decimal places.
Number of distinct sandboxes metered in the window.
Total sandbox-seconds consumed.
Sum of `sandbox_free_micros + balance_micros` at the time of the query.
Total guardrails scan cost in the window. Present only when the guardrails store is available.
USD-formatted equivalent.
Sum of `guardrails_free_micros + balance_micros`.
Per-scanner scan counts: `pii_ml_scans`, `injection_ml_scans`, `toxicity_ml_scans`, `code_security_scans`, `language_ml_scans`, `invisible_text_scans`.
```json Response theme={null}
{
"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
```bash theme={null}
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](/platform/billing#guardrails-scan-pricing) to get scanner-level spend — useful when deciding whether to disable an expensive scanner in low-risk environments.