Billing & usage

Understand how API billing works and monitor your costs.

Pricing

API requests are billed per request:

Endpoint type	Cost per request	Example
Standard endpoints	$0.002	Trading, usage, billing
Private company endpoints	$0.02 (10x)	Company data, search

Cost examples

Usage scenario	Requests	Cost
Check 10 valuations per day for a month	300	$0.60
Fetch private company data 100 times	100	$2.00
Trading bot making 1,000 requests/day for a month	30,000	$60.00
Research project: 500 company lookups	500	$10.00

Check current pricing

curl "https://api.vaulto.ai/api/pricing"

This public endpoint returns:

{
  "pricing": {
    "unit": "per 1,000 requests",
    "amountUsd": 2.00,
    "currency": "USD"
  },
  "costPerRequestUsd": 0.002
}

Per-request cost header

Every API response includes the cost in the X-Request-Cost-USD header:

X-Request-Cost-USD: 0.002

For private company endpoints, this shows the higher rate:

X-Request-Cost-USD: 0.02

Tracking usage

View usage records

curl -H "x-api-key: YOUR_KEY" \
  "https://api.vaulto.ai/api/usage?limit=100"

Each record includes costUsd and currency:

{
  "records": [
    {
      "path": "/api/trading/valuation",
      "method": "GET",
      "timestamp": "2024-01-15T10:30:00Z",
      "costUsd": 0.002,
      "currency": "USD"
    }
  ]
}

Filter by date range

curl -H "x-api-key: YOUR_KEY" \
  "https://api.vaulto.ai/api/usage?from=2024-01-01&to=2024-01-31"

Get billing summary

curl -H "x-api-key: YOUR_KEY" \
  "https://api.vaulto.ai/api/billing"

Returns your current balance and usage:

{
  "usageCount": 1250,
  "usageCostUsd": 2.50,
  "balanceUsd": 97.50,
  "costPerRequestUsd": 0.002
}

Account balance

Your account must have a positive balance to make API requests.

Adding funds

1. Log in to the Dashboard
2. Navigate to Billing or Account
3. Use Fund with USDC to add funds

Insufficient balance

If your balance is zero, you'll receive a 402 Payment Required error:

{
  "code": "INSUFFICIENT_BALANCE",
  "message": "Account balance is zero. Add funds in the dashboard.",
  "status": 402
}

Stripe integration

For automated billing, usage can be synced to Stripe for metered subscriptions. Contact support for setup details.

Best practices

1. Monitor costs — Check GET /api/billing regularly
2. Set up alerts — Track the X-Request-Cost-USD header in your code
3. Batch when possible — Use pagination to reduce request count
4. Cache responses — Cache data that doesn't change frequently