Hillwinds API
Get access
API Reference

Credits

Check your remaining credit balance and usage history.

Requires an API-key account context
Credit endpoints require a live API key attached to a credit account. Use credits:read for balance and usage:read for usage history. Internal bearer tokens do not have an account credit pool.

Check Balance

GET/v1/credits0 credits

Returns the org's total remaining credits, every active grant with its expiration date, and rolling usage. Credits are pooled at the organization level — multiple keys in the same org draw from this single balance.

bash
curl -H "Authorization: Bearer ss_live_..." \
  "https://api.hillwinds.ai/v1/credits"
json
{
  "ok": true,
  "data": {
    "total_remaining": 48250.00,
    "grants": [
      {
        "id": "cg_a1b2c3",
        "source": "negotiated",
        "amount": 50000.00,
        "remaining": 45000.00,
        "expires_at": "2027-04-22T00:00:00Z"
      },
      {
        "id": "cg_d4e5f6",
        "source": "promotional",
        "amount": 5000.00,
        "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 }
  }
}

Expiration policy

Credits expire. Customers should know exactly when.

Grant sourceDefault expirationNotes
negotiatedPer contract — typically 12 months from issueCan be customized per deal
promotional90 days from issueOnboarding / campaign credits
manual12 months from issueSupport adjustments, goodwill

FIFO consumption ensures the soonest-expiring grants are consumed first, minimizing forfeiture as long as the org has steady usage. Forfeited credits (a grant expired with remaining > 0) are not recoverable.

X-Credits-Expiring-Soon header
Every API response includes X-Credits-Expiring-Soon when any grant has < 30 days until expiration. Format: <amount> credits expire on <ISO8601 date>. If multiple grants are expiring, the soonest is reported.

Usage History

GET/v1/credits/usage0 credits

Returns daily usage for the last 90 days. Group by day, endpoint, or API key.

Direct grouped aliases are also available at /v1/credits/usage/by-endpoint and /v1/credits/usage/by-key. Both return an empty data array when no matching usage exists; that does not alter the pooled balance returned by /v1/credits.

ParameterTypeDescription
fromstringISO date (YYYY-MM-DD). Start of the window (inclusive). Defaults to 30 days ago.
tostringISO date. End of the window (inclusive). Defaults to today.
group_byday | endpoint | api_keyHow to bucket the rows. Defaults to day.
bash
curl -H "Authorization: Bearer ss_live_..." \
  "https://api.hillwinds.ai/v1/credits/usage?from=2026-04-01&to=2026-04-22&group_by=day"
json
{
  "ok": true,
  "data": [
    { "date": "2026-04-22", "credits_used": 1750.0, "rows_returned": 12400, "queries": 342 },
    { "date": "2026-04-21", "credits_used": 980.0, "rows_returned": 7300, "queries": 218 }
  ]
}
PreviousAPI KeysNext Reports
Need a key?

Keys are issued by our team, not a signup form. Book a 25-minute walkthrough and you'll leave with sandbox and live credentials.

Get accessExplore the platform