# Models and Paid Tools API

Calling models and running paid tools from an agent account. The steps are in the Models and Paid tools guides.

## Models and paid tools

An entry runs through the route its kind already has. Each run is one action on the meter, is put to the account's controls before anything is spent, holds its worst case on the account's credit and budget, and is charged at the provider's cost, never more than was held. A refused run is never charged.

### Chat models

A model entry runs through the model gateway, at the path its entry names (for example `POST /v1/llm/openrouter/chat/completions` for a chat model, and `/embeddings`, `/audio/speech` or `/videos` for the others) with the model in the body. On an account's agent, which runs on STACK's key, the call holds its worst case on the account's credit and budget, worked out from the model's listed prices and your request. The header `X-Max-Cost-Cents` (a whole number of cents, 1 or more) is the most you accept the call to hold: the hold is lowered to it when it is below the worst case, and a call whose most cannot be worked out holds an estimate from the model's own prices. The call is then charged what OpenRouter reports it cost: the rest of the hold is given back, and a cost above the hold is taken from the account's credit at once. On a call that uses your own provider key there is nothing to hold, so the header is ignored.

### Tools

```bash
# read a tool's input schema and price first (free), then run it with /tools/run
curl -X POST https://api.getstack.run/v1/accounts/acct_123/tools/inspect \
  -H "Authorization: Bearer <access token>" -H "X-Passport-Token: $PASSPORT" -H "Content-Type: application/json" \
  -d '{"provider":"apify","endpoint":"/apify/google-search-scraper"}'
```

- POST /v1/accounts/:id/tools/discover - { query, limit? 1 to 40 }. Searches Monid's own listing. Free.
- POST /v1/accounts/:id/tools/inspect - { provider, endpoint }. The endpoint's input schema, its price, and what a run holds when that is an estimate. Free.
- POST /v1/accounts/:id/tools/run - { provider, endpoint, input?, max_results?, max_cost_cents? }. Runs any endpoint at Monid's price plus its 5% processing fee. Returns the run with untrusted and files: 200 once settled or released, 202 while pending.
- GET /v1/accounts/:id/tools/runs/:runId - one run, in the same shape. The agent or the operator reads it.

Any endpoint runs, charged Monid's price plus its 5% processing fee for the run, with its worst case held first, or an estimate where its price and input do not bound it; a cost above the hold is taken from the account's credit at once. Tools are Monid data endpoints on STACK's Monid key. Only the account's agent discovers, inspects and runs them, under its Passport; an operator credential gets 403. A run is charged at Monid's price plus its 5% processing fee from the budget, its worst case held first. An endpoint priced per result is bounded by `max_results`. `max_cost_cents` lowers the hold to it, and a cost above the hold is taken from the account's credit at once. What a tool returns is marked: web and social results are third-party content, so a run comes back with `untrusted: true`, is scanned like every tool output, and is recorded in the data trail as read, so the data-flow rule follows it like any other read. Scanned output flagged with controls on comes back withheld with its security event; with controls off it carries a `flag`. Output is not stored: each read of a run fetches it again and scans it again. A tool that makes a file saves it to the account's drive, private to the agent that ran it; the links in a page are never fetched.

A file in `files` has `name`, `content_type`, `size_bytes`, `drive_file_id`, `source_url` and `data_base64`.

- 422 TOOL_PRICE_REFUSED - max_results is outside 1 to 1000, or the input is nested too deeply to read; details.reason names why. Nothing is held or charged.
- 422 MODEL_COST_CAP - a gateway call is above its X-Max-Cost-Cents.
- 400 TOOL_RUN_REJECTED - Monid refused the input. Inspect the endpoint first. Nothing is charged.
- 503 TOOLS_UNAVAILABLE - paid tools are down on STACK's side. Nothing is charged.
- 402 AGENT_BUDGET_EXCEEDED - the budget cannot cover the run's worst case.
