Credits & Usage

How much does a company search cost?

A company search costs 0.10 credits per returned row in basic mode or 1.00 credit per row in full mode, plus any signal enrichment charge. Use dry_run=true orcount_only=true to size the request without consuming credits.

Per-row costs

Examples:

• 25 companies with basic fields → 25 × 0.10 = 2.5 credits
• 25 companies with advanced fields → 25 × 1.00 = 25 credits
• 10 personnel with phone numbers (advanced) → 10 × 2.00 = 20 credits
• 10 broker offices with advanced fields → 10 × 2.00 = 20 credits
• 5 companies advanced + benchmark high_pepm → 5 × 1.00 + 5 × 10 = 55 credits
• count_only=true or dry_run=true → 0 credits (no rows returned)

Signal enrichment costs

Signals are charged per row, in addition to the base row cost. Always size queries with dry_run=true first when using benchmark signals.

Free operations

These cost 0 credits: filter-options, autocomplete, count_only=true queries.

Checking your balance

curl -H "Authorization: Bearer ss_live_..." \
  "https://api.hillwinds.ai/v1/credits"

{
  "ok": true,
  "data": {
    "total_remaining": 48250.00,
    "grants": [
      { "id": "cg_a1b2c3", "source": "negotiated", "remaining": 45000.00, "expires_at": "2027-04-22T00:00:00Z" },
      { "id": "cg_d4e5f6", "source": "promotional", "remaining": 3250.00, "expires_at": "2027-07-22T00:00:00Z" }
    ],
    "usage_today": { "credits_used": 1750.00, "rows_returned": 12400, "queries": 342 },
    "usage_this_month": { "credits_used": 28500.00, "rows_returned": 185000, "queries": 8200 }
  }
}

Credit response headers

Every response includes credit information in headers. Credits are pooled at the organization level — multiple keys in the same org draw from the same balance.

X-Org-Credits-Remaining: 48250.00
X-Credits-Charged: 25.00
X-Credits-Expiring-Soon: 3250 credits expire on 2027-07-22T00:00:00Z

X-Credits-Expiring-Soon appears only when at least one grant is within 30 days of expiry — it names the soonest-expiring amount.

When credits run out

Requests return 402 CREDITS_EXHAUSTED. Contact nate@hillwinds.xyz to add more credits. Paid data is never returned without a successful deduction; if a deduction fails after the query runs (e.g. transient lock contention), the request rolls back with 503 CREDIT_DEDUCTION_FAILED — safe to retry.