Run an API
run_apiDestructive
Execute an API by API slug with a normalized input payload. Every input schema is strict: unknown fields are rejected, not ignored, and field names can differ between related APIs. Inputs must conform to the endpoint's schema, not its description. Published latency p50/p95/p99 and sample counts describe observed successful requests; p99 is an observation, not a maximum or a client timeout guarantee. Requires a valid AnyAPI key as a Bearer token. Charges the USD wallet. Some failed wallet-funded requests incur processing charges passed through at cost, with no markup; the error message shows the amount charged. Results can be large. fields keeps selected keys, max_items caps returned rows, and summary returns an outline; these controls reduce response size without changing the charge. max_cost_usd caps what this one request may charge, in USD: sources priced above it are skipped, and when none fits the request is refused before it runs, with no charge.
Tool call template
Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"sku_id": "<sku_id>",
"input": "<input>",
"context": "<context>"
},
"name": "run_api"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| jq | No | optional: a jq expression to reshape the result; its output replaces 'output' (multiple outputs collect into an array). Example: '.data | {title, description, md: .markdown[:3500]}'. Sandboxed 250ms/2MB budget; on failure the full result is returned with jqError. Does not change cost | |
| input | Yes | normalized input payload matching the API input schema | |
| fields | No | optional: keep only these keys on each result item - each row of the result list, or the data object itself for an API that returns one record (dotted paths like 'author.name' descend into nested objects). Shrinks the response without changing cost | |
| sku_id | Yes | the API SKU slug to execute | |
| context | Yes | Brief purpose of this tool call within the requested task, used for analytics and user-intent tracking. | |
| summary | No | optional: return only a structural outline (top-level keys, item counts, and per-field byte sizes) instead of the full data. Does not change cost | |
| max_items | No | optional: cap the number of result items returned; a _truncated note reports how many were withheld. An API that returns one record is not trimmed. Does not change cost | |
| max_cost_usd | No | optional: the most you are willing to pay for this one request, in US dollars (for example 0.05). Any source that would charge more is not used, so the request only runs on a source you can afford. If none is available at or below this amount, the request is refused before it runs, nothing is charged, and the message names the cheapest price per request so you can raise it. Leave it out to accept the normal price |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| hint | No | optional result caveat. 'large_result:' identifies a large response; fields/max_items/summary reduce response size without changing cost. 'paging_unavailable:' means the source cannot return a nextCursor, so the result may be incomplete and cannot be paged further; requireFields ["nextCursor"] restricts execution to sources that support pagination and may cost more per request. 'malformed_query:' means X interpreted adjacent bare words as ANDed and OR as having higher precedence, so a multi-word alternative is not a phrase; the result reflects that interpretation, and the hint includes a corrected query. 'date_adjusted:' means an input date was outside the platform's accepted range, so execution used the nearest accepted date named in the hint | |
| note | No | how to finish a charged request that is still running, present with collectUrl | |
| error | No | safe AnyAPI failure code when durable work failed | |
| items | Yes | number of result rows returned; an API that returns one record counts it as one row. For per-result APIs the per-item cost is charged against this; for input-priced APIs (perItemUnit != result) the charge is per submitted input, independent of this count | |
| output | Yes | normalized output payload | |
| source | No | the source that served this request; its id is the value 'source' and 'ignoreSources' accept; leave 'source' out to keep automatic routing and failover. Absent when no source identity applies | |
| status | No | durable request status: queued, running, succeeded, failed, or expired | |
| costUsd | Yes | amount charged to the wallet in USD | |
| jqError | No | present only when a jq expression failed; output then holds the full unshaped result and this explains why the reshape did not apply | |
| provider | Yes | the provider serving the request (AnyAPI) | |
| replayed | Yes | true when this response replays an identical earlier call (same API, same input) from the last few minutes instead of running again: nothing new was executed and costUsd restates the original charge, it was NOT charged a second time | |
| resultId | No | opaque handle to the full result, cached ~15 min; identifies the paid result available for free reshaping without another execution or charge. Absent when the result was too large to cache | |
| requestId | No | durable request identifier for stored status and result retrieval without repeating the paid provider dispatch | |
| collectUrl | No | present when the request was already charged and is still running: a link that reads this one request with no API key, until status is succeeded | |
| nextAction | No | stored-request retrieval coordinates and polling interval present while durable work is pending | |
| serviceOutcome | No | end-to-end AnyAPI service outcome when known | |
| settlementState | No | payment settlement state when known; independent of durable request status |