Credit Model

Every Console check has a credit cost computed from two inputs: the prompts and the number of AI platforms. The formula is deterministic, and the preview endpoint returns the exact cost before you commit.

The formula

• Prompts. If you omit keywords, SurfacedBy generates 20 prompts for the domain and the check costs a flat 20 credits. If you send your own keywords, each prompt costs 1 credit and the flat 20 does not apply: 5 prompts cost 5 credits, 60 prompts cost 60 credits. The per-check prompt maximum is in the table below.
• Platforms. Up to 3 platforms are included. Each platform beyond the third adds 20% of the prompt cost, rounded up to a whole credit at the end. If you omit platforms, the check runs on ChatGPT, Claude, and Perplexity. Any platform listed by the platforms endpoint can be selected.

Examples:

A platform that is paused is refused at submission with 422 platform_unavailable, before any credit is debited, so a check is never charged for a platform that will not run. The platforms endpoint reports a paused platform with enabled set to false.

Credit packs

Buy packs from Buy credits in the Console. Credits from every pack pool into one balance and do not expire.

The same catalog is available from GET https://api.surfacedby.com/api/v1/console/credits/packs.

Purchased credits are shared with the Credits the SurfacedBy dashboard uses for AI-written drafts in the workspace your Console account belongs to, so your ledger can also show action_consumption rows.

Who buys credits

Buying credits charges a card, so the buyer must be the member who pays for the workspace: the member billed for its subscription, or the owner when the workspace has none. Checkout also requires workspace billing access, an active workspace, a signed-in session and enabled purchases. Everyone with Console access draws on the same balance. Only the payer may change the spend cap or refill reminder. A payer check that fails returns 403 with type billing_payer_required, and the buyer field names who to ask. GET /account reports payer status through can_buy_credits and credits_buyer_name, payment access through can_verify_credit_payments, and purchase availability through credit_checkout_enabled.

Spend cap and refill reminders

The member who pays for the workspace can set, under Settings:

• A monthly spend cap (spend_cap_cents). A credit purchase that would take the current calendar month's purchases over the cap is refused at checkout. Send null to remove the cap.
• A refill reminder (auto_refill_threshold and auto_refill_pack_id). When the balance drops below the threshold, SurfacedBy emails them a link to the Console's Buy credits page, at most once every 24 hours. Nothing is charged automatically. Send null for both to turn the reminder off.

Refunds

Credits come back to your balance automatically in two cases:

• The check fails. A check that ends in the failed state is refunded in full.
• You cancel before it starts. A check cancelled while still pending is refunded in full.

Credits stay debited when a check completes, and when you cancel a check that is already running.

Each refund is a ledger row with reason refund, the check's scan_id, and a description of Refund: check failed or Refund: check cancelled. Refunds of a card payment also appear as refund rows, with a negative delta and the payment's payment_reference.

Preview before you commit

curl -X POST https://api.surfacedby.com/api/v1/console/scans/preview \
  -H "X-API-Key: sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "domain_id": "3f6c2a1e-8b4d-4c1a-9e2f-7a5b6c8d9e0f",
    "keywords": ["best crm for small teams", "crm with email tracking"],
    "platforms": ["chatgpt", "claude", "perplexity", "gemini"]
  }'

The response carries credits_required, query_count (prompts x platforms), keyword_count, platform_count, and a breakdown list of labelled line items. Preview debits nothing. It validates the body the same way a submitted check is validated, so domain_id is required.