Run a tool

Submit a saved request with a fixed price revision, spending cap and idempotency key.

On this page

Create request.json
purrkey run
Reuse the file after interruption

Create request.json

Fill the template using the inspected contract. input must match inputSchema; maxChargeMicros must be a non-negative integer string derived from the inspected pricing unit and bounded volume. The CLI accepts balance funding only.

JSON template · replace all placeholders

{
  "toolId": "<toolId from inspect>",
  "toolRevision": "<toolRevision from inspect>",
  "priceRevision": "<priceRevision from inspect>",
  "input": {
    "<required field>": "<value matching inputSchema>"
  },
  "idempotencyKey": "<unique key saved for this task>",
  "maxChargeMicros": "<integer spending cap in USD micro-units>",
  "funding": {
    "mode": "balance"
  }
}

purrkey run

Shell

purrkey run --request request.json --wait 30s --output result.json

Flag	Meaning
--request	Required request-file path. Use - to read JSON from stdin. The raw file and the normalized request must each fit in 1 MiB.
--wait	Maximum polling time, from 0 to 10m. Default 0 returns without additional polling.
--output	Save the complete JSON response to a local file.
--api-url	Optional API-origin override for an explicitly chosen deployment.

Reuse the file after interruption

The CLI writes a recovery journal before submission. Repeating the identical request file with the same API origin and API key recovers the operation; once a Run ID has been saved, the CLI retrieves that Run directly.

A changed request under the same idempotency key is a conflict. A new idempotency key means a new task and can create another charge. Rotating the API key does not change the server-side request identity within the same account. Preserve the original file when the submission result is uncertain.

Retrieve and cancelPoll an existing Run or request cancellation.