Skip to main content
Plyne tools use workspace credits for acquisition. Describe the tool for its billing policy and call /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 the Idempotency-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 a code 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.