Running tools

Inspect the input

Use the exact tool ID and current input schema. GET /tools/definition/{name} returns one tool with its input schema, example, providers, models and price; the catalog in the app shows the same.

A tool, provider or model with available: false cannot run for your project yet, and unavailable says why: own_key (it needs your own provider key), connection (a connected app), permission (a permission the connection lacks), setup (Relvo has not finished setting it up) or retired. Start with a small request that can establish whether the tool returns the information you need.

Follow the execution

Some tools finish quickly; others return an accepted request with an execution ID. Keep that ID and read the execution until its status is no longer queued, running or waiting.

queued
  Accepted and waiting to start.

running
  The provider is working.

waiting
  Waiting on an asynchronous provider job.

succeeded
  Finished. output holds the result.

failed
  Ended with errorCode. Partial output and charges may remain.

cancelled
  Stopped by a cancel request, its deadline or lost key access (errorCode platform_execution_cancelled), or by a connection's rule (platform_approval_required or platform_connection_policy_denied). Costs already incurred are charged.

needs_review
  The provider's charge was above the quote or could not be confirmed. The reservation is held until Relvo reviews it.

A timeout in your client does not by itself establish whether the tool ran. Check the existing execution before submitting the same paid or state-changing work again.

Read the output

output is a JSON object whose fields depend on the tool, the provider and the mode; there is no per-tool output schema. A successful call can still return data: null or found: false. When the call made one successful provider request, output is that request’s object; otherwise it is { "results": [{ "step": 0, "data": … }] }, one entry per successful provider request.

For large results, GET /tools/executions/{id}/context returns a bounded summary and POST /tools/executions/{id}/result reads one part by path, with offset, limit and maxChars.

Files and artifacts

To give a tool a local image, audio or video file, upload it first: POST /tools/upload takes mimeType and base64 data (up to 12 MiB) and returns an f_… file id for the tool’s arguments. Uploading needs a purchased balance or your own provider key in the project; a team can upload 1 GiB per 24 hours, and an uploaded file expires after 30 days.

Generated images, audio and video appear in output as artifacts with an a_… id. Their download links work for up to 5 minutes; artifacts are kept for 30 days and each can issue 10 download links per 24 hours.

Handle a failed request

Read the error and identify whether it concerns input, access, quota or the provider. Correct that cause before retrying. A failed, cancelled or needs_review execution reports its reason in errorCode.

Record the tool ID, execution ID and the error message when asking for help. Troubleshooting lists the most common checks.

Cancel a run

POST /tools/executions/{id}/cancel asks an active execution to stop and returns its state with cancelRequested: true. Work that already started may still finish, and costs already incurred are charged. Only the member who submitted it, or a project administrator, can cancel.