# Aquedra Run > GIS tools that agents call over REST or MCP and pay for per call from prepaid credits (1 credit = US$1). Prices and limits are listed before you pay; a call is priced from its input before it runs. ## Authentication - REST: send `Authorization: Bearer rk_...` with an API key created in the dashboard (https://r.aquedra.com/app). Every /v1 route needs it. - MCP: connect to https://r.aquedra.com/mcp (Streamable HTTP) with the same Bearer key, or through OAuth, where the client discovers the authorization server at /.well-known/oauth-authorization-server. ## Example ``` curl -X POST https://r.aquedra.com/v1/geo/measure \ -H "Authorization: Bearer rk_..." \ -H "Content-Type: application/json" \ -d '{"geojson":{"type":"Feature","properties":{"name":"Plot A"},"geometry":{"type":"Polygon","coordinates":[[[-70.65,-33.45],[-70.64,-33.45],[-70.64,-33.44],[-70.65,-33.44],[-70.65,-33.45]]]}}}' ``` Response (200): ```json { "data": { "result": { "features": [ { "index": 0, "geometry_type": "Polygon", "area_m2": 1031699.8850028745, "perimeter_m": 4079.559030916064 } ], "totals": { "area_m2": 1031699.8850028745, "length_m": 0 } }, "cost_usd": "0.001000", "units": 1, "call_id": "0b7e6f3c-5d4a-4c1e-9a52-3f6f1d2c8e10", "balance_usd": "4.999000" } } ``` Success is `{ "data": ... }`; an error is `{ "error": { "code", "message", "request_id" } }`. Money is decimal text in US dollars. ## Tools ### Convert coordinates - Route: POST https://r.aquedra.com/v1/geo/coordinates - MCP tool: convert_coordinates - What it does: Convert up to 1,000 points between decimal degrees, degrees-minutes-seconds and UTM (WGS84). - Price: US$0.001 per unit; max(1, ceil(points / 1000)): up to 1,000 points are 1 unit. - Limits: up to 1,000 points per call. ### Measure GeoJSON - Route: POST https://r.aquedra.com/v1/geo/measure - MCP tool: measure_geojson - What it does: Measure the geodesic area, perimeter and length of each feature of a GeoJSON, with totals, in square meters and meters. - Price: US$0.001 per unit; max(1, ceil(features / 1000), ceil(vertices / 10000)): up to 1,000 features and 10,000 vertices are 1 unit. - Limits: up to 50,000 features and 200,000 vertices. ### Reproject GeoJSON - Route: POST https://r.aquedra.com/v1/geo/reproject - MCP tool: reproject_geojson - What it does: Reproject every coordinate of a GeoJSON between coordinate reference systems such as EPSG:4326, EPSG:3857 and the WGS84 UTM zones. - Price: US$0.001 per unit; max(1, ceil(features / 1000), ceil(vertices / 10000)): up to 1,000 features and 10,000 vertices are 1 unit. - Limits: up to 50,000 features and 200,000 vertices. ### Transform GeoJSON - Route: POST https://r.aquedra.com/v1/geo/transform - MCP tool: transform_geojson - What it does: Buffer, simplify, centroid, bounding box, convex hull or clean a GeoJSON, returning the resulting GeoJSON. - Price: US$0.001 per unit; max(1, ceil(features / 1000), ceil(vertices / 10000)): up to 1,000 features and 10,000 vertices are 1 unit. - Limits: up to 50,000 features and 200,000 vertices; buffer takes up to 1,000 features, 4,000 vertices and 1,000 MultiPoint positions (5,000, 20,000 and 5,000 with max_seconds over 3). ### Convert geospatial file - Route: POST https://r.aquedra.com/v1/geo/convert - MCP tool: convert_geo_file - What it does: Convert a geospatial file (CSV, KML, GPX, GeoJSON or zipped Shapefile) to GeoJSON, KML or CSV. - Price: US$0.01 per file; 1 per file (up to 1 MiB of arguments), whatever its number of features. - Limits: text content up to 1 MiB (csv: 200 columns, 50,000 rows, 200,000 cells); a zipped Shapefile as base64 text up to about 750 KB (8 MiB unzipped); up to 50,000 features and 200,000 vertices; csv and kml output up to 200 property keys, kml output up to 20,000 features. Every request (or MCP argument set) is at most 1 MiB, and a result is at most 8 MiB. ## Options These go at the top level of the JSON body (or the MCP arguments), next to the operation's own fields. - `dry_run` (boolean): return the price (`cost_usd`) and `units` without running the call or charging anything. - `max_cost_usd` (USD as a number or decimal text, at most 6 decimals): a call that would cost more is refused with 402 `max_cost_exceeded` and nothing is charged. - `max_seconds` (integer 1 to 30, default 3): the compute limit; 1 to 3 all run the standard 3 s. 3 seconds are included in the price. From 4 to 30 (extended time) each second over 3 costs US$0.0005: the price plus all those seconds is held at the start (`dry_run` and `max_cost_usd` use that amount), the seconds not used are refunded, and the response adds `compute_ms` and `max_seconds`. Extended time also raises buffer's limits. ## Charges - With the default 3 s a call is charged only when it succeeds, invalid input is never charged and every failure is refunded in full. - With extended time, the price and the time used are charged if the call runs out of time or memory, or is cancelled while running; those errors carry `cost_usd` in the error object and the X-Run-Cost-Usd header (over MCP, `structuredContent.error.cost_usd`). Every other failure is refunded in full. - Calls with the same X-Request-Id are separate calls and each is charged; the call_id is issued by the server. ## Errors Each error has a stable `code`; branch on the code, not the message. 429 and 503 carry `Retry-After` (seconds). Over MCP an error is a tool result with `isError` and `structuredContent.error`; an unexpected failure there has the code `unavailable` (REST: 500 `internal_error`). - 400 invalid_json: The request body is not valid JSON (REST only). Charged: no. - 401 unauthorized: Missing, invalid or revoked API key or access token. Charged: no. - 402 insufficient_credits: The balance does not cover the price (with max_seconds over 3, the price plus the time held). Buy credits at POST /v1/credits/purchase. Charged: no. - 402 max_cost_exceeded: The price (with max_seconds over 3, the hold) is above max_cost_usd. Charged: no. - 404 not_found: Unknown GIS operation in the path (REST only); use coordinates, reproject, measure, transform or convert. Charged: no. - 413 payload_too_large: The body or arguments are over 1 MiB, or the input is over a limit of the operation (features, vertices, points, file size). Charged: no. - 413 result_too_large: The result is over 8 MiB; ask for GeoJSON or CSV output, or split the input. Charged: no; with max_seconds over 3, the price and the seconds used. - 422 validation_failed: The body does not match the operation's schema; the message names the field. Charged: no. - 422 invalid_geometry: A GeoJSON geometry is invalid or degenerate. Charged: no. - 422 invalid_file: The file content cannot be read as the stated input_format. Charged: no. - 422 operation_too_complex: The operation did not finish within max_seconds (3 by default); simplify or split the input, or raise max_seconds up to 30. Charged: no; with max_seconds over 3, the price and the whole hold. - 422 operation_too_large: The operation ran out of memory; simplify or split the input. Charged: no; with max_seconds over 3, the price and the seconds used. - 429 daily_spend_cap: The call would pass the account's daily spend limit; Retry-After is the seconds until 00:00 UTC. Charged: no. - 429 too_many_concurrent: This account already has its limit of GIS calls queued or running on that lane at the server that received the call (2 by default, counted per server, not across the whole service); wait for one to finish (Retry-After: 1). Charged: no. - 429 rate_limited: Too many requests for the key; retry after Retry-After (60 s). Charged: no. - 499 cancelled: The client closed the request while the call was queued or running. Charged: no; cancelled while running with max_seconds over 3, the price and the seconds used. - 500 internal_error: An unexpected failure (REST). Over MCP the same failure is reported as the code unavailable. Retry shortly; quote the request_id if it persists. Charged: no. - 503 busy: The GIS service is full or the call waited too long for a worker; retry after Retry-After. Charged: no. ## Inference (own GPUs, best effort) Chat completions on Run's own GPUs, OpenAI-compatible: set `base_url` to `https://r.aquedra.com/v1` in an OpenAI SDK and use your API key. REST: POST https://r.aquedra.com/v1/chat/completions and GET https://r.aquedra.com/v1/models; MCP tool: chat (no streaming). Best effort: the GPUs are shared and their owner's other work has priority, so the service can be busy. ``` curl -X POST https://r.aquedra.com/v1/chat/completions \ -H "Authorization: Bearer rk_..." \ -H "Content-Type: application/json" \ -d '{"model":"qwen2.5-3b","messages":[{"role":"user","content":"Say hello in one sentence."}],"max_tokens":64}' ``` Response (200), the OpenAI shape plus `run`: ```json { "id": "chatcmpl-0b7e6f3c-5d4a-4c1e-9a52-3f6f1d2c8e10", "object": "chat.completion", "created": 1795132800, "model": "qwen2.5-3b", "choices": [ { "index": 0, "message": { "role": "assistant", "content": "Hello! It's nice to meet you." }, "finish_reason": "stop" } ], "usage": { "prompt_tokens": 15, "completion_tokens": 9, "total_tokens": 24 }, "run": { "call_id": "0b7e6f3c-5d4a-4c1e-9a52-3f6f1d2c8e10", "cost_usd": "0.000500", "balance_usd": "4.999500", "hold_usd": "0.000500" } } ``` Models on sale (US$ per million tokens): - `qwen3-8b`: US$0.18 in / US$0.70 out; 8,192 tokens of context, up to 2,048 of output; reasons before answering. - `qwen2.5-3b`: US$0.05 in / US$0.10 out; 8,192 tokens of context, up to 2,048 of output. - `qwen2.5-coder-7b`: US$0.025 in / US$0.05 out; 8,192 tokens of context, up to 2,048 of output. - `qwen2.5-vl-7b`: US$0.18 in / US$0.69 out; 8,192 tokens of context, up to 2,048 of output; accepts images. - Reasoning: `qwen3-8b` reasons before it answers; those tokens are not in `content` but count as output tokens and use up `max_tokens`, so send `max_tokens` of at least 1024 (with less, the answer can come back empty and is still charged). - Minimum per call: US$0.0005. The estimated prompt plus max_tokens is held first and the unused part is refunded; the final cost is at least the minimum and never above the hold. `dry_run` returns the most the call can cost (`cost_usd`, the hold) and the `max_tokens` it assumes, without running or charging; `max_cost_usd` refuses a dearer call (402 `max_cost_exceeded`). - Cost: `run.cost_usd` and `run.balance_usd` in the response (in the last chunk when streaming) and the X-Run-Call-Id, X-Run-Cost-Usd and X-Run-Balance-Usd headers; with stream true only X-Run-Call-Id and X-Run-Hold-Usd come before the first byte. A failure mid-stream ends the stream with an event `data: {"error": {code, message, request_id}}` and no `[DONE]`. - 503 `gpu_busy` means the GPU is busy: wait `Retry-After` seconds and retry; nothing is charged. A call is limited to 90 s (504 `upstream_timeout`). - Limits: up to 64 messages and 1 MiB per request; the estimated prompt plus max_tokens is at most 8192 tokens (422 `context_length_exceeded`); max_tokens defaults to 1024, and one above 2,048 is lowered to 2,048 (the response then carries `run.max_tokens` and `run.max_tokens_requested`); up to 10 calls per minute per account (429 `rate_limited`), and a call answered 503 `gpu_busy` counts toward that limit too. - Images: only `qwen2.5-vl-7b`, up to 2 inline `data:image/png|jpeg|webp;base64` images of up to 512 KB each, which together must fit in the 1 MiB request; remote image URLs are not supported. - Ignored fields: `user`, `frequency_penalty` and `presence_penalty` are accepted and ignored, and so is `stream_options` (the usage always comes in the last chunk). A field sent as `null` counts as not sent. - Not supported (422 `unsupported_parameter`, never ignored): tools and function calling, response_format other than text, n other than 1, logprobs, audio, embeddings, remote images, max_seconds. One of these sent as `false` or `[]` (or `tool_choice: "none"`) asks for nothing and is accepted. - Privacy: prompts and answers are not stored; only the call's tokens and cost are recorded. - 404 model_not_found: The model is not on sale; GET /v1/models lists the ones that are. - 422 unsupported_parameter: A field the service does not support (tools, response_format other than text, n other than 1, max_seconds, remote images, images on a text model); it is refused, never ignored. - 422 context_length_exceeded: The estimated prompt plus max_tokens is over 8192 tokens; shorten the messages or lower max_tokens. - 502 upstream_error: The GPU failed while answering; retry later. - 503 gpu_busy: The GPU is busy (best effort: the GPUs are shared and their owner's other work has priority); retry after Retry-After. - 503 inference_unavailable: Inference is not available right now. - 504 upstream_timeout: The model did not finish within 90 s; lower max_tokens or retry. ## Buy credits POST https://r.aquedra.com/v1/credits/purchase with `{"pack_usd": 5 | 20 | 50 | 100, "method": "card" | "usdc"}`. With "card" the response has a `checkout_url` that a person completes in a browser; the API never charges a card. With "usdc" the first response is 402 with an x402 payment request, and retrying with the signed payment in the PAYMENT-SIGNATURE header adds the credits. The MCP tool is buy_credits. Check the balance with GET https://r.aquedra.com/v1/usage or the get_usage tool. ## Links - OpenAPI 3.1: https://r.aquedra.com/openapi.json - Prices as JSON: https://r.aquedra.com/pricing.json - Prices for people: https://r.aquedra.com/pricing - Documentation and quick start: https://r.aquedra.com/docs - MCP: https://r.aquedra.com/mcp - MCP for Claude and ChatGPT connector directories (no purchase tool): https://r.aquedra.com/mcp/connector - Purchase: https://r.aquedra.com/v1/credits/purchase