> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cloud.gomry.com/llms.txt
> Use this file to discover all available pages before exploring further.
# ToolsAPI
> Find a tool that can do a task and run it — 1,700+ across 55+ vendors, on your Gomry key.
ToolsAPI is one key over someone else's whole catalogue. Describe a task to POST /v1/toolsapi/discover and it returns the tools that can do it; POST /v1/toolsapi/run executes one and returns its output. You never sign up with the vendor, hold their key, or reconcile their invoice.
Overview
Billing is the vendor's cost plus our margin, metered in micro-dollars rather than in calls, because tools here range over four orders of magnitude in price — billing every call the same would either overcharge the cheap ones or give away the expensive ones. The `meteredMicroUsd` field in each response is exactly what went on your invoice. Discovery and inspection are billed as a flat `lookup`; polling a run is not billed at all.
A run has two independent outcomes and reading them as one is the most common mistake. `status` says whether the run completed; `upstreamStatus` says what the tool itself answered. A `succeeded` run carrying `404` is normal and means the tool looked and found nothing — that is an answer, not an error, and retrying it just pays a second vendor for the same fact.
Two failures, and the difference is whether retrying can help. `404 tool_not_runnable` means the catalogue refused this `vendor` / `endpoint` / `input` — an unchanged retry will be refused again, so check the address against `discover` and the input against `inspect`. `502 run_failed` means the catalogue could not be reached or did not answer, and retrying is exactly right. Neither is billed.
⚠️ A tool's advertised price is usually unknown, and `discover` says so rather than guessing. `price.amountMicroUsd` is `null` when the catalogue published no rate — which today is most of them — and `null` means UNKNOWN, not free. What a run cost is never a guess: `meteredMicroUsd` is the amount the vendor actually charged, returned with the result and identical to the invoice line. Read the price as a hint and the metered amount as the fact.
What it does not do: it does not translate your input between tools. `input` is passed to the tool unchanged and must match the schema `inspect` returns, so two tools that do the same job with different argument names are two different calls. It also does not guarantee a price in advance for PER\_RESULT tools — cost depends on rows returned, which is unknowable before the call, so the real ceiling is your project's monthly budget cap rather than a per-call estimate.
Endpoints
**POST /v1/toolsapi/run** — Find a tool that can do a task and run it — 1,700+ across 55+ vendors, on your Gomry key.
```bash theme={null}
curl -X POST https://api.cloud.gomry.com/v1/toolsapi/run \
-H "Authorization: Bearer $GOMRY_CLOUD_KEY" \
-H "Content-Type: application/json" \
-d '{
"vendor": "apify",
"endpoint": "/apidojo/tweet-scraper",
"input": { "handle": "gomry", "limit": 20 }
}'
```
The response reports `meteredMicroUsd` — the quantity you were metered for this call.
**POST /v1/toolsapi/discover** — Describe a task in words and get back the tools that can do it, ranked, with prices.
```bash theme={null}
curl -X POST https://api.cloud.gomry.com/v1/toolsapi/discover \
-H "Authorization: Bearer $GOMRY_CLOUD_KEY" \
-H "Content-Type: application/json" \
-d '{ "query": "scrape recent tweets from an account", "limit": 5 }'
```
The response reports `lookups` — the quantity you were metered for this call.
**POST /v1/toolsapi/inspect** — One tool's input schema, price and docs — what you need to build a valid `input`.
```bash theme={null}
curl -X POST https://api.cloud.gomry.com/v1/toolsapi/inspect \
-H "Authorization: Bearer $GOMRY_CLOUD_KEY" \
-H "Content-Type: application/json" \
-d '{ "vendor": "apify", "endpoint": "/apidojo/tweet-scraper" }'
```
The response reports `lookups` — the quantity you were metered for this call.
**GET /v1/toolsapi/runs/\{runId}** — Poll a run that came back RUNNING. Not billed — you already paid for the run.
```bash theme={null}
curl -X GET https://api.cloud.gomry.com/v1/toolsapi/runs/{runId} \
-H "Authorization: Bearer $GOMRY_CLOUD_KEY"
```
This operation is not billed.
Request options
| Field | Description |
| ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `vendor` | Required for run/inspect. Catalogue vendor slug, e.g. "apify". Monid calls this `provider`; here it is `vendor`, because `provider` already means an adapter. |
| `endpoint` | Required for run/inspect. The tool's path within that vendor, e.g. "/apidojo/tweet-scraper". Both halves come from `discover` or `inspect`. |
| `input` | Required for run. An object matching the tool's own `inputSchema` from `inspect`. Passed through unvalidated by us — the tool rejects what it does not accept. |
| `query` | Required for discover. 1–2000 characters of natural language describing the task. |
| `limit` | Discover only. How many tools to return, 1–20. Values above the ceiling are clamped, not refused. |
| `timeout` | Milliseconds before the catalogue call is abandoned. 1000–90000. The run route is capped at 120s server-side. |
Pricing
| Unit | Price |
| -------------------- | ----------------------- |
| per µ\$ of tool cost | 0.0003¢ (\$3.00 per 1M) |
| per lookup | 0.2¢ |
Only calls that returned a result are billed. Failures cost nothing. Billed monthly in arrears — see [Billing](/billing).
Authentication
Send a key as a bearer token. This service's operations require the `toolsapi:read` and `toolsapi:run` scopes, granted independently — and the project must have ToolsAPI enabled. See [Authentication](/authentication).