Docs/API reference

Credits

Your credit balance, every credit transaction, and buying more credits with the card on file.

get /credits/balance Get the credit balancepost /credits/purchase Buy credits (charges real money)get /credits/transactions List credit transactions

Get the credit balance

get https://api.emailchaser.com/r/credits/balance
Works with a read-only key

Returns the workspace's credit wallet. A wallet is created empty on first use, so a new workspace sees zeros rather than an error; a workspace on a free trial sees its one-time trial credits, which its first balance read hands over. unlimited is true when Emailchaser has made this workspace's credits free: credit actions then never spend available and are never refused for lack of credits, so there is no need to check the balance or buy credits.

Responses

Fields in the 200 response
  • available integer
    Example: 1500
  • lifetimeGranted integer
    Example: 5000
  • lifetimeUsed integer
    Example: 3400
  • monthlyGrant integer
    Example: 2000
  • reserved integer
    Example: 100
  • unlimited boolean

    Unlimited is true when this workspace's credits are free: every credit action goes through without spending available, nothing is refused for lack of credits, and POST /credits/purchase is refused (code credits_free) because there is nothing to buy.

    Example: false

Request

curl -X GET "https://api.emailchaser.com/r/credits/balance" \
  -H "Authorization: Bearer $EMAILCHASER_API_KEY"

Response

{
  "available": 1500,
  "lifetimeGranted": 5000,
  "lifetimeUsed": 3400,
  "monthlyGrant": 2000,
  "reserved": 100,
  "unlimited": false
}

Buy credits (charges real money)

post https://api.emailchaser.com/r/credits/purchase
Needs a read and write key

CHARGES REAL MONEY: this immediately charges the workspace's saved default payment method (the card behind the active subscription), off-session, with no confirmation step beyond this call. Buys between 1000 and 10000 prospect credits at the tiered list price ($33 per 1000 credits, $20 per 1000 from 5000 credits) and grants them to the wallet on success. Responds with the credits bought, the exact amount charged in USD and the new available balance. Errors carry a machine-readable code: billing_required (402, no active subscription or saved card - fix billing in the app first), payment_failed (402, the charge was refused - no money moved), credits_free (409, this workspace's credits are free, so nothing is charged and there is nothing to buy), invalid_request (400), temporarily_unavailable (503, the purchase stopped before any charge - safe to retry), purchase_incomplete (500, charged but not credited, support already notified - do NOT retry) and purchase_unconfirmed (500, check /credits/transactions before retrying). The grant is idempotent on the Stripe invoice, so one charge can never double-credit - but every successful call is a NEW charge.

Request bodyJSON · PurchaseCreditsRequest

  • credits integer required

    Credits is how many prospect credits to buy. Minimum 1000, maximum 10000 per call.

    Example: 5000

Responses

Fields in the 200 response
  • amountUsd number

    AmountUsd is what the saved default payment method was charged, in US dollars.

    Example: 100
  • creditsPurchased integer

    CreditsPurchased is how many credits were bought and granted.

    Example: 5000
  • newBalance integer

    NewBalance is the available credit balance after the grant.

    Example: 5000

Request

curl -X POST "https://api.emailchaser.com/r/credits/purchase" \
  -H "Authorization: Bearer $EMAILCHASER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "credits": 5000
}'

Response

{
  "amountUsd": 100,
  "creditsPurchased": 5000,
  "newBalance": 5000
}

List credit transactions

get https://api.emailchaser.com/r/credits/transactions
Works with a read-only key

Lists the workspace's credit ledger entries, newest first. Optional filters: kind (movement type), reason (what the credits were for), and since/until on the entry time (both inclusive, RFC3339 or YYYY-MM-DD where a bare date means midnight UTC at the start of that day). Without filters the full ledger is returned as before. An entry with free=true was written while the workspace's credits were free: its amount is what the action would have cost, and no credits moved.

Parameters

  • limit integer in query

    Page size (default 50, max 200)

  • page integer in query

    Page number, 1-based (default 1)

  • kind string in query

    Filter by movement type: grant, topup, reserve, commit, refund, expire or adjustment

  • reason string in query

    Filter by reason: monthly_grant, prospect_reveal, ai_icp, ai_sequence, ai_reply, stripe_topup or manual_adjustment

  • since string in query

    Only entries at or after this time, RFC3339 or YYYY-MM-DD

  • until string in query

    Only entries at or before this time, RFC3339 or YYYY-MM-DD (a bare date means midnight UTC at the start of that day)

Responses

Fields in the 200 response
  • total integer
    Example: 12
  • transactions array of CreditTransactionItem
    9 fields inside transactions
    • amount integer

      Amount is the signed credit delta: negative for spend, positive for grants and refunds.

      Example: 2000
    • balanceAfter integer

      BalanceAfter is the available balance immediately after this entry.

      Example: 2000
    • createdAt string
      Example: 2026-07-01T10:30:00Z
    • description string
      Example: Monthly plan credits
    • free boolean

      Free is true for an entry written while this workspace's credits were free. Its amount is what the action would have cost, no credits moved, and balanceAfter is the balance it found.

      Example: false
    • id integer
      Example: 42
    • kind string

      Kind is the movement type: grant, topup, reserve, commit, refund, expire or adjustment.

      Example: grant
    • reason string

      Reason is what the credits were spent on or granted for.

      Example: monthly_grant
    • reference string

      Reference correlates the entry to what caused it, e.g. 'prospect_search:123'.

Request

curl -X GET "https://api.emailchaser.com/r/credits/transactions" \
  -H "Authorization: Bearer $EMAILCHASER_API_KEY"

Response

{
  "total": 12,
  "transactions": [
    {
      "amount": 2000,
      "balanceAfter": 2000,
      "createdAt": "2026-07-01T10:30:00Z",
      "description": "Monthly plan credits",
      "free": false,
      "id": 42,
      "kind": "grant",
      "reason": "monthly_grant",
      "reference": "string"
    }
  ]
}

Generated from the Emailchaser API's own OpenAPI definition, so it always matches the running API.