# Run a waterfall (/docs/api/waterfalls/waterfall_run) Run a waterfall on one input. Sync by default; Prefer: wait=N (or wait) falls back to 202, Prefer: respond-async (or async: true) returns 202 with a run to poll, stream (/events) or receive by webhook. version draft runs the test runner. `POST /v1/waterfalls/{id}/run` ```json { "operationId": "waterfall_run", "summary": "Run a waterfall", "description": "Run a waterfall on one input. Sync by default; Prefer: wait=N (or wait) falls back to 202, Prefer: respond-async (or async: true) returns 202 with a run to poll, stream (/events) or receive by webhook. version draft runs the test runner.", "tags": [ "waterfalls" ], "security": [ { "bearer": [] } ], "parameters": [ { "schema": { "type": "string", "pattern": "^wf_[a-z0-9]{8,40}$" }, "required": true, "name": "id", "in": "path" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "input": { "type": "object", "additionalProperties": {} }, "version": { "anyOf": [ { "type": "string", "enum": [ "published", "draft" ] }, { "type": "string", "pattern": "^\\d{1,4}\\.\\d{1,4}\\.\\d{1,4}$" } ], "default": "published" }, "max_cost_micro": { "type": "integer", "minimum": 0 }, "fields": { "type": "array", "items": { "type": "string", "maxLength": 80, "pattern": "^[a-z][a-z0-9_]*(\\.[a-z][a-z0-9_]*)*$" }, "maxItems": 50 }, "include_raw": { "type": "boolean", "default": false }, "webhook_url": { "type": "string", "format": "uri" }, "delay_seconds": { "type": "integer", "minimum": 1, "maximum": 43200 }, "wait": { "type": "integer", "minimum": 0, "maximum": 60 }, "async": { "type": "boolean", "description": "Same as Prefer: respond-async" }, "meta": {}, "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); explicit fields above win over them" } }, "required": [ "input" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "waterfall_run" ] }, "id": { "type": "string", "pattern": "^wfr_[a-z0-9]{8,64}$" }, "waterfall_id": { "type": "string" }, "version": { "type": "string" }, "mode": { "type": "string", "enum": [ "sync", "wait", "async", "batch", "list", "scheduled", "test" ] }, "status": { "type": "string", "enum": [ "queued", "running", "completed", "failed", "cancelled" ] }, "outcome": { "type": [ "string", "null" ], "enum": [ "hit", "partial", "miss", "failed", null ] }, "stop_reason": { "type": [ "string", "null" ], "enum": [ "first_hit", "first_verified", "until_fields_filled", "all_then_merge", "condition", "exhausted", "budget_exceeded", "deadline_exceeded", "cancelled", "account_error", null ] }, "data": { "type": "object", "additionalProperties": {} }, "_provenance": { "type": "object", "additionalProperties": { "type": "object", "properties": { "provider": { "type": "string" }, "endpoint_id": { "type": "string" }, "call_id": { "type": [ "string", "null" ] }, "stage_id": { "type": "string" }, "step_id": { "type": "string" }, "fetched_at": { "type": "string", "format": "date-time" }, "confidence": { "type": [ "number", "null" ] }, "verified": { "type": [ "boolean", "null" ] }, "strategy": { "type": "string", "enum": [ "highest_quality", "consensus", "most_recent", "prefer_verified", "first_non_null", "union" ] }, "conflicts": { "type": "array", "items": { "type": "object", "properties": { "provider": { "type": "string" }, "value": {} }, "required": [ "provider" ] }, "maxItems": 20, "default": [] } }, "required": [ "provider", "endpoint_id", "call_id", "stage_id", "step_id", "fetched_at", "confidence", "verified", "strategy" ] } }, "_attempts": { "type": "array", "items": { "type": "object", "properties": { "stage_id": { "type": "string" }, "step_id": { "type": "string" }, "endpoint_id": { "type": "string" }, "provider": { "type": "string" }, "call_id": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "hit", "miss", "failed", "skipped", "timeout", "cancelled" ] }, "reason": { "type": [ "string", "null" ], "enum": [ "circuit_open", "over_step_budget", "over_run_budget", "missing_input", "unsupported_mode", "not_eligible", "condition_false", "deadline", "stopped", "low_confidence", "missing_fields", "unverified", "client_error", "rate_limited", "server_error", "timeout", "account", null ] }, "try": { "type": "integer", "minimum": 0 }, "hedged": { "type": "boolean" }, "cost_micro": { "type": "integer", "minimum": 0 }, "quote_micro": { "type": "integer", "minimum": 0 }, "started_ms": { "type": "integer", "minimum": 0 }, "latency_ms": { "type": "integer", "minimum": 0 }, "verified": { "type": [ "boolean", "null" ] }, "confidence": { "type": [ "number", "null" ] }, "fields": { "type": "array", "items": { "type": "string" } }, "error": { "type": [ "object", "null" ], "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", "maxLength": 500 }, "upstream_status": { "type": [ "integer", "null" ] }, "retry_after_ms": { "type": [ "integer", "null" ], "minimum": 0 } }, "required": [ "code", "message", "upstream_status", "retry_after_ms" ] }, "raw": {} }, "required": [ "stage_id", "step_id", "endpoint_id", "provider", "call_id", "status", "reason", "try", "hedged", "cost_micro", "quote_micro", "started_ms", "latency_ms", "verified", "confidence", "fields", "error" ] } }, "stages": { "type": "array", "items": { "type": "object", "properties": { "stage_id": { "type": "string" }, "capability": { "type": "string" }, "outcome": { "type": "string", "enum": [ "hit", "partial", "miss", "failed" ] }, "stop_reason": { "type": "string", "enum": [ "first_hit", "first_verified", "until_fields_filled", "all_then_merge", "condition", "exhausted", "budget_exceeded", "deadline_exceeded", "cancelled", "account_error" ] }, "data": { "type": "object", "additionalProperties": {} }, "cost_micro": { "type": "integer", "minimum": 0 }, "latency_ms": { "type": "integer", "minimum": 0 } }, "required": [ "stage_id", "capability", "outcome", "stop_reason", "data", "cost_micro", "latency_ms" ] } }, "fields_filled": { "type": "array", "items": { "type": "string" } }, "cost_micro": { "type": "integer", "minimum": 0 }, "cost_per_field_micro": { "type": "integer", "minimum": 0 }, "latency_ms": { "type": "integer", "minimum": 0 }, "input": { "type": "object", "additionalProperties": {} }, "error": { "type": [ "object", "null" ], "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" } }, "required": [ "code", "message" ] }, "batch_id": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "completed_at": { "type": [ "string", "null" ], "format": "date-time" }, "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", "waterfall_id", "version", "mode", "status", "outcome", "stop_reason", "data", "_provenance", "_attempts", "stages", "fields_filled", "cost_micro", "cost_per_field_micro", "latency_ms", "error", "batch_id", "created_at", "completed_at" ] } } } }, "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" ] } } } } } } ```