Skip to main content
POST
/
api
/
credits
/
preview
Preview credit cost for an action
curl --request POST \
  --url https://app.puffle.ai/api/credits/preview \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "action": "FIND_PERSON",
  "count": 4503599627370496
}
'
{
  "action": "DEEP_RESEARCH",
  "count": 10,
  "costPerUnit": 40,
  "totalCredits": 400,
  "totalDollars": 20,
  "sufficient": true,
  "balance": 900
}

​
Overview

A read-only pre-flight for credit-gated operations. Sends the same shape you’d send to the real endpoint (e.g., a campaign launch, a deep research run) and returns the projected credit charge plus the caller’s current balance, without actually charging or side-effecting anything. Recommended before any expensive operation: if sufficient: false, surface the deficit to the user and bail before the real call hits 402.

​
AI agent notes

Ideal for AI agents. Before kicking off an action that costs credits, call this first. If the balance is too low, tell the human rather than burning a failed call.Response shape. Returns { action, required, balance, sufficient } where required is the projected cost in credits and sufficient is balance >= required.Not a guarantee. Credit prices can change (rarely) or the action’s inputs may affect actual cost (e.g., a deep research run whose scope widens during execution). Treat this as a close estimate, not a quoted price.Related:

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

Preview request. Use this before any billable endpoint to check affordability without deducting credits.

​
action
enum<string>
required

Identifier of the billable action to preview. See GET /api/credits/config for the per-unit price of each action.

Available options:
FIND_PERSON,
IMPORT_LEAD,
EMAIL_LOOKUP,
PHONE_LOOKUP,
LINKEDIN_PROFILE,
LINKEDIN_POSTS,
COMPANY_NEWS,
PERSON_NEWS,
HIRING_STATUS,
WEBSITE_ENRICHMENT,
SITE_CRAWL_ENRICHMENT,
CUSTOM_ENRICHMENT_AI,
CUSTOM_ENRICHMENT_WEB,
DEEP_RESEARCH,
AI_MESSAGE_GENERATION,
AGENT_SEARCH,
SEARCH_CONTINUE
​
count
integer
required

Batch size — total cost is CREDIT_COSTS[action] * count. Must be a positive integer.

Required range: 1 <= x <= 9007199254740991

Response

Affordability report. Always returned when the body is well-formed — sufficient is the bit that matters.

Non-destructive affordability check. Running this does not deduct credits, open a checkout, or change state.

​
action
enum<string>
required

Identifier of the billable action to preview. See GET /api/credits/config for the per-unit price of each action.

Available options:
FIND_PERSON,
IMPORT_LEAD,
EMAIL_LOOKUP,
PHONE_LOOKUP,
LINKEDIN_PROFILE,
LINKEDIN_POSTS,
COMPANY_NEWS,
PERSON_NEWS,
HIRING_STATUS,
WEBSITE_ENRICHMENT,
SITE_CRAWL_ENRICHMENT,
CUSTOM_ENRICHMENT_AI,
CUSTOM_ENRICHMENT_WEB,
DEEP_RESEARCH,
AI_MESSAGE_GENERATION,
AGENT_SEARCH,
SEARCH_CONTINUE
​
count
integer
required
Required range: 1 <= x <= 9007199254740991
​
costPerUnit
integer
required

Credits consumed per unit for this action.

Required range: 0 <= x <= 9007199254740991
​
totalCredits
integer
required

costPerUnit * count — total credits that would be deducted.

Required range: 0 <= x <= 9007199254740991
​
totalDollars
number
required

Approximate USD face value (totalCredits * 0.05). For display only — actual billing runs through Autumn.

​
sufficient
boolean
required

true if the caller's current balance covers totalCredits. When false, either reduce count, offer to proceed with a smaller batch, or escalate to the human to upgrade.

​
balance
number | null
required

Caller's current credit balance reported by Autumn. null when Autumn is unreachable (system fails open — sufficient: true is assumed so operations aren't blocked by billing outages).