/plan for the maximum quote at your chosen settings. Preserve the request body and key until the operation reaches a terminal result.
Plan, reserve and settle
A displayed base price describes the tool’s default settings. Limits and source-specific settings can change the quote. Use the current plan rather than multiplying a catalog price without reading the billing policy.
Know the billing unit
For example, Search jobs reserves up to
limit times its per-record rate and charges for returned jobs. Other tools bill in source blocks or use a fixed quote. Empty acquisition results are not universally free: company enrichment explicitly bills completed and not-found lookups. Read the policy of the tool you call.
usage.credit_units is the integer ledger amount and usage.credits is its credit representation. These are Plyne credits, not the upstream service’s units.
Keep one key per operation
Execute uses theIdempotency-Key header. MCP uses idempotency_key inside the tool arguments. A key contains 8–128 ASCII letters, digits, underscores or hyphens.
Keep both the original request body and key. Reuse them to retrieve that operation, including after a client disconnect. A new logical acquisition or a subsequent page needs a new key. Reusing an existing key with a different normalized request produces an idempotency_conflict.
Recover an interrupted call
1
Keep the original request
A timeout, missing response or unavailable connection does not prove that no paid work started. Retain the same body and key.
2
Retrieve the same operation
Call execute again with the original body and key. A completed operation returns its saved result. A pending operation can return its current progress.
3
Inspect the status
For
pending or in_progress, keep the operation identity. An unresolved provider acceptance may require reconciliation; do not create a replacement key merely to force another attempt.4
Start new work deliberately
Use a new key when you intend a separate acquisition, rather than as a retry for an operation whose outcome is still unknown.
Separate request errors from tool outcomes
An HTTP error has acode and message. A valid execution response also carries a tool status, so HTTP 200 alone does not mean data was found.
See source chains for fallback behavior and tool execution for pagination and the shared response envelope.