Calling models and running paid tools from an agent account. The steps are in the Models and Paid tools guides.
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.
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.
# 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"}'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.