# Run a capability (/docs/api/calls/run) Routed call: GridRouter picks vendors (waterfall/cheapest/best) until one hits. Only hits are charged on per-success vendors. `POST /v1/run/{capability}` ```json { "operationId": "run", "summary": "Run a capability", "description": "Routed call: GridRouter picks vendors (waterfall/cheapest/best) until one hits. Only hits are charged on per-success vendors.", "tags": [ "run" ], "security": [ { "bearer": [] } ], "parameters": [ { "schema": { "type": "string", "pattern": "^[a-z]+(\\.[a-z0-9_]+)+$" }, "required": true, "name": "capability", "in": "path" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "input": { "type": "object", "additionalProperties": {} }, "max_cost_micro": { "type": "integer", "minimum": 0 }, "meta": {}, "credential": { "type": "string", "enum": [ "auto", "managed", "byok" ], "default": "auto" }, "include_raw": { "type": "boolean", "default": false }, "provider": { "type": "object", "properties": { "order": { "type": "array", "items": { "type": "string" }, "maxItems": 20 }, "only": { "type": "array", "items": { "type": "string" }, "maxItems": 20 }, "ignore": { "type": "array", "items": { "type": "string" }, "maxItems": 20 }, "allow_fallbacks": { "type": "boolean" }, "sort": { "type": "string", "enum": [ "price", "reliability", "latency", "throughput", "quality" ] }, "max_cost_micro": { "type": "integer", "minimum": 0, "description": "Skip endpoints whose quote exceeds this" }, "max_price_micro": { "type": "integer", "minimum": 0, "description": "OpenRouter-style max_price: skip endpoints whose worst-case price is above this" }, "preferred_max_latency_ms": { "type": "integer", "exclusiveMinimum": 0, "maximum": 120000, "description": "Endpoints with a p50 above this are tried after the ones under it" }, "data_policy": { "type": "object", "properties": { "storage": { "type": "string", "enum": [ "any", "reviewed", "storable" ], "default": "any" }, "zdr": { "type": "boolean", "default": false } } }, "require_verified": { "type": "boolean", "description": "Only vendors Relaygrid has verified" } }, "default": {} }, "preset": { "type": "string", "maxLength": 48, "pattern": "^@(preset\\/)?[a-z0-9]+(-[a-z0-9]+)*$", "description": "Saved routing preset (`@slug`); explicit request fields override it" }, "fields": { "type": "array", "items": { "type": "string", "maxLength": 80, "pattern": "^[a-z][a-z0-9_]*(\\.[a-z][a-z0-9_]*)*$" }, "maxItems": 50, "description": "Return only these normalized output fields" }, "stop_when": { "type": "string", "enum": [ "hit", "success" ] }, "options": { "type": "object", "properties": { "timing": { "type": "object", "properties": { "timeout_ms": { "type": "integer", "minimum": 100, "maximum": 120000, "description": "Abort one vendor attempt after" }, "deadline_ms": { "type": "integer", "minimum": 100, "maximum": 300000, "description": "Total time for the whole request or run" }, "hedge_after_ms": { "type": "integer", "minimum": 50, "maximum": 60000, "description": "Start the next vendor if one is slow" }, "wait_s": { "type": "integer", "minimum": 0, "maximum": 60, "description": "Prefer: wait=N before answering 202" }, "run_at": { "type": "string", "format": "date-time", "description": "ISO time" }, "delay_s": { "type": "integer", "minimum": 1, "maximum": 43200, "description": "Delay (s)" }, "schedule": { "type": "string", "maxLength": 100, "pattern": "^(\\S+\\s+){4}\\S+$", "description": "Schedule (cron)" }, "job_ttl_s": { "type": "integer", "minimum": 60, "maximum": 604800, "description": "Job TTL (s)" }, "retry": { "type": "object", "properties": { "max": { "type": "integer", "minimum": 0, "maximum": 10, "description": "Max retries" }, "backoff": { "type": "string", "enum": [ "fixed", "exponential" ], "description": "Backoff" }, "base_ms": { "type": "integer", "minimum": 10, "maximum": 60000, "description": "Base delay (ms)" }, "max_ms": { "type": "integer", "minimum": 10, "maximum": 300000, "description": "Max delay (ms)" }, "jitter": { "type": "boolean", "description": "Jitter" }, "retry_on": { "type": "array", "items": { "type": "string", "enum": [ "429", "5xx", "timeout" ] }, "maxItems": 3, "description": "Retry on" } }, "additionalProperties": false, "description": "Retry" } }, "additionalProperties": false, "description": "Timing" }, "concurrency": { "type": "object", "properties": { "max_concurrency": { "type": "integer", "minimum": 1, "maximum": 1000, "description": "Max concurrency" }, "per_provider_concurrency": { "type": "integer", "minimum": 1, "maximum": 200, "description": "Per-provider concurrency" }, "priority": { "type": "string", "enum": [ "low", "normal", "high" ], "description": "Priority" }, "ordering": { "type": "string", "enum": [ "fifo", "none" ], "description": "Ordering" } }, "additionalProperties": false, "description": "Concurrency" }, "rate": { "type": "object", "properties": { "per_second": { "type": "number", "minimum": 0.01, "maximum": 10000, "description": "Per second" }, "per_minute": { "type": "integer", "minimum": 1, "maximum": 600000, "description": "Per minute" }, "burst": { "type": "integer", "minimum": 1, "maximum": 10000, "description": "Burst" }, "adaptive": { "type": "boolean", "description": "Slow down from vendor headers and 429s" } }, "additionalProperties": false, "description": "Rate limits" }, "cost": { "type": "object", "properties": { "max_cost_micro": { "type": "integer", "minimum": 0, "description": "Per call, run or list row" }, "daily_cap_micro": { "type": "integer", "minimum": 0, "description": "Daily cap (micro-USD)" }, "budget": { "type": "string", "pattern": "^[a-z0-9_-]{1,64}$", "description": "Budget" }, "dry_run": { "type": "boolean", "description": "Dry run" }, "quote_only": { "type": "boolean", "description": "Quote only" } }, "additionalProperties": false, "description": "Cost" }, "routing": { "type": "object", "properties": { "provider": { "type": "object", "properties": { "order": { "type": "array", "items": { "type": "string" }, "maxItems": 20 }, "only": { "type": "array", "items": { "type": "string" }, "maxItems": 20 }, "ignore": { "type": "array", "items": { "type": "string" }, "maxItems": 20 }, "allow_fallbacks": { "type": "boolean" }, "sort": { "type": "string", "enum": [ "price", "reliability", "latency", "throughput", "quality" ] }, "max_cost_micro": { "type": "integer", "minimum": 0, "description": "Skip endpoints whose quote exceeds this" }, "max_price_micro": { "type": "integer", "minimum": 0, "description": "OpenRouter-style max_price: skip endpoints whose worst-case price is above this" }, "preferred_max_latency_ms": { "type": "integer", "exclusiveMinimum": 0, "maximum": 120000, "description": "Endpoints with a p50 above this are tried after the ones under it" }, "data_policy": { "type": "object", "properties": { "storage": { "type": "string", "enum": [ "any", "reviewed", "storable" ], "default": "any" }, "zdr": { "type": "boolean", "default": false } } }, "require_verified": { "type": "boolean", "description": "Only vendors Relaygrid has verified" } }, "description": "Provider preferences" }, "preset": { "type": "string", "maxLength": 48, "pattern": "^@?(preset\\/)?[a-z0-9]+(-[a-z0-9]+)*$", "description": "Preset" }, "waterfall": { "type": "string", "pattern": "^wf_[a-z0-9]{8,40}$", "description": "Waterfall" } }, "additionalProperties": false, "description": "Routing" }, "data": { "type": "object", "properties": { "fields": { "type": "array", "items": { "type": "string", "maxLength": 80, "pattern": "^[a-z][a-z0-9_]*(\\.[a-z][a-z0-9_]*)*$" }, "maxItems": 50, "description": "Fields" }, "cache": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "prefer", "refresh", "only", "bypass" ], "description": "prefer: use fresh cached fields; refresh: re-fetch; only: never call a vendor" }, "max_age_s": { "type": "integer", "minimum": 0, "maximum": 63072000, "description": "Accept cached values at most this old" }, "ttl_s": { "type": "integer", "minimum": 60, "maximum": 63072000, "description": "Keep what this call fetches for at most this long" }, "stale_while_revalidate_s": { "type": "integer", "minimum": 0, "maximum": 2592000, "description": "Serve an expired value this long past its TTL and refresh it in the background" }, "write": { "type": "boolean", "description": "Store this call's answer in your private cache" }, "class_ttl_s": { "type": "object", "properties": { "work_email": { "type": "integer", "minimum": 60, "maximum": 63072000, "description": "Work email" }, "personal_email": { "type": "integer", "minimum": 60, "maximum": 63072000, "description": "Personal email" }, "phone": { "type": "integer", "minimum": 60, "maximum": 63072000, "description": "Phone" }, "title": { "type": "integer", "minimum": 60, "maximum": 63072000, "description": "Title" }, "firmographics": { "type": "integer", "minimum": 60, "maximum": 63072000, "description": "Firmographics" }, "technographics": { "type": "integer", "minimum": 60, "maximum": 63072000, "description": "Technographics" }, "signals": { "type": "integer", "minimum": 60, "maximum": 63072000, "description": "Signals" }, "verification": { "type": "integer", "minimum": 60, "maximum": 63072000, "description": "Verification" }, "social": { "type": "integer", "minimum": 60, "maximum": 63072000, "description": "Social" }, "other": { "type": "integer", "minimum": 60, "maximum": 63072000, "description": "Other" } }, "additionalProperties": false, "description": "TTL per field class (s)" } }, "additionalProperties": false, "description": "Cache" }, "store": { "type": "object", "properties": { "records": { "type": "boolean", "description": "false = destination-only, nothing cached" }, "bodies": { "type": "boolean", "description": "Keep request and response bodies" } }, "additionalProperties": false, "description": "Storage" } }, "additionalProperties": false, "description": "Data and cache" }, "delivery": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "sync", "wait", "async", "batch", "stream" ], "description": "Mode" }, "webhook": { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "description": "URL" }, "events": { "type": "array", "items": { "type": "string", "enum": [ "completed", "failed", "attempt" ] }, "maxItems": 3, "description": "Events" }, "secret_ref": { "type": "string", "pattern": "^[a-z0-9_-]{1,64}$", "description": "Secret" } }, "required": [ "url" ], "additionalProperties": false, "description": "Webhook" }, "destination": { "type": "string", "pattern": "^[a-z0-9_-]{1,64}$", "description": "Destination" }, "stream": { "type": "string", "enum": [ "sse" ], "description": "Stream" } }, "additionalProperties": false, "description": "Delivery" }, "identity": { "type": "object", "properties": { "idempotency_key": { "type": "string", "pattern": "^[A-Za-z0-9_.:-]{8,128}$", "description": "Idempotency key" }, "dedupe_window_s": { "type": "integer", "minimum": 0, "maximum": 86400, "description": "Dedupe window (s)" }, "meta": { "type": "object", "additionalProperties": { "type": "string", "maxLength": 500 }, "description": "Meta tags" }, "app": { "type": "string", "pattern": "^[a-z0-9][a-z0-9._-]{0,63}$", "description": "App" }, "run": { "type": "string", "maxLength": 128, "description": "Run" }, "end_user": { "type": "string", "maxLength": 128, "description": "End user" } }, "additionalProperties": false, "description": "Identity" }, "observability": { "type": "object", "properties": { "log_level": { "type": "string", "enum": [ "full", "metadata", "none" ], "description": "full keeps bodies; metadata keeps the row only" }, "redact_fields": { "type": "array", "items": { "type": "string", "pattern": "^[A-Za-z0-9_.-]{1,80}$" }, "maxItems": 50, "description": "Redact fields" }, "tail": { "type": "boolean", "description": "Live tail" }, "tail_sample": { "type": "number", "minimum": 0, "maximum": 1, "description": "Tail sample (0–1)" } }, "additionalProperties": false, "description": "Observability" } }, "additionalProperties": false, "description": "Execution options (docs/31): timing, cost, routing, cache, delivery, identity, observability" } }, "required": [ "input" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "call" ] }, "id": { "type": "string" }, "endpoint_id": { "type": "string" }, "provider": { "type": "string" }, "status": { "type": "string", "enum": [ "succeeded", "failed" ] }, "hit": { "type": "boolean" }, "cost_micro": { "type": "integer", "minimum": 0 }, "latency_ms": { "type": "integer", "minimum": 0 }, "credential": { "type": "string", "enum": [ "managed", "byok" ] }, "data": { "type": "object", "additionalProperties": {} }, "raw": {}, "attempts": { "type": "array", "items": { "type": "object", "properties": { "endpoint_id": { "type": "string" }, "provider": { "type": "string" }, "outcome": { "type": "string", "enum": [ "hit", "miss", "failed", "skipped" ] }, "cost_micro": { "type": "integer", "minimum": 0 }, "latency_ms": { "type": "integer", "minimum": 0 }, "error_code": { "type": "string", "enum": [ "invalid_request", "unauthorized", "insufficient_balance", "max_cost_exceeded", "scope_denied", "budget_blocked", "not_found", "idempotency_mismatch", "invalid_meta", "rate_limited", "upstream_error", "response_buffer_limit", "provider_capacity_unavailable", "grid_saturated", "upstream_timeout", "conflict", "internal_error", "account_frozen", "strict_filters", "plan_limit_reached", "validation_failed", "deadline_exceeded", "cancelled" ] } }, "required": [ "endpoint_id", "provider", "outcome", "cost_micro", "latency_ms" ] } }, "meta": { "type": "object", "additionalProperties": { "type": "string" } }, "cache": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "hit", "partial", "miss", "stale", "bypass" ] }, "age_s": { "type": [ "integer", "null" ], "minimum": 0 }, "fetched_at": { "type": [ "string", "null" ], "format": "date-time" }, "saved_micro": { "type": "integer", "minimum": 0 }, "fields_cached": { "type": "array", "items": { "type": "string", "maxLength": 80 }, "maxItems": 100 }, "fields_fetched": { "type": "array", "items": { "type": "string", "maxLength": 80 }, "maxItems": 100 } }, "required": [ "status", "age_s", "fetched_at", "saved_micro" ] } }, "required": [ "object", "id", "endpoint_id", "provider", "status", "hit", "cost_micro", "latency_ms", "credential", "data", "attempts" ] } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "invalid_request", "unauthorized", "insufficient_balance", "max_cost_exceeded", "scope_denied", "budget_blocked", "not_found", "idempotency_mismatch", "invalid_meta", "rate_limited", "upstream_error", "response_buffer_limit", "provider_capacity_unavailable", "grid_saturated", "upstream_timeout", "conflict", "internal_error", "account_frozen", "strict_filters", "plan_limit_reached", "validation_failed", "deadline_exceeded", "cancelled" ] }, "message": { "type": "string" }, "request_id": { "type": "string" }, "call_id": { "type": "string" }, "retry_after_ms": { "type": "integer", "minimum": 0 }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } ```