Skip to content
/ docs
Get API key

Call response

A call returns one JSON object: the call's ID, status and cost, with the tool's result in output. POST /v1/tools/{tool}/calls and GET /v1/calls/{call_id} return it over REST, and call_tool and get_call over MCP.

Each tool's page lists the blocks of its output: see all tools.

Fields

Every field is always present. A field marked nullable can be null.

idstring

The call's ID. Read the call again with GET /v1/calls/{call_id}.

toolstring

The tool called.

statusstring
pendingWhile providers are tried.
succeededOnce one served the call.
failedWhen none did.
failure_reasonstring· nullable

Why a failed call was not served. Null unless the call failed.

all_attempts_failedNo provider served it.
billed_provider_failureThe provider failed the call and billed it, so no other was tried.
rate_limitedEvery provider tried refused it for its rate limit; retry later.
deadline_exceededThe call ran out of time.
internal_errorNo provider served it.
abandonedThe call ran out of time.
providerstring· nullable

The provider that served the call. Null unless the call succeeded.

requested_providerstring· nullable

The provider the request named in provider. Null when it named none.

inputobject

The input as you sent it.

resolved_inputobject

The input as the tool read it: case-insensitive values lowercased, defaults filled in, and a page token as its provider issued it.

requirearray of string

The optional outputs the request required, by name.

costobject· nullable

What the call was charged, in USD. All zeros for a failed call, unless it failed billed_provider_failure. Null while the call is pending.

cost.provider_usdstring

The data provider's part of total_usd.

cost.platform_fee_usdstring

Voxoria's part of total_usd.

cost.total_usdstring

What the call cost you, drawn from your balance: the sum of the other two.

labelstring· nullable

The name you gave the call. Null when it has none.

created_atstring

When the call was made.

Format date-time.

completed_atstring· nullable

When the call succeeded or failed. Null while it is pending.

Format date-time.

outputobject· nullable

What the tool returned, in the blocks its reference lists. Null unless the call succeeded.

reusedboolean

Whether a request with reuse_within was answered with this earlier call instead of a new one. A reused call is not charged again.

Errors

A request that fails answers with an HTTP error status and one of three bodies. Branch on code, not on detail.

Refused request

A refused request. Nothing was charged. Sent with every error status not listed below, such as 402 when your balance is too low.

detailstring

What went wrong, in a sentence.

codestring

The kind of error. Branch on this, not on detail.

UNKNOWNSomething went wrong on our side.
VALIDATIONThe request is not valid. errors lists each problem.
MODEL_NOT_FOUNDThe tool or call does not exist.
NOT_ALLOWEDThe key's scope does not permit the endpoint, or the account needs a subscription.
INVALID_AUTH_TOKENThe API key is missing, wrong or revoked.
INVALID_CREDENTIALSConsole only: the email, password or signature is wrong.
TOKEN_EXPIREDConsole only: the session or link has expired.
EMAIL_NOT_VERIFIEDConsole only: the account's email is not verified yet.
DUPLICATE_EMAILConsole only: an account with this email already exists.
DUPLICATE_SLUGConsole only: an account with this slug already exists.
QUOTA_EXCEEDEDConsole only: the account has reached a limit of its plan.
INSUFFICIENT_BALANCEYour available balance cannot cover the call.
PAYMENT_PROVIDER_ERRORConsole only: the payment provider failed while serving the request.
TOOL_NOT_CALLABLEThe tool cannot be called yet.
TOOL_UNAVAILABLEThe tool or the call cannot be served right now. Not charged. Retry shortly.
NO_ELIGIBLE_PROVIDERNo provider can serve the request as sent.
TOOL_CALL_FAILEDNo provider served the call. Not charged, unless its provider billed the failure.
TOOL_CALL_TIMED_OUTThe call ran out of time. Not charged.
TEST_KEY_NOT_ALLOWEDTest keys cannot call tools yet. Use a live key.
IDEMPOTENCY_KEY_REUSEDThe idempotency key was already used with a different request.
RATE_LIMITEDToo many requests. Retry after Retry-After seconds.
PROVIDER_RATE_LIMITEDEvery provider that could serve the call refused it for its own rate limit. Not charged.
CALL_RESULT_DEFERREDThe call ran, but its result could not be returned now. Read it with GET /v1/calls/{call_id}.

Invalid request

A request that is not valid, with each of its problems. Nothing was charged. Sent with 422 and VALIDATION.

detailstring

What went wrong, in a sentence.

errorsarray of object

Each problem with the request.

errors.locarray of string or integer

Where the problem is, as a path into the request.

errors.msgstring

What is wrong there.

codestring

The kind of error. Branch on this, not on detail.

UNKNOWNSomething went wrong on our side.
VALIDATIONThe request is not valid. errors lists each problem.
MODEL_NOT_FOUNDThe tool or call does not exist.
NOT_ALLOWEDThe key's scope does not permit the endpoint, or the account needs a subscription.
INVALID_AUTH_TOKENThe API key is missing, wrong or revoked.
INVALID_CREDENTIALSConsole only: the email, password or signature is wrong.
TOKEN_EXPIREDConsole only: the session or link has expired.
EMAIL_NOT_VERIFIEDConsole only: the account's email is not verified yet.
DUPLICATE_EMAILConsole only: an account with this email already exists.
DUPLICATE_SLUGConsole only: an account with this slug already exists.
QUOTA_EXCEEDEDConsole only: the account has reached a limit of its plan.
INSUFFICIENT_BALANCEYour available balance cannot cover the call.
PAYMENT_PROVIDER_ERRORConsole only: the payment provider failed while serving the request.
TOOL_NOT_CALLABLEThe tool cannot be called yet.
TOOL_UNAVAILABLEThe tool or the call cannot be served right now. Not charged. Retry shortly.
NO_ELIGIBLE_PROVIDERNo provider can serve the request as sent.
TOOL_CALL_FAILEDNo provider served the call. Not charged, unless its provider billed the failure.
TOOL_CALL_TIMED_OUTThe call ran out of time. Not charged.
TEST_KEY_NOT_ALLOWEDTest keys cannot call tools yet. Use a live key.
IDEMPOTENCY_KEY_REUSEDThe idempotency key was already used with a different request.
RATE_LIMITEDToo many requests. Retry after Retry-After seconds.
PROVIDER_RATE_LIMITEDEvery provider that could serve the call refused it for its own rate limit. Not charged.
CALL_RESULT_DEFERREDThe call ran, but its result could not be returned now. Read it with GET /v1/calls/{call_id}.

Failed call

An error about a recorded call: call_id names it, and GET /v1/calls/{call_id} reads it. A call that ran and that no provider served was not charged, unless its provider billed the failure: then detail says what it was charged. A call whose result could not be returned (CALL_RESULT_DEFERRED) ran as recorded. Sent with 502 and TOOL_CALL_FAILED, 504 and TOOL_CALL_TIMED_OUT, or 429 and PROVIDER_RATE_LIMITED.

detailstring

What went wrong, in a sentence.

codestring

The kind of error. Branch on this, not on detail.

UNKNOWNSomething went wrong on our side.
VALIDATIONThe request is not valid. errors lists each problem.
MODEL_NOT_FOUNDThe tool or call does not exist.
NOT_ALLOWEDThe key's scope does not permit the endpoint, or the account needs a subscription.
INVALID_AUTH_TOKENThe API key is missing, wrong or revoked.
INVALID_CREDENTIALSConsole only: the email, password or signature is wrong.
TOKEN_EXPIREDConsole only: the session or link has expired.
EMAIL_NOT_VERIFIEDConsole only: the account's email is not verified yet.
DUPLICATE_EMAILConsole only: an account with this email already exists.
DUPLICATE_SLUGConsole only: an account with this slug already exists.
QUOTA_EXCEEDEDConsole only: the account has reached a limit of its plan.
INSUFFICIENT_BALANCEYour available balance cannot cover the call.
PAYMENT_PROVIDER_ERRORConsole only: the payment provider failed while serving the request.
TOOL_NOT_CALLABLEThe tool cannot be called yet.
TOOL_UNAVAILABLEThe tool or the call cannot be served right now. Not charged. Retry shortly.
NO_ELIGIBLE_PROVIDERNo provider can serve the request as sent.
TOOL_CALL_FAILEDNo provider served the call. Not charged, unless its provider billed the failure.
TOOL_CALL_TIMED_OUTThe call ran out of time. Not charged.
TEST_KEY_NOT_ALLOWEDTest keys cannot call tools yet. Use a live key.
IDEMPOTENCY_KEY_REUSEDThe idempotency key was already used with a different request.
RATE_LIMITEDToo many requests. Retry after Retry-After seconds.
PROVIDER_RATE_LIMITEDEvery provider that could serve the call refused it for its own rate limit. Not charged.
CALL_RESULT_DEFERREDThe call ran, but its result could not be returned now. Read it with GET /v1/calls/{call_id}.
call_idstring

The failed call's ID. Read the call with GET /v1/calls/{call_id}.