# Gomry Cloud > Developer APIs from Gomry. Metered per request, priced per unit, billed monthly — no plans, no seats, no free tier to outgrow. This file is the complete public documentation for Gomry Cloud, concatenated into one document: 18 pages, each identical to the Markdown served at its own URL with a `.md` suffix. The index of these pages, with one-line descriptions, is at https://cloud.gomry.com/llms.txt. The machine-readable description of the API itself is at https://cloud.gomry.com/openapi.json. The data plane every example calls is documented against its real host. The documentation is served from https://docs.cloud.gomry.com and each document below states its canonical URL. It is reproduced here in full so that one fetch of this file answers everything — https://docs.cloud.gomry.com/llms-full.txt is the same corpus published by the docs site itself. Prices below are read from the live rate table at build time. For anything a customer will be invoiced for, https://docs.cloud.gomry.com/pricing is the page that is refreshed most often. --- # Pricing > What Gomry Cloud costs: the per-unit rate for every API operation, billed monthly in arrears with no plans, seats or minimums. Source: https://docs.cloud.gomry.com/pricing You pay for the units you consume, at the same rate from the first request to the millionth. No plans, no seats, no minimum, and no free tier to outgrow. ## Rates | Service | Unit | Price | | --- | --- | --- | | Scrape | per page | $0.02 | | Scrape | per fetch | 0.5¢ | | ToolsAPI | per µ$ of tool cost | 0.0003¢ ($3.00 per 1M) | | ToolsAPI | per lookup | 0.2¢ | | Superagent | per task | $0.15 | | Superagent | per source | $0.02 | | Superagent | per round | $0.05 | | Ember | per input token (cheap) | 0.00011¢ ($1.10 per 1M) | | Ember | per output token (cheap) | 0.0009¢ ($9.00 per 1M) | | Ember | per input token (balanced) | 0.00055¢ ($5.50 per 1M) | | Ember | per output token (balanced) | 0.0028¢ ($28.00 per 1M) | | Ember | per input token (strong) | 0.00055¢ ($5.50 per 1M) | | Ember | per output token (strong) | 0.0028¢ ($28.00 per 1M) | Operations within one service are priced separately because they cost separately — rendering a page and running a structured extraction over it are not the same work, so they are not the same rate. ## What you pay for - **Only results.** A failed, timed-out or refused request is never billed. - **Per unit, per month.** Usage accrues over the calendar month and is invoiced to your card at the end of it. Every response tells you the quantity it metered, in the same payload as the result — so what you were charged is visible at the call site, not only on the invoice. ## What a Superagent task costs Superagent is the one service billed on more than one dimension: a flat unit for the task itself, one per source it fetched and extracted, and one per reasoning round it completed. A task that reads less costs less, and the totals below are the worst case at each tier — the ceiling, not the estimate. | Tier | Sources (max) | Rounds (max) | Most it can cost | | --- | --- | --- | --- | | lite | 3 | 0 | 20.29¢ | | standard | 15 | 2 | 51.71¢ | | deep | 100 | 6 | $2.26 | A task that fails before producing output is not charged the task unit, but the sources it already fetched and the rounds it already ran are charged — that work really happened. Narrow `maxSources` in the request body to cap it below the tier, or set a project budget cap to bound the month. ## Common questions ### What is Gomry Cloud? Gomry Cloud sells the technical services Gomry built to run its own event platform as metered HTTP APIs. You authenticate with an API key, call a JSON endpoint, and are billed per unit consumed — currently web page fetching and structured data extraction. ### How is Gomry Cloud priced? Per unit, postpaid. Each operation has its own per-unit rate, usage accrues over the calendar month, and the total is invoiced to your card at the end of it. There are no plans, no seats and no minimum commitment. ### Is there a free tier? No. Every request carries real upstream cost the moment it runs, so an active payment method is required before any API will serve. Free usage, when granted, is a credit on the account that applies to any service and runs out, rather than a permanent free allowance. ### Am I charged for failed requests? No. Only work that produced a result is billed. Validation errors, authentication failures, rate limits, timeouts and upstream failures all cost nothing, and every response reports the quantity it metered in its own body. ### What does it cost to develop against Cloud? Every request is billed at the same per-unit rate, including the ones you make while integrating — there is no separate development tier. In practice wiring up an integration costs cents, because only work that produced a result is billed and a few hundred calls is a few hundred units. Set a budget cap on the project to put a hard ceiling under it. ### How do I stop a runaway job from spending too much? Set a monthly budget cap on the project. It is evaluated before each request against the calendar month's spend in UTC, and can either block further requests with a 402 or allow them and flag the overage. ## Controlling spend Each project can carry a monthly budget cap, checked before the work runs, that either blocks or flags requests once the month's spend reaches it. It is the control that bounds a runaway loop, and setting one on day one is the recommendation. See [Billing](https://docs.cloud.gomry.com/billing) for how caps, invoicing and payment failures behave. > **Note:** Cloud is postpaid, so an active payment method is required before any API will serve. There is no free tier and no development tier: every request carries real upstream cost the moment it runs, and is billed at the same rate whoever makes it. --- # Quickstart > Create a project, enable an API, mint a key and make your first billable Gomry Cloud request in about two minutes. Source: https://docs.cloud.gomry.com/quickstart Every Gomry Cloud request needs three things: a **project**, the **API enabled** on that project, and a **key** scoped to the operation you are calling. This page gets you all three and a first response. ## Before you start You need a Gomry account and an organization with a payment method. Cloud is postpaid and metered: there is no free tier, and an organization with no card on file is refused at the gateway with `billing_required` before any work is done. See [Billing](https://docs.cloud.gomry.com/billing) for why the card comes first. ## Make your first request 1. **Create a project** — A project is the unit of isolation and of spend: keys, enabled APIs, usage and the monthly budget cap all belong to one. Most teams run one per environment — `production` and `staging` — because that is the boundary you want a budget and a key revocation to respect. 2. **Enable the API on that project** — Open [Services](https://docs.cloud.gomry.com/services), pick the one you want and turn it on for the project. Enabling is separate from key scopes on purpose: a key minted with a broad scope still cannot reach an API this project never enabled. 3. **Mint a key** — Grant it only the scopes you will call. The plaintext key is shown **once** and never again — store it in your secret manager now. Set a monthly budget on the project at the same time: it is the ceiling on everything this key can spend. 4. **Call the API** — Send the key as a bearer token. Endpoints take and return JSON. Most are `POST`; the ones that read or stop work already started are `GET` and `DELETE`. ```bash export GOMRY_CLOUD_KEY=gck_live_... curl -X POST https://api.cloud.gomry.com/v1/fetch \ -H "Authorization: Bearer $GOMRY_CLOUD_KEY" \ -H "Content-Type: application/json" \ -d '{ "url": "https://example.com" }' ``` ## Reading the response Every response carries an `x-request-id` header. Log it: it is the one identifier that ties your call to our records of it, and the first thing support will ask for. Every response body also tells you what it metered — `fetches` here, `pages` for an extraction. That field is the quantity that reaches your invoice, in the same payload as the result, so you never have to infer what you were charged. Response: ```json { "rawHtml": "...", "metadata": { "title": "Example Domain" }, "fetches": 1 } ``` ## Going live There is nothing to swap. The key you integrated with is the key you run in production — same URL, same body, same response shape — so going live is a deployment, not a migration. What changes is the traffic you point at it. > **Important:** Set a monthly budget on the project before you point production traffic at it. A project with no limit is capped only by your card. See [Billing](https://docs.cloud.gomry.com/billing). --- # Authentication > How Gomry Cloud API keys work: the gck_live_ format, scopes per operation, and the two independent checks every request passes. Source: https://docs.cloud.gomry.com/authentication Gomry Cloud authenticates machines with API keys, sent as a bearer token. There is no session, no OAuth flow and no browser-facing credential — a Cloud key is a server-side secret. ## Sending a key ```http POST /v1/scrape HTTP/1.1 Host: api.cloud.gomry.com Authorization: Bearer gck_live_... Content-Type: application/json ``` > **Important:** Never put a Cloud key in browser JavaScript, a mobile app, or anything else you ship to a user. The data plane sends no CORS headers, deliberately — a key that a browser can read is a key anyone can spend. ## Key format A key is the `gck_live_` prefix plus 32 random bytes. There is one kind of key: it does the work and bills for it. Spend is bounded by the project's monthly budget cap, not by the credential. > **Important:** `gck_test_` keys are retired. They ran the real request against the real upstream and were simply not invoiced, which made "test" a promise of a sandbox that never existed. Existing ones no longer authenticate — mint a replacement in the console. We store only a SHA-256 hash of the key. The plaintext is returned once, at mint time, and cannot be recovered — if it is lost, revoke it and mint another. The console shows a key by its prefix and last four characters, which is enough to tell two keys apart and useless to anyone who steals the display. ## Scopes A scope names exactly one operation a key may perform, in the form `service:action`. A key carries the scopes you grant it and nothing else. - `scrape:run` — Call POST /v1/scrape — render a page and extract structured data from it. - `scrape:fetch` — Call POST /v1/fetch — render a page and return its HTML and metadata. - `toolsapi:read` — Search and inspect the tool catalogue — POST /v1/toolsapi/discover, POST /v1/toolsapi/inspect, and polling a run with GET /v1/toolsapi/runs/{runId}. Reads only; it cannot execute anything. - `toolsapi:run` — Call POST /v1/toolsapi/run — execute a tool and pay its upstream cost. This is the scope that spends: grant it separately from toolsapi:read. - `tasks:run` — Call POST /v1/superagent — start a research task. This is the scope that spends, and it commits to work that continues after the request returns. - `tasks:read` — Poll a task with GET /v1/superagent/{taskId} and stop one with DELETE. Neither is billed, so a worker that only collects results needs nothing more than this. - `inference:run` — Call POST /v1/inference — one model call, billed per input and output token at the capability you asked for. Nothing implies it: it is the only scope whose cost per call is set by how much you send rather than by the operation, so a key that may run a task must still be granted this to call the model directly. > **Important:** Scopes are flat: there are no wildcards, and `scrape:run` does **not** imply `scrape:fetch`. They are separately priced operations, so they are separately granted — a key minted for a cheap fetch loop must not be able to spend four times the rate on extractions. ## Two independent checks A request is authorized by two separate facts, and both must hold. They fail with different codes so you can tell them apart without guessing. | Check | Failure | Fix | | --- | --- | --- | | The key carries the scope for this operation | `403 forbidden` | Mint a key with the scope, or grant it. | | The project has this API enabled | `403 api_not_enabled` | Turn the API on for the project in the console. | Keeping them separate is what stops each from silently widening the other: enabling an API must not grant new power to keys that already exist, and a broadly scoped key must not reach an API the project never turned on. ## Rotation and revocation Revocation takes effect on the next request — there is no cache of authorization decisions to wait out. To rotate without downtime, mint the new key, deploy it, then revoke the old one. A key can also be given an expiry at mint time, which is the better default for anything handed to a third party. --- # Errors > Every error code the Gomry Cloud API returns, what causes it, whether it is retryable, and whether the failed request was billed. Source: https://docs.cloud.gomry.com/errors Errors are JSON, with a stable machine-readable `error` code and a human `message`. Branch on the code — the message is written for a person and may be reworded. ## The shape ```json { "error": "api_not_enabled", "message": "scrape is not enabled for this project. Enable it in the console." } ``` The `x-request-id` header is present on errors too, including on a `500`. Capture it — without it a report of an intermittent failure cannot be traced back to the request that produced it. ## Codes | Status | Code | Meaning | | --- | --- | --- | | 400 | `validation_error` | The body failed schema validation. `details.issues` names the fields that failed, by path — never their values. | | 401 | `unauthorized` | Key missing, malformed, unknown, revoked or expired. | | 403 | `forbidden` | The key is valid but lacks the scope for this operation. | | 403 | `api_not_enabled` | The project has not enabled this API. | | 404 | `not_found` | The addressed resource does not exist, or is not yours to see. | | 409 | `conflict` | The request conflicts with the current state — a name already taken, for example. | | 402 | `billing_required` | The organization has no payment method. Add a card. | | 402 | `billing_past_due` | The last invoice could not be collected. Update the card. | | 402 | `billing_suspended` | Billing is suspended. Contact support. | | 402 | `insufficient_credit` | The project reached its monthly budget cap. | | 429 | `rate_limited` | Too many requests for this key. Back off and retry. | | 502 | `upstream_error` | A provider we depend on failed. | | 503 | `provider_unavailable` | The service is not currently configured to serve. Retry. | | 500 | `internal_error` | A fault on our side. Retry, and send us the request id. | Individual services add codes of their own for a failure that is specific to them — `scrape_failed` and `fetch_failed` are both `502` and both mean the page could not be retrieved. They are documented on each [service's page](https://docs.cloud.gomry.com/services). A `400` carries a `details` object naming what was wrong: `{"error":"validation_error","message":"Invalid request body","details":{"issues":["prompt"]}}` means the `prompt` field failed. Only validation errors carry it, and only field names, allowed values and limits — never the values you sent, and never anything about your organization. ## What a failure costs > **Note:** Only work that produced a result is billed. A validation error, an auth failure, a rate limit, a timeout, or an upstream failure costs nothing. Failed requests are still recorded, so they appear in your usage dashboard with their status — you can see a spike of `429`s without being charged for it. The quantity billed is what the handler actually consumed, which is why a partially successful call (an extraction that needed a retry) reports exactly what it used in the response body. ## Retrying - Retry `429`, `500`, `502` and `503` with exponential backoff and jitter. - Do not retry `400`, `401` or `403` — the same request will fail identically until you change something. - Do not retry `402` in a loop. It means spending is blocked until a human adds a card, fixes one, or raises a budget. - Retries are billed like any other request: a successful retry of a failed call is one billable unit, because the failed attempt was free. --- # Rate limits > Gomry Cloud rate limits per API key, not per IP: the default budget, the headers to read, and how to back off correctly. Source: https://docs.cloud.gomry.com/rate-limits Rate limits are applied **per API key**, using a sliding window. ## Per key, never per IP An IP-based limit is wrong in both directions: several customers behind one NAT throttle each other, and a caller distributed across many addresses evades it entirely. A key is the unit you control, so it is the unit we limit. Running two workers? Give them a key each and they get a budget each. ## Headers Every rate-limited response carries your remaining budget. Read these rather than counting requests yourself — the window slides, so your count and ours will not agree. - `x-ratelimit-remaining` — Requests left in the current window for this key. - `x-ratelimit-reset` — Unix timestamp in milliseconds at which the window resets. Exceeding the limit returns `429 rate_limited`. Back off until `x-ratelimit-reset`, with jitter — retrying the instant the window opens is how a fleet of workers synchronises itself into a thundering herd. ## Limits The default is 120 requests per minute per key. If your workload needs more, ask — the limit exists to protect shared upstream capacity, not to sell you a tier. > **Note:** A rate limit is not a spend control. It caps the rate of requests, not their cost. To bound what a project can spend, set a monthly budget — see [Billing](https://docs.cloud.gomry.com/billing). --- # Versioning and deprecation > How Gomry Cloud versions its API, what counts as a breaking change, and the notice and headers you get before anything is withdrawn. Source: https://docs.cloud.gomry.com/versioning The API is versioned by its **`/v1` path prefix**, which is the contract you code against. This page says what we may change inside it without telling you, what we may not, and how you find out before something goes away. ## What the version covers `/v1` is the whole data plane. There is no date-pinned version, no `Api-Version` header and no per-account pin — one live contract, and the machine-readable description of it is at [/openapi.json](https://cloud.gomry.com/openapi.json). That document's own `info.version` is its revision, not the API's; branch on the path prefix, never on that number. ## What we may change without notice Anything a correctly written client already tolerates. **Write your client to ignore fields it does not recognise** — that single habit is what makes every change below safe for you. - New endpoints, and new optional request fields. - New fields in a response body, and new values in a field that is already documented as open-ended. - New error codes, within a status you already handle. Branch on the code, treat an unknown one as the class its status implies. - New response headers. - Rate-limit defaults, and the per-unit rates — rates are published at [Pricing](https://docs.cloud.gomry.com/pricing) and always render from the live price list. A change there is a price change, not an API change. - Wording of any `message`. It is written for a person and may be rewritten at any time. ## What counts as breaking - Removing or renaming an endpoint, a request field, a response field or an error code. - Narrowing what a request field accepts, or making an optional field required. - Changing the type or the meaning of an existing field. - Changing which scope an operation requires. - Changing the unit an operation is metered in — the rate may move freely; what the unit *counts* may not. > **Important:** Service **identifiers** never change even when display names do. `scrape`, `toolsapi` and `tasks` are written into live API keys, usage records and scope strings — the name a page shows you and the identifier the contract uses are allowed to disagree, and `tasks` / Superagent already do. ## Notice, and the headers that carry it A breaking change ships as a new path prefix — `/v2` — and never as an edit to `/v1`. Once a successor exists, the older operation is marked deprecated and stays serving for the notice period below. | Signal | Where | Means | | --- | --- | --- | | `Deprecation` | Response header, [RFC 9745](https://www.rfc-editor.org/rfc/rfc9745) | An HTTP date. This operation is deprecated as of then; a successor exists and is named in `Link`. | | `Sunset` | Response header, [RFC 8594](https://www.rfc-editor.org/rfc/rfc8594) | An HTTP date. The operation stops serving after it. | | `Link: rel="successor-version"` | Response header | Where to go instead. | | `deprecated: true` | [/openapi.json](https://cloud.gomry.com/openapi.json) | The same fact, for a client generator and an agent. | **The notice period is twelve months** between the first `Deprecation` header and the `Sunset` date, and we will mail the technical contact on every organization whose keys called the affected operation in the preceding ninety days. Nothing is withdrawn without both. > **Note:** An automated caller should log a `Deprecation` header rather than ignore it: it is the one signal that arrives long before anything breaks, and an unattended integration is exactly the kind that finds out on the sunset date otherwise. ## The two exceptions **Security.** If serving an operation is actively unsafe — a vulnerability, a credential exposure, an upstream provider withdrawing something under us — we will change or withdraw it faster than twelve months, and say why. This is the only case in which notice is shortened. **Third-party catalogues.** ToolsAPI runs tools published by other vendors. Which tools exist, what they cost and what their inputs look like is the vendor's decision, not ours, and none of it is covered by this policy — `discover` and `inspect` tell you the current state, which is why the docs tell you to read them rather than cache what they returned. --- # Billing > How Gomry Cloud bills: postpaid per-unit metering, one monthly invoice, per-project budget caps, and why there is no free tier. Source: https://docs.cloud.gomry.com/billing Cloud is **postpaid and metered**. You are billed for the units you consume, invoiced monthly. There are no plans, no seats and no minimum. ## How it works - Every billable request records the units it consumed, against the project that made it. - Each service prices each of its operations separately, per unit — the current rates are on each [service page](https://docs.cloud.gomry.com/services), read from the same table that generates the invoice. - Usage accumulates over the calendar month and is invoiced to the organization's card at the end of it. - Only work that produced a result is billed. Failures cost nothing. Operations within one service are priced independently because they cost independently. Extracting structured data from a page costs several times what fetching that page costs, so they are separate prices, separate meters and separate scopes rather than a flag on one endpoint. That is what stops a caller who wanted the cheap operation from being billed for the expensive one. ## Why there is no free tier Every Cloud request carries real upstream cost the moment it runs, whether or not we can invoice for it. So spending is opt-in and the opt-in is a card: an organization without an active payment method is refused with `billing_required` at the gateway, before any work happens. Free usage, when we grant it, is a **credit on your account** rather than a free allowance written into a product. A credit covers any service you use, including ones that ship after it was granted, and it runs out — which is the honest version of the same offer. ## Budget caps Each project can carry a monthly limit, evaluated **before** the work, against the calendar month in UTC. It is the control that bounds a runaway loop, and it is the one we recommend setting on day one. | Setting | Effect | | --- | --- | | No limit | Uncapped. Your card is the only ceiling. | | Limit, action **block** | Requests are refused with `402 insufficient_credit` once the month's spend reaches the cap. | | Limit, action **notify** | Requests continue; the overage is flagged rather than refused. | > **Important:** A budget is per project, not per organization. A limit on `production` does not constrain `staging`. ## When payment fails If an invoice cannot be collected, the organization moves to past due and the data plane stops serving with `billing_past_due` until the card is fixed. There is no grace window on a postpaid metered API, and that is deliberate: usage accrued during a retry window would land on the same invoice that is already failing to collect. Nothing is deleted. Keys, projects and usage history survive; only the ability to spend is paused, and it resumes on the next request once the payment method is valid. ## What development costs There is no separate development tier: the calls you make while integrating are billed at the same per-unit rate as production. In practice that is cents, because only work that produced a result is metered — validation errors, auth failures, rate limits and upstream failures all cost nothing. Set a small monthly budget on a project you are experimenting with and the cap, not the credential, is what bounds the spend. --- # Scrape > Fetch a page and extract structured data from it against a JSON schema. Source: https://docs.cloud.gomry.com/services/scrape Give Scrape a URL and a JSON schema and it returns that shape, filled in from the page. It renders JavaScript first, so single-page apps and pages that build their content client-side work the same as static HTML. ## Overview Two operations, priced separately because they cost differently. POST /v1/scrape renders the page and runs an LLM extraction against your schema, and is billed per page. POST /v1/fetch renders the page and returns its raw HTML plus metadata with no extraction, at a quarter the price — reach for it when you only need og:image, JSON-LD, or the raw HTML and intend to parse it yourself. Only calls that returned a page are billed. A failed scrape, a timeout, or an unreachable host costs nothing. The response tells you what was metered in its `pages` or `fetches` field, so what you were charged is visible in the same payload as the result. What it does not do: there is no search endpoint. Scrape answers questions about a URL you already have — it will not find one for you, and a caller that needs 'the best image for this event name' has to bring its own candidate URLs. It also does not crawl: one call is one page, and following links is yours to orchestrate. ## Endpoints **POST /v1/scrape** — Fetch a page and extract structured data from it against a JSON schema. ```bash curl -X POST https://api.cloud.gomry.com/v1/scrape \ -H "Authorization: Bearer $GOMRY_CLOUD_KEY" \ -H "Content-Type: application/json" \ -d '{ "url": "https://example.com/events/summer-fest", "prompt": "Extract the event", "schema": { "type": "object", "properties": { "name": { "type": "string" }, "startDate": { "type": "string" }, "venue": { "type": "string" } } } }' ``` The response reports `pages` — the quantity you were metered for this call. **POST /v1/fetch** — Fetch a page and return its raw HTML and metadata, without LLM extraction. A quarter the price. ```bash curl -X POST https://api.cloud.gomry.com/v1/fetch \ -H "Authorization: Bearer $GOMRY_CLOUD_KEY" \ -H "Content-Type: application/json" \ -d '{ "url": "https://example.com/events/summer-fest" }' ``` The response reports `fetches` — the quantity you were metered for this call. ## Request options - `url` — Required. The page to scrape. Max 2048 characters. Private addresses and internal hostnames are refused. - `schema` — Required for /v1/scrape. A JSON Schema object describing the shape you want back. Returned in `data`. - `prompt` — Required for /v1/scrape. 1–2000 characters of instruction for the extraction, e.g. "Extract the event". - `waitFor` — Milliseconds to wait after load before reading the page, for content that arrives late. 0–15000. - `timeout` — Milliseconds before the vendor call is abandoned. 1000–90000. The whole request is capped at 120s server-side, so budget for two calls if you use `retry`. - `onlyMainContent` — Strip navigation, footers and boilerplate before extraction. Defaults to true; set false when the data you want lives in the chrome. - `includeRawHtml` — Also return the page's raw HTML in `rawHtml`. Use when you parse JSON-LD or embedded blobs yourself. - `retry` — { requiredField, waitFor }. If the first pass returns without that field, the page is fetched once more with the longer wait. Bills both calls, and only when each returned a page. ## Pricing | Unit | Price | | --- | --- | | per page | $0.02 | | per fetch | 0.5¢ | Only calls that returned a result are billed. Failures cost nothing. Billed monthly in arrears — see [Billing](https://docs.cloud.gomry.com/billing). ## Authentication Send a key as a bearer token. This service's operations require the `scrape:run` and `scrape:fetch` scopes, granted independently — and the project must have Scrape enabled. See [Authentication](https://docs.cloud.gomry.com/authentication). --- # ToolsAPI > Find a tool that can do a task and run it — 1,700+ across 55+ vendors, on your Gomry key. Source: https://docs.cloud.gomry.com/services/toolsapi 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 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 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 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 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 - `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](https://docs.cloud.gomry.com/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](https://docs.cloud.gomry.com/authentication). --- # Superagent > Give it a research question and a JSON schema. It plans, searches, reads, notices what is missing, searches again — and cites every field. Source: https://docs.cloud.gomry.com/services/tasks Superagent is the one API here whose work outlives your request. POST a research question and a JSON schema and you get a task id back immediately; it then works for minutes or hours, and you collect the result by polling or by webhook. Every field in the output names the URL it came from and quotes the sentence that supports it — a field we cannot cite is dropped rather than guessed. ## Overview It researches rather than crawls. First it turns your objective into sub-questions and search queries, because an objective is rarely a good query. Then it reads. Then it looks at what it found, names what is still missing, and decides what to ask next — new searches, or a link it saw on a page it already read. That cycle repeats until the evidence meets the criteria it set for itself at the start, or until it runs out of envelope. The plan it wrote and the reasoning behind each round come back with the answer. Where sources disagree, you are told. A field backed by two independent pages carries two citations, one marked primary; a field two pages contradict each other on comes back in `conflicts` with both values and both quotes, rather than quietly resolved to whichever the model preferred. The disagreement is usually the most useful thing the research found. Three tiers set the envelope: lite reads up to 3 sources and does not reason at all, standard reads up to 15 across 2 rounds, deep up to 100 across 6. The tier is a CEILING, not a price — you pay for one task, one unit per source actually read, and one per reasoning round, so a standard task answered from four pages after one round costs what that actually was. A `budget` can narrow any ceiling but never widen it; set `maxRounds: 0` to skip reasoning entirely and just extract from what you supply. It is cheap because of what it does not buy. A page costs one credit as markdown and five with the vendor's own extraction; Superagent buys the one and extracts itself, then caches both the page and the extraction — so a re-run over a site that has not changed pays for almost none of it again. Polling and cancelling are never billed. A task that fails still bills the sources and rounds it really consumed, but not the task unit. What it does not do: it is not synchronous, and `wait: true` is a 60-second convenience rather than a guarantee — if you need an answer inside one HTTP request, /v1/scrape is the right call. It does not log into anything, so pages behind an account are out of reach. It only follows links it actually saw on pages it read, never a URL it invented. And it will not fill your schema to look complete: a field no source supports comes back missing, which is the honest answer and occasionally a surprising one. ## Endpoints **POST /v1/superagent** — Give it a research question and a JSON schema. It plans, searches, reads, notices what is missing, searches again — and cites every field. ```bash curl -X POST https://api.cloud.gomry.com/v1/superagent \ -H "Authorization: Bearer $GOMRY_CLOUD_KEY" \ -H "Content-Type: application/json" \ -d '{ "objective": "Which of these venues changed their refund policy in 2026, and how?", "seedUrls": ["https://example.com/venue/calendar"], "outputSchema": { "type": "object", "properties": { "shows": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "startDate": { "type": "string" } } } } } }, "tier": "standard" }' ``` The response reports `cost.units` — the quantity you were metered for this call. **GET /v1/superagent/{taskId}** — Poll a running task: status, partial output, sources read, spend so far. Not billed. ```bash curl -X GET https://api.cloud.gomry.com/v1/superagent/{taskId} \ -H "Authorization: Bearer $GOMRY_CLOUD_KEY" ``` This operation is not billed. **DELETE /v1/superagent/{taskId}** — Stop a task admitting further steps. Not billed, and never refunds work already done. ```bash curl -X DELETE https://api.cloud.gomry.com/v1/superagent/{taskId} \ -H "Authorization: Bearer $GOMRY_CLOUD_KEY" ``` This operation is not billed. ## This API answers before the work is done > **Note:** `POST /v1/superagent` returns **202 Accepted** with an id, not a result. The response carries a `Location` header pointing at `/v1/superagent/{taskId}` and a `Retry-After` of 5 seconds — poll no faster than that. Send `DELETE /v1/superagent/{taskId}` to stop it. The id is at `task.taskId` in the create response. Polling and cancelling are never billed, so a loop that respects `Retry-After` costs nothing beyond the work itself. ## Request headers - `Idempotency-Key` — Two requests carrying the same key on one project return the same task instead of starting a second. Send one whenever a retry is possible — an unattended caller that retries without it pays twice for the same research. ## Request options - `objective` — Required. 1–2000 characters describing what you want found, in plain language. - `outputSchema` — Required. A JSON Schema object describing the shape you want back. Returned in `output`, with a matching entry in `citations` for every field. - `seedUrls` — URLs to start from, up to 100 and never more than the tier's source ceiling. Omit and the task searches for its own sources. Private addresses and internal hostnames are refused at creation. - `tier` — lite | standard | deep. Sets the source, round, cost and time ceilings. Defaults to standard. - `budget` — { maxCostMicroUsd, maxSources, deadlineSeconds, maxRounds }. Each is intersected with the tier's ceiling — it can only narrow. `maxRounds: 0` is honoured as "do not reason, just read what I gave you". - `webhookUrl` — Called once when the task reaches a terminal state. Must be a public host. - `wait` — Block up to 60s for a terminal state before responding. The task is unaffected and keeps running if the wait expires. Defaults to false. ## Pricing | Unit | Price | | --- | --- | | per task | $0.15 | | per source | $0.02 | | per round | $0.05 | Only calls that returned a result are billed. Failures cost nothing. Billed monthly in arrears — see [Billing](https://docs.cloud.gomry.com/billing). ## Authentication Send a key as a bearer token. This service's operations require the `tasks:run` and `tasks:read` scopes, granted independently — and the project must have Superagent enabled. See [Authentication](https://docs.cloud.gomry.com/authentication). --- # Ember > One model call, priced per token, at three grades — with the routing, compression and caching that make the cheap grade cheap. Source: https://docs.cloud.gomry.com/services/inference Ember is one call to a language model, on your Gomry key. You choose a CAPABILITY rather than a model — `cheap`, `balanced` or `strong` — and we decide which model serves it. That indirection is the product: the day a smaller specialist beats the current cheap model at a fraction of the cost, your call gets cheaper and your code does not change. ## Overview Billing is per token, in six rows: input and output at each of the three capabilities. Output costs several times input on every model worth using, and the strong grade costs several times the cheap one, so a single blended token price would be wrong in both directions at once. The `usage` field in each response is exactly what went on your invoice. It is cheap because of what it does not send. Passage selection scores a long input against what you actually asked for and drops the rest; a thinking budget stops a trivial call from billing eight times its visible answer at the output rate; an exact-result cache answers a repeated call without a vendor round trip. Each of those is measured before it is turned on, and none of them changes what you are charged — the savings are ours to earn, which is why the price is per token submitted rather than per cent we spent. Everything is priced at the model's published rate, computed from tokens on our side rather than read back from the vendor, so what we charge you and what the envelope allows can never disagree with each other. A call that fails after the model ran still consumed tokens and is still billed for them; a call that never reached a vendor costs nothing. `usage.truncated` is true when the model stopped because it hit `maxOutputTokens` rather than because it had finished. It is not an error — the tokens were spent, the partial answer is often still what you wanted, and the ceiling was yours — but a truncated answer is indistinguishable from a short one without it, and a truncated JSON object will not parse. Raise the ceiling and call again, or accept the prefix; a truncated result is deliberately not cached, so the retry is a real one. What it does not do: there are no tools, no function calling and no multi-turn conversation state — one system prompt, one user message, one answer. That is a deliberate containment boundary, not a roadmap gap: the inputs here are frequently scraped pages, and a model that reads untrusted text and can also act on it is a different risk product. It does not stream, and it does not let you name a model directly — if you need a specific model id, you want that vendor, not us. ## Endpoints **POST /v1/inference** — One model call, priced per token, at three grades — with the routing, compression and caching that make the cheap grade cheap. ```bash curl -X POST https://api.cloud.gomry.com/v1/inference \ -H "Authorization: Bearer $GOMRY_CLOUD_KEY" \ -H "Content-Type: application/json" \ -d '{ "capability": "cheap", "system": "You extract structured data. Answer with one JSON object.", "user": "Event page text here. Return the name and start date.", "jsonSchema": { "type": "object", "properties": { "name": { "type": "string" }, "startDate": { "type": "string" } } } }' ``` The response reports `usage` — the quantity you were metered for this call. ## Request options - `capability` — Required. cheap | balanced | strong. Chooses the price/quality grade, never a specific model. - `system` — Required. 1–20000 characters of instruction. Treat it as yours: nothing is prepended. - `user` — Required. 1–400000 characters. The content to work on. Long inputs are trimmed to the model's window, head first. - `jsonSchema` — A JSON Schema object. Sent as a constrained-decoding hint where the vendor supports it; always parse defensively, because some ignore it. - `maxOutputTokens` — Caps the answer. 1–16384, and never raised above the capability's own ceiling. Remember that thinking tokens count against it, and check `usage.truncated` — a call that hits the ceiling still returns 200. - `effort` — minimal | low | default. Lowers the thinking budget on a call that does not need to reason. Ignored by vendors that do not support it. - `timeoutMs` — Milliseconds before the vendor call is abandoned. Can only tighten the capability's own timeout, never extend it. - `noCache` — Skip the result cache for this call. Default false. A cache hit bills the same as a live call — it is our cost that changed, not your result. ## Pricing | Unit | Price | | --- | --- | | per input token (cheap) | 0.00011¢ ($1.10 per 1M) | | per output token (cheap) | 0.0009¢ ($9.00 per 1M) | | per input token (balanced) | 0.00055¢ ($5.50 per 1M) | | per output token (balanced) | 0.0028¢ ($28.00 per 1M) | | per input token (strong) | 0.00055¢ ($5.50 per 1M) | | per output token (strong) | 0.0028¢ ($28.00 per 1M) | Only calls that returned a result are billed. Failures cost nothing. Billed monthly in arrears — see [Billing](https://docs.cloud.gomry.com/billing). ## Authentication Send a key as a bearer token. This service's operations require the `inference:run` scope, granted independently — and the project must have Ember enabled. See [Authentication](https://docs.cloud.gomry.com/authentication). --- # About Gomry Cloud > Gomry Cloud sells the web-fetching, tool-running and research services Gomry built for its own event platform as metered HTTP APIs, billed per unit with no plans or seats. Source: https://cloud.gomry.com/about Gomry Cloud is the developer platform of **Gomry**, the event ticketing and management company. It sells the technical services Gomry built to run its own product — fetching and understanding web pages, running third-party tools, and doing multi-step research — as metered HTTP APIs that anyone can call. ## What we do Gomry runs an event platform. To do that it had to solve a set of problems that turn out not to be about events at all: reading a venue's page well enough to know when the doors open, reaching a tool that can do a job no one on the team has integrated, and answering a research question that needs twenty sources rather than one. Each of those became a service, and each is now sold on its own terms. Every API is described at [Services](https://docs.cloud.gomry.com/services), priced at [Pricing](https://docs.cloud.gomry.com/pricing) and callable at `https://api.cloud.gomry.com`. The same services power Gomry's own product, which is the only quality guarantee worth stating: an outage here is an outage there. - **Scrape** — Fetch a page and extract structured data from it against a JSON schema. [Read more](https://docs.cloud.gomry.com/services/scrape). - **ToolsAPI** — Find a tool that can do a task and run it — 1,700+ across 55+ vendors, on your Gomry key. [Read more](https://docs.cloud.gomry.com/services/toolsapi). - **Superagent** — Give it a research question and a JSON schema. It plans, searches, reads, notices what is missing, searches again — and cites every field. [Read more](https://docs.cloud.gomry.com/services/tasks). - **Ember** — One model call, priced per token, at three grades — with the routing, compression and caching that make the cheap grade cheap. [Read more](https://docs.cloud.gomry.com/services/inference). ## How we charge Postpaid and metered. You are charged per unit actually consumed, usage accrues over the calendar month, and the total is invoiced to the card on file at the end of it. There are no plans, no seats, no minimum commitment and no annual contract. Stripe is the ledger — we never hold a balance. There is deliberately **no free tier**. Every request carries real upstream cost the moment it runs, so an active payment method is required before any API will serve. Free usage, when we grant it, is a credit on the account that spans every service and runs out — not a permanent allowance written into the code. The full reasoning is on [Billing](https://docs.cloud.gomry.com/billing). ## Company - `Legal name` — Gomry - `Parent product` — Gomry event ticketing and management — https://www.gomry.com - `Address` — 44 Montgomery St, San Francisco, CA 94104, US - `Contact` — info@gomry.com — see [Contact](https://cloud.gomry.com/contact) - `Source` — Open-source clients and examples at https://github.com/GomryHQ --- # Contact > How to reach Gomry Cloud about an API problem, a billing question, a security report or a partnership — including what to include so the first reply is useful. Source: https://cloud.gomry.com/contact There is no sales gate on Gomry Cloud: you can sign up, add a card, mint a key and be calling an API without speaking to anyone. These are the addresses for when something needs a human. ## Reaching us | Subject | Where | What to include | | --- | --- | --- | | An API returned something wrong | `info@gomry.com` | The `x-request-id` from the response header. Without it an intermittent failure cannot be traced. | | Billing, invoices or credits | `info@gomry.com` | Your organization name and the month in question. Rates are at [Pricing](https://docs.cloud.gomry.com/pricing); invoices are issued by Stripe. | | Security vulnerability | `info@gomry.com` | Subject line starting `SECURITY`. Please do not open a public issue first. | | Partnership or volume pricing | `info@gomry.com` | What you want to call and roughly how often. Volume is priced against real usage, not forecasts. | > **Note:** An automated caller does not need any of this to get started. Authentication, scopes and error handling are documented at [Authentication](https://docs.cloud.gomry.com/authentication) and [Errors](https://docs.cloud.gomry.com/errors), and the machine-readable description is at [`/openapi.json`](https://cloud.gomry.com/openapi.json). ## Postal address Gomry, 44 Montgomery St, San Francisco, CA 94104, US. Gomry Cloud is not a separate legal entity — it is Gomry's developer platform, and correspondence about either reaches the same place. The parent product is at https://www.gomry.com. ## When something is down Check the response first. A `502 upstream_error` or a `503 provider_unavailable` names a provider we depend on rather than a fault in your request, and neither is billed — [Errors](https://docs.cloud.gomry.com/errors) says which codes are retryable and with what backoff. If a failure persists across several minutes and several requests, mail us the request ids. --- # Privacy > What Gomry Cloud stores when you call an API, what it does not store, who processes it, and how long each category is kept. Source: https://cloud.gomry.com/privacy This page describes what Gomry Cloud does with data as a **developer platform**. Gomry's product-wide privacy policy covers the event platform and the account you sign in with; this covers the API. ## What we store - `Account and organization` — Your Gomry user id, the organizations you belong to, and your role in each. Identity comes from your existing Gomry account — Cloud creates no separate login. - `API keys` — A SHA-256 hash of each key, never the key itself, plus its prefix, last four characters, scopes and expiry. A lost key cannot be recovered, only revoked and replaced. - `Usage records` — One row per billable request: the project, the service and operation, the quantity metered, the response status, the duration and the request id. This is the record an invoice is built from. - `Billing` — A Stripe customer id and the consent timestamp captured when a card was added. Card details are held by Stripe and never reach our systems. ## What we do not store **We do not retain the content you fetch.** A page scraped through `/v1/scrape` or `/v1/fetch` is returned to you and not kept as a record of what you looked at; a task's cached pages exist to stop the same task paying twice for the same URL and are scoped to the project that created them. Request and response bodies are not written to our logs — logs carry the request id, the key id and the outcome, which is what a support question actually needs. We never log a full API key, an `Authorization` header, or the body of a page a service fetched on your behalf. That is a rule in the codebase, not a preference. ## Who else processes it Calling an API means calling the providers behind it: a scrape reaches the page you named through a rendering provider, a tool run reaches the vendor that publishes that tool, and a research task reaches the search and inference providers it needs. The URL you send and the input you supply go to those providers because that is the work you asked for. Billing is processed by Stripe. Identity is Firebase Authentication. > **Important:** Do not send personal data you are not entitled to send to a third-party processor. An `input` passed to a tool through ToolsAPI is forwarded to that vendor unchanged — we do not inspect or filter it, and we cannot unsend it. ## Retention Usage records are kept for as long as they may be needed to substantiate an invoice, and an unbilled usage row is never deleted — it is unbilled revenue and its absence would be a silent loss. Account, key and billing records live for the life of the organization. Revoking a key removes its ability to authenticate immediately; the usage it already generated remains, because the invoice it belongs to does. ## Access, export and deletion Write to `info@gomry.com` from the address on your Gomry account. We will tell you what is held against your organization, export it, or delete what is not required for a settled invoice or a legal obligation. See [Contact](https://cloud.gomry.com/contact) for the rest of the addresses. --- # Authentication for agents > How an automated caller obtains, uses, rotates and revokes a Gomry Cloud credential, and which parts of the agent-auth specs this platform does and does not implement. Source: https://cloud.gomry.com/auth This page is addressed to **software**. It says how a program gets a credential for Gomry Cloud, what that credential may do, and what happens when it is refused. The equivalent written for a person is [Authentication](https://docs.cloud.gomry.com/authentication). ## Discover The resource server is `https://api.cloud.gomry.com`. Its protected-resource metadata is published under [RFC 9728](https://www.rfc-editor.org/rfc/rfc9728) at [`/.well-known/oauth-protected-resource`](https://cloud.gomry.com/.well-known/oauth-protected-resource), on both this host and the API host. It names the resource, every scope this platform defines, and the bearer methods accepted. An unauthenticated call to any `/v1` endpoint answers `401` with a `WWW-Authenticate: Bearer resource_metadata="…"` header pointing at that document, so one request is enough to learn the requirements. The callable surface itself is described at [`/openapi.json`](https://cloud.gomry.com/openapi.json), and [`/.well-known/api-catalog`](https://cloud.gomry.com/.well-known/api-catalog) is the RFC 9727 linkset that points at both. > **Important:** **What this platform does not implement, stated plainly so nothing has to guess.** There is no OAuth 2.0 authorization server, so there is no `/.well-known/oauth-authorization-server` document, no `agent_auth` block, no `identity_endpoint`, no `claim_endpoint` and no `events_endpoint`. No `identity_assertion` flow is accepted, `service_auth` is not offered, and an ID-JAG assertion (`urn:ietf:params:oauth:token-type:id-jag`) will be refused like any other unrecognised bearer token. A credential is minted by a human in the console and handed to the agent. If that changes, this section changes with it — and the metadata document above is where a machine should look, not this prose. ## Pick a method There is one method: a project-scoped API key, sent as a bearer token. It is not a user token — it carries no person's identity, it does not expire with a session, and it cannot be exchanged for one. | Key prefix | Behaviour | Use it for | | --- | --- | --- | | `gck_live_` | The real request, metered and invoiced. | Production. | | `gck_test_` | The same request path and the same real upstream call, returning real data, metered at zero. | A test environment, a CI run, or an agent exercising the integration before it is trusted with spend. | > **Note:** A `gck_test_` key is the sandbox. It is not a mock and not a separate host: the URL, the request body and the response shape are identical to production, which is the point — an integration proven with a test key works unchanged when the prefix changes. It still requires an organization with a payment method, because it still spends real upstream cost; what it does not do is bill you for it. ## Register Registration is self-serve and needs no sales contact. A person signs in at [the console](https://cloud.gomry.com/sign-in) with a Google account, an email code or a phone number, creates or adopts an organization, adds a payment method, and creates a project. Nothing is provisioned for an agent automatically — there is no dynamic client registration endpoint. 1. **Create a project** — The unit of isolation and of spend. Keys, enabled APIs, usage and the monthly budget cap all belong to one project. 2. **Enable the APIs the agent will call** — Enabling is separate from scopes on purpose: a key minted with a broad scope still cannot reach an API the project never enabled. 3. **Set a budget cap** — Checked before every request, from local tables. This is the real ceiling on what an unattended caller can spend, and it is the control to set before handing a key to one. ## Claim A key is minted in the console against a project, with an explicit list of scopes and an optional expiry. Grant only the scopes the agent will call — scopes are flat, there are no wildcards, and a read scope never implies the matching run scope. Every scope this platform defines is listed at [Authentication](https://docs.cloud.gomry.com/authentication) and in the protected-resource metadata. > **Important:** The plaintext key is shown **once**, at mint time. Only a SHA-256 hash is stored, so it cannot be recovered — put it in your secret manager in the same step that creates it. An expiry at mint time is the better default for anything handed to a third party or to an unattended process. ## Exchange There is no exchange step. The key you were given is the credential you send — there is no token endpoint, no refresh token, no assertion to present and nothing to mint at runtime. An agent that has the key is ready to call. ## Use the access token Send it as a bearer token on every request. There is no cookie, no session and no ambient credential: a browser session cannot authenticate a data-plane call, and a key cannot authenticate a console call. Request: ```bash curl -sS https://api.cloud.gomry.com/v1/fetch \ -H "Authorization: Bearer $GOMRY_CLOUD_KEY" \ -H "Content-Type: application/json" \ -d '{"url":"https://example.com"}' ``` Every response carries `x-request-id`; capture it, because an intermittent failure cannot be traced without it. Billable responses report the quantity they metered in their own body, so what you were charged arrives in the same payload as the result. ## Errors Failures are JSON with a stable `error` code and a human `message`. Branch on the code; the message is written for a person and may be reworded. The complete table is at [Errors](https://docs.cloud.gomry.com/errors) — these are the ones an authentication layer has to handle. | Status | Code | What an agent should do | | --- | --- | --- | | `401` | `unauthorized` | The key is missing, malformed, unknown, revoked or expired. Do not retry — the credential has to be replaced. The `WWW-Authenticate` header names the metadata document. | | `403` | `forbidden` | The key is valid but lacks the scope for this operation. Do not retry; a broader key must be minted. | | `403` | `api_not_enabled` | The project has not enabled this API. Do not retry; a person must turn it on. | | `402` | `billing_required`, `billing_past_due`, `billing_suspended`, `insufficient_credit` | Spending is blocked until a human adds a card, fixes one, or raises the project budget. **Never retry in a loop** — nothing an agent can do resolves these. | | `429` | `rate_limited` | Back off until `x-ratelimit-reset`, with jitter. Limits are per key, not per IP. | | `5xx` | `internal_error`, `upstream_error`, `provider_unavailable` | Retryable with backoff, and not billed. | ## Revocation Revoke a key in the console. It takes effect on the **next request** — there is no cache of authorization decisions to wait out and no propagation delay to plan around. To rotate without downtime, mint the replacement, deploy it, then revoke the old one. Revocation does not stop work already in flight that outlives its request: a research task started before the key was revoked continues and is still billed, because the spend was committed when the task was accepted. Stop it explicitly with `DELETE /v1/superagent/{taskId}`. Deleting a project revokes every key it owns. --- # Gomry Cloud for agents > When an AI agent should call Gomry Cloud and when it should not — the jobs each API is right for, the ones it is wrong for, and how to call it safely under a budget. Source: https://cloud.gomry.com/agents Gomry Cloud is a set of metered HTTP APIs an autonomous caller can use as tools. This page says **when to reach for them**, which is the one thing the machine-readable descriptions cannot say for themselves. ## When to use this platform Reach for Gomry Cloud when a task needs something from the open web that you cannot get from your own context, and you want one credential and one invoice rather than an account with each provider. Every operation below is a single JSON POST with a bearer token. | If the task is… | Call | Notes | | --- | --- | --- | | **I have a URL and I need specific fields out of it** | `POST /v1/scrape` | Renders JavaScript first, so single-page apps work. Give it a JSON schema and it returns that shape. Billed per page, and only when a page came back. | | **I have a URL and I want the raw HTML or its metadata** | `POST /v1/fetch` | No extraction, a quarter the price. The right call when you intend to parse og:image, JSON-LD or the HTML yourself. | | **I need a capability nobody here has integrated** | `POST /v1/toolsapi/discover` then `/run` | Describe the task in words, get ranked tools with prices, run one. You never hold the vendor's key. | | **I need an answer that takes many sources, not one page** | `POST /v1/superagent` | Plans, searches, reads, notices what is missing and searches again. Returns a task id immediately; poll it. Every field cites the URL and the sentence behind it. | ## When not to use it - **You want to find a URL rather than read one.** There is no search endpoint on Scrape. It answers questions about a URL you already have. Superagent searches, but it is the wrong tool when you only wanted a link. - **You want to crawl a site.** One Scrape call is one page. Following links is yours to orchestrate, and a naive crawl is the fastest way to spend a budget cap. - **You need the answer inside one HTTP request.** Superagent is asynchronous; `wait: true` is a 60-second convenience, not a guarantee. If a synchronous answer is required, that is `/v1/scrape`. - **The page is behind a login.** Nothing here authenticates to a third-party site on your behalf. - **You are retrying a `402` or a `403`.** Neither resolves without a person. A retry loop on a billing refusal is the single most expensive mistake an unattended caller makes here — it cannot succeed and it will not stop. - **You already have the content.** These are metered calls. Re-fetching a page you fetched a minute ago is billed again. ## Calling safely under a budget - Start with a `gck_test_` key. Same URL, same body, same response shape, real upstream call, metered at zero. - Set the project's monthly budget cap before handing a key to an unattended process. It is checked before the work runs, not after. - Grant the narrowest scopes. `toolsapi:read` browses the catalogue; `toolsapi:run` spends. `tasks:read` supervises work; `tasks:run` starts it. - Read the metered field in each response — `pages`, `fetches`, `meteredMicroUsd`, `cost.units`. It is exactly what went on the invoice. - Honour `x-ratelimit-reset` and back off with jitter. Limits are per key. - Send an `Idempotency-Key` when starting a research task, so a retried request returns the existing task instead of starting a second one. ## Machine-readable entry points - `https://cloud.gomry.com/openapi.json` — Every endpoint, verb, required scope and example body. Start here to call rather than to read. - `https://cloud.gomry.com/llms.txt` — This site as an index, linking the Markdown twin of every page. - `https://cloud.gomry.com/llms-full.txt` — The whole corpus in one fetch. - `https://cloud.gomry.com/auth.md` — How to obtain, use, rotate and revoke a credential. - `https://cloud.gomry.com/.well-known/api-catalog` — RFC 9727 linkset pointing at the description and the docs. - `https://cloud.gomry.com/.well-known/oauth-protected-resource` — RFC 9728 metadata: the resource, its scopes and the bearer methods accepted. - `https://cloud.gomry.com/.well-known/agent-skills/index.json` — The same capabilities as a skills index. - `https://cloud.gomry.com/.well-known/ard.json` — Agentic Resource Discovery catalog of everything on this list. - `https://cloud.gomry.com/mcp` — Documentation MCP server (Streamable HTTP, no credential) — search and read these docs as tools. - `https://api.cloud.gomry.com/mcp` — Product MCP server (Streamable HTTP, bearer key) — call the APIs as tools. Any page on this site can be fetched as Markdown by appending `.md` to its URL, or by sending `Accept: text/markdown`. If you are driving a browser rather than calling HTTP yourself, every public page declares those same documentation tools on `document.modelContext` (WebMCP), so they can be invoked as tools instead of read back off the rendered page. They are the tools of the documentation server above: anonymous, read-only and unbilled. Calling an API still requires a key and still goes to the data plane. --- # Documentation > Gomry Cloud documentation: quickstart, authentication, error codes, rate limits and billing, plus a reference for every API. Source: https://docs.cloud.gomry.com Start with the quickstart. The rest is what is true of every API: how keys and scopes work, what each error code means, how requests are limited, and how you are billed. ## Guides - [Quickstart](https://docs.cloud.gomry.com/quickstart) — Create a project, enable an API, mint a key and make your first billable Gomry Cloud request in about two minutes. - [Authentication](https://docs.cloud.gomry.com/authentication) — How Gomry Cloud API keys work: the gck_live_ format, scopes per operation, and the two independent checks every request passes. - [Errors](https://docs.cloud.gomry.com/errors) — Every error code the Gomry Cloud API returns, what causes it, whether it is retryable, and whether the failed request was billed. - [Rate limits](https://docs.cloud.gomry.com/rate-limits) — Gomry Cloud rate limits per API key, not per IP: the default budget, the headers to read, and how to back off correctly. - [Versioning and deprecation](https://docs.cloud.gomry.com/versioning) — How Gomry Cloud versions its API, what counts as a breaking change, and the notice and headers you get before anything is withdrawn. - [Billing](https://docs.cloud.gomry.com/billing) — How Gomry Cloud bills: postpaid per-unit metering, one monthly invoice, per-project budget caps, and why there is no free tier. ## API reference - [Scrape](https://docs.cloud.gomry.com/services/scrape) — Fetch a page and extract structured data from it against a JSON schema. `POST /v1/scrape`. - [ToolsAPI](https://docs.cloud.gomry.com/services/toolsapi) — Find a tool that can do a task and run it — 1,700+ across 55+ vendors, on your Gomry key. `POST /v1/toolsapi/run`. - [Superagent](https://docs.cloud.gomry.com/services/tasks) — Give it a research question and a JSON schema. It plans, searches, reads, notices what is missing, searches again — and cites every field. `POST /v1/superagent`. - [Ember](https://docs.cloud.gomry.com/services/inference) — One model call, priced per token, at three grades — with the routing, compression and caching that make the cheap grade cheap. `POST /v1/inference`. Every page linked here is also available as Markdown: append `.md` to its URL, or send `Accept: text/markdown`. The whole corpus in one fetch is at [/llms-full.txt](https://cloud.gomry.com/llms-full.txt). --- # Services > Every API Gomry Cloud sells, with what each one does and what each operation costs per unit. Source: https://docs.cloud.gomry.com/services Each service is enabled per project, carries its own scopes, and prices each of its operations separately. Rates are per unit and billed monthly in arrears. ## Every API we sell - **Scrape** — Fetch a page and extract structured data from it against a JSON schema. Endpoints: `/v1/scrape, /v1/fetch`. [Reference](https://docs.cloud.gomry.com/services/scrape). - **ToolsAPI** — Find a tool that can do a task and run it — 1,700+ across 55+ vendors, on your Gomry key. Endpoints: `/v1/toolsapi/run, /v1/toolsapi/discover, /v1/toolsapi/inspect, /v1/toolsapi/runs/{runId}`. [Reference](https://docs.cloud.gomry.com/services/toolsapi). - **Superagent** — Give it a research question and a JSON schema. It plans, searches, reads, notices what is missing, searches again — and cites every field. Endpoints: `/v1/superagent, /v1/superagent/{taskId}, /v1/superagent/{taskId}`. [Reference](https://docs.cloud.gomry.com/services/tasks). - **Ember** — One model call, priced per token, at three grades — with the routing, compression and caching that make the cheap grade cheap. Endpoints: `/v1/inference`. [Reference](https://docs.cloud.gomry.com/services/inference). ## What each one costs | Service | Unit | Price | | --- | --- | --- | | Scrape | per page | $0.02 | | Scrape | per fetch | 0.5¢ | | ToolsAPI | per µ$ of tool cost | 0.0003¢ ($3.00 per 1M) | | ToolsAPI | per lookup | 0.2¢ | | Superagent | per task | $0.15 | | Superagent | per source | $0.02 | | Superagent | per round | $0.05 | | Ember | per input token (cheap) | 0.00011¢ ($1.10 per 1M) | | Ember | per output token (cheap) | 0.0009¢ ($9.00 per 1M) | | Ember | per input token (balanced) | 0.00055¢ ($5.50 per 1M) | | Ember | per output token (balanced) | 0.0028¢ ($28.00 per 1M) | | Ember | per input token (strong) | 0.00055¢ ($5.50 per 1M) | | Ember | per output token (strong) | 0.0028¢ ($28.00 per 1M) | Only work that produced a result is billed: a validation error, an auth failure, a rate limit, a timeout or an upstream failure costs nothing. The full price list and how invoicing works are at [Pricing](https://docs.cloud.gomry.com/pricing); the mechanics of metering, budgets and payment failures are at [Billing](https://docs.cloud.gomry.com/billing).