Know what a run costs before it starts.
Most API calls are free. Credits are spent only when an enrichment run or a list import calls a provider on Appenda's own keys.
What spends credits
| Call | Credits |
|---|---|
| Reading and changing tables, fields, records and views | None |
| A run or list import on a provider key you connected | None. The provider bills you directly. |
| A run or list import on Appenda's keys | Credits from the workspace balance, per record |
A refused request, any 4xx or 5xx | None |
A provider answer that is lost on the way back is never sent again and is not charged. When the workspace has a monthly credit cap, runs that would pass it are stopped.
When a run starts, its response's X-Credits-Cost header shows
the credits that call reserved from your balance: the most it can spend. It is
0 for a provider key you connected and for an idempotent replay of a start,
since neither reserves more credits. Unused credits return to your balance
when the run ends.
A price can be a fraction of a credit, such as 0.5 per record found. The
balance is charged in whole credits: a run or list import adds up its exact
price and rounds the total up once, so 7 records at 0.5 cost 4 credits.
Every credit amount also has a JSON number beside its integer, such as
available_decimal or credits.used_decimal. Today each one equals its
integer, and it can hold fractional credits later without changing type.
See the price first
Preview a run prices it without starting it, and charges nothing:
curl https://api.appenda.app/v1/runs/preview \
-H "Authorization: Bearer $APPENDA_API_KEY" \
-H "Content-Type: application/json" \
-d '{"kind": "enrichment", "table_id": "tbl_67ad65ba34a7bbfc643711b8531cba3f", "field_id": "fld_1e57b877a78db86124936f976015f646", "options": {"force": false, "mode": {"kind": "all"}}}'
The reply's billing_quote says what the run may spend:
| Field | Meaning |
|---|---|
credits_per_unit | Credits per charged unit, usually a record. It can be a fraction, such as 0.5. |
maximum_credits | The most the run can spend. |
billable_outcomes | Which results are charged, for example success only. A record the provider finds nothing for is free unless this list says otherwise. |
An API token can't quote or start a list import yet: both need a signed-in
session and answer 401 with session_required, and nothing is charged.
Cap what a run spends
Start the run in one call with spend_cap.max_credits. It starts only if its
price fits under the cap; otherwise nothing runs:
curl https://api.appenda.app/v1/runs \
-H "Authorization: Bearer $APPENDA_API_KEY" \
-H "Content-Type: application/json" \
-d '{"kind": "enrichment", "table_id": "tbl_67ad65ba34a7bbfc643711b8531cba3f", "field_id": "fld_1e57b877a78db86124936f976015f646", "credential_source": "managed", "options": {"force": false, "mode": {"kind": "all"}}, "spend_cap": {"max_credits": 500}}'
You can also start it with the preview token from Preview a run. A run
answers 202 and works in the background; check it with Get a run. If the
balance is too low, the start answers 402 with insufficient_credits.
Get credit usage returns runs, outcomes and credits per provider action and day.
To recover after a daily key limit or a paused key, see Job and key limits.