Search by task, endpoint, field, or error.
Preflight
Check access, cost and allowance before running requests.
Request
Call from your server with a secret API key. Send operation names and counts in the JSON body, rather than customer lookup values. Preflight checks access and estimates additional charges without making those lookups.
This request uses your shared per-minute rate limit. It consumes no monthly lookup allowance or metered units and reserves no allowance or money. Responses are private and must not be publicly cached.
curl "https://api.parseapi.com/preflight" \
-H "X-API-Key: YOUR_SECRET_API_KEY" \
-H "X-API-Version: 2.0.0" \
-H "Content-Type: application/json" \
--data '{
"operations": [
{
"operation": "email",
"count": 100,
"deep": true
}
],
"budget_usd": "1.00"
}'The example requests an estimate for 100 email verifications. deep: true selects verification in this estimate. To verify an address with API 2.1, use POST /email/verify.
Inputs
operationsarray- 1-20 entries. Each entry supplies an operation name and a positive integer count. The total across all entries is at most 100000 lookups.
operations[].operationstring- One of the supported operation names below. Search, lists and files are outside this estimate.
operations[].countinteger- The number of intended lookups for this operation, from 1 to 100000. Send counts, not customer lookup values.
operations[].deepboolean (optional)- Request additional detail for this operation where supported. Defaults to false in this control request. For email, true estimates verification. Preflight itself performs no verification.
budget_usdUSD string (optional)- A nonnegative decimal string with at most 12 whole-number digits and two decimal places, such as "1.00". Supply options in the JSON body. Lookup values and extra fields are rejected.
Supported operations: email, carrier, caller, hlr, domain, dns, mx, country, ip, phone, postal.
Example response
This complete synthetic example assumes 50 included email verifications remain, additional units are enabled at $0.007 each, and the request supplies a $1.00 budget. The maximum extra cost is $0.70. Applying the remaining included units projects $0.35.
{
"schema_version": "1.0.0",
"api_version": "2.0.0",
"evaluated_at": "2026-11-03T12:00:00.000Z",
"estimate_only": true,
"supported": true,
"permitted": true,
"operations": [
{
"operation": "email",
"count": 100,
"deep": true,
"permitted": true,
"reason": null,
"max_http_attempts": 1,
"pooled_requests_max": 100,
"metered_units_max": 100
}
],
"cost": {
"currency": "USD",
"status": "estimated",
"minimum_usd": "0.00",
"maximum_usd": "0.70",
"projected_maximum_usd": "0.35",
"on_demand_unit_price_usd": "0.0070"
},
"capacity": {
"pooled_requests": {
"advisory": true,
"required_max": 100,
"policy": "grace",
"limit": 1000,
"used_at_snapshot": 4,
"remaining_at_snapshot": 996,
"grace_until": null,
"reset_at": 1796083200,
"allowed_at_snapshot": true,
"status": "within_allowance"
},
"email_verifications": {
"advisory": true,
"required_max": 100,
"included_limit": 2000,
"reserved_at_snapshot": 1950,
"unallocated_included_at_snapshot": 50,
"projected_overage_units_max": 50,
"on_demand_enabled": true,
"fits_unallocated_capacity": true,
"reset_at": 1796083200
},
"shared_on_demand_spend": {
"advisory": true,
"currency": "USD",
"cap_usd": null,
"cap_status": "unlimited",
"reserved_usd_at_snapshot": "0.0000",
"unallocated_usd_at_snapshot": null,
"reset_at": 1796083200
}
},
"assumptions": [
"Costs are additional Email verification charges in USD; subscription fees, taxes and model or hosting costs are excluded.",
"Each core lookup allows at most three HTTP attempts; Email Deep allows one attempt. Extra retries or calls require a new estimate.",
"The maximum assumes every eligible Email Deep unit completes at the effective accepted rate and no included units remain; the projection uses currently unallocated included units.",
"Costs assume the same credentials, plan, accepted rates, on-demand setting and spend cap throughout execution. Authenticated terms may be cached and can change."
],
"warnings": [
"This preflight reserves no requests, verification units or money and does not enforce a task budget.",
"Capacity is advisory. Counters can lag, include unused machine leases, and change with concurrent work; a failed fit does not prove every machine is unable to serve.",
"Actual results can consume fewer verification units; cached and locally completed Email Deep results can still consume a unit.",
"Shared on-demand spend includes other metered products and is an enforcement counter, not invoiced spend. Monetary estimates round upward to cents."
],
"budget": {
"amount_usd": "1.00",
"within_maximum": true,
"enforced": false
}
}Read the estimate
Permission, allowance and budget are separate checks. A permitted operation can still lack allowance, and a budget comparison does not authorize or start work. Check cost.status and the relevant capacity statuses as well as permitted.
permitted- Whether the key and plan allow every requested operation and its detail. This does not establish enough allowance or budget.
cost- maximum_usd assumes all eligible units need an additional charge. projected_maximum_usd applies the included units remaining at this check. Amounts are USD strings, rounded upward to cents. Unit rates and spending balances use four decimal places. Null means the estimate is unavailable.
capacity- The pooled request allowance, metered units and shared spending balance at this check. Read their statuses and limits alongside the numbers. Counters may include pending work and can change.
budget- Returned only when budget_usd is supplied. within_maximum compares the conservative maximum with your amount and can be null when cost is unavailable. enforced is false: later requests are not bound to this budget.
operations- The requested counts and access reasons for each operation. max_http_attempts is the bounded retry assumption. pooled_requests_max and metered_units_max describe the maximum request and billable-unit counts; they are not reservations.
Missing balance information stays null rather than becoming zero. Read the status beside a null balance: a null cap_usd with cap_status: unlimited means no spending cap. Pooled balances can also be null when their status is unlimited or not_enforced.
The estimate covers additional lookup charges under the account's effective terms. Subscription fees and taxes are separate. The example's api_version: "2.0.0" identifies the control response format.
Limits and recovery
Allowances can change while other work runs, so an estimate does not guarantee completion. An ordinary lookup allows at most three HTTP attempts in this estimate. A metered lookup allows one. Extra calls or retries need a new estimate, and a changed key, plan, price or spending setting can change the result.
HTTP 200 can include unavailable cost or capacity information. Keep those values unknown and check again before relying on them. For HTTP 400, correct the JSON types, supported operation names and limits. For 401, check that the key is valid and active. For 403, use a secret key from your server and check the account's API access. For 429, follow Retry-After before retrying.