Billing

HatiData uses a credit-based billing model. Queries consume credits based on complexity (tables scanned, rows returned, query type). The billing API provides usage tracking and quota management.

Get Usage

GET /v1/organizations/{org_id}/billing/usage

Returns usage metrics for the current billing period. Accessible to Owner role.

Request:

curl https://api.hatidata.com/v1/organizations/org_a1b2c3d4/billing/usage \
  -H "Authorization: Bearer <jwt>"

Response 200 OK:

{
  "org_id": "org_a1b2c3d4",
  "tier": "cloud",
  "billing_period": {
    "start": "2026-02-01T00:00:00Z",
    "end": "2026-02-28T23:59:59Z"
  },
  "credits": {
    "limit": 10000,
    "used": 3250,
    "remaining": 6750,
    "usage_percent": 32.5
  },
  "breakdown": {
    "queries": {
      "total": 45200,
      "select": 42100,
      "insert": 2800,
      "update": 200,
      "delete": 100
    },
    "by_environment": [
      {
        "env_id": "env_prod_x1y2",
        "name": "production",
        "credits_used": 2800,
        "query_count": 38000
      },
      {
        "env_id": "env_stg_a3b4",
        "name": "staging",
        "credits_used": 450,
        "query_count": 7200
      }
    ],
    "by_day": [
      {
        "date": "2026-02-15",
        "credits_used": 210,
        "query_count": 3100
      },
      {
        "date": "2026-02-16",
        "credits_used": 185,
        "query_count": 2800
      }
    ]
  },
  "storage": {
    "total_gb": 125.4,
    "limit_gb": 500
  }
}

Query Parameters

Parameter	Type	Default	Description
start_date	string (ISO 8601)	Billing period start	Start of date range
end_date	string (ISO 8601)	Today	End of date range
group_by	string	day	Breakdown granularity: hour, day, week

Get Quotas

GET /v1/organizations/{org_id}/billing/quotas

Returns current quota settings for the organization. Accessible to Owner role.

Request:

curl https://api.hatidata.com/v1/organizations/org_a1b2c3d4/billing/quotas \
  -H "Authorization: Bearer <jwt>"

Response 200 OK:

{
  "org_id": "org_a1b2c3d4",
  "tier": "cloud",
  "quotas": {
    "monthly_credit_limit": 10000,
    "max_concurrent_queries": 100,
    "max_rows_per_query": 1000000,
    "storage_limit_gb": 500,
    "max_environments": 5,
    "max_users": 25,
    "max_api_keys_per_environment": 50
  },
  "alerts": {
    "credit_warning_threshold": 0.8,
    "credit_critical_threshold": 0.95,
    "storage_warning_threshold": 0.9
  }
}

Tier Quotas

Quota	Free	Cloud	Growth	Enterprise
Monthly credits	1,000	10,000	100,000	Custom
Concurrent queries	10	100	500	Custom
Max rows/query	100,000	1,000,000	10,000,000	Unlimited
Storage (GB)	10	500	5,000	Custom
Environments	1	5	20	Unlimited
Users	3	25	100	Unlimited
API keys/env	5	50	200	Unlimited

Update Quotas

PUT /v1/organizations/{org_id}/billing/quotas

Updates quota settings. Only the alerts thresholds can be modified directly -- credit and storage limits are determined by the subscription tier. Requires Owner role.

Request:

curl -X PUT https://api.hatidata.com/v1/organizations/org_a1b2c3d4/billing/quotas \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  -d '{
    "alerts": {
      "credit_warning_threshold": 0.7,
      "credit_critical_threshold": 0.9,
      "storage_warning_threshold": 0.85
    }
  }'

Response 200 OK:

{
  "org_id": "org_a1b2c3d4",
  "alerts": {
    "credit_warning_threshold": 0.7,
    "credit_critical_threshold": 0.9,
    "storage_warning_threshold": 0.85
  },
  "updated_at": "2026-02-16T10:00:00Z"
}

Field	Type	Description
alerts.credit_warning_threshold	float	Send warning webhook at this usage percentage (0.0-1.0)
alerts.credit_critical_threshold	float	Send critical alert at this usage percentage
alerts.storage_warning_threshold	float	Send warning when storage reaches this percentage

Webhook Alerts

Billing alerts are delivered via webhooks. Configure a webhook with the billing.warning and billing.critical event types to receive notifications.

Billing Events

The following billing-related events are emitted:

Event	Trigger
billing.warning	Usage reaches the warning threshold
billing.critical	Usage reaches the critical threshold
billing.quota_exceeded	Usage exceeds the monthly credit limit
billing.period_reset	Monthly billing period resets

Error Responses

Status	Code	Description
401	UNAUTHORIZED	Missing or invalid authentication
403	FORBIDDEN	Insufficient role (must be Owner)
404	NOT_FOUND	Organization not found
422	VALIDATION_ERROR	Invalid threshold values