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

Return the exact credit cost of running an action count times, plus the caller’s current balance and whether it covers the cost. Pure read — nothing is deducted, no background work is triggered. Agents should call this before every expensive operation (lead search, deep research, LLM-powered generation, enrichment). The response tells you whether to proceed, ask the human for approval, or shrink the batch to fit the remaining balance. See the credit system in the Agent Playbook. When sufficient: false: report the shortfall to the human with a specific number, do not partially-execute, and optionally offer to proceed with a smaller batch that fits the balance. When Autumn is unreachable, the system fails open — sufficient will be true and balance null, so callers should treat a null balance as “unknown, proceed with caution.”

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).