Skip to content
GridRouterhome

Search

Search providers, capabilities and pages

Sign inGet your free API key

Waterfalls

Waterfalls: your own enrichment endpoint, built in minutes

Put providers in order, choose how fast and how far to go, and publish the result as a versioned endpoint your code and agents can call.
Try the demoGet your free API key

See it working

A test run and its estimateDemo dataOpen in the demo

Estimate

per run
Expected cost
$0.0077
Worst case
$0.019
Expected time
1.1 s
Worst case
6.4 s
Expected fill
95%
Eligible steps
3 of 3
Outcome
Hitfirst verified
Cost
$0.006
Per filled field
$0.002
Time
1.5 s · 1.9 s round trip
Attempts
2

Golden record

FieldValueFromStrategyOther values
emailada.lovelace@acme-demo.exampleExample Betaverifiedprefer verified—
email_statusvalidExample Betaverifiedprefer verified—
confidence94Example Betaverifiedprefer verified—

Attempt timeline

  1. Example Alpha
    Miss713 ms$0
    Example Alpha: Miss, started at 0 ms, took 713 ms, cost $0
  2. Example Beta
    Hit817 ms$0.006
    Example Beta: Hit, started at 713 ms, took 817 ms, cost $0.006
The builder's estimate for a three-provider email waterfall, and a simulated run: the first provider missed, the second returned a verified email.

What you get

  • A visual builder with a live estimate

    Drag providers into order and see the expected cost, fill rate and latency update as you go.

  • Speed profiles

    fastest races three providers and hedges; balanced goes one at a time; cheapest goes lowest quote first; or set your own.

  • Stop rules and per-field merge

    Stop at the first hit, the first verified answer or when fields are filled; merge each field by quality, consensus or recency.

  • Pipelines

    Chain up to 10 stages; a later stage reads an earlier stage's output.

  • Sync, async, scheduled and batch

    Run one record in under a minute, or send up to 1,000 rows or a CSV and get a webhook when they're done.

  • Versioned endpoints

    Publish a semver version at /v1/x/{workspace}/{name}, roll back in one click, and call it as an MCP tool.

How it works

  1. Pick a capability and add providers in the order you want them tried.

  2. Set a speed profile, stop rules and how each field is merged, then test it on one record.

  3. Publish a version and call it by name, one record at a time or in batches.

POST /v1/x/{workspace}/{name}
curl https://api.gridrouter.io/v1/x/acme/work-email \
  -H "Authorization: Bearer $GRID_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Prefer: respond-async" \
  -d '{
    "input": { "first_name": "Ada", "last_name": "Lovelace", "domain": "example.com" },
    "webhook_url": "https://example.com/hooks/gridrouter"
  }'

Questions

What does a waterfall cost?

The providers' own prices for the attempts that hit (or that the provider always bills). Misses and failed attempts are free, and a max cost per run caps the worst case.

How is a waterfall different from /v1/run?

/v1/run plans providers for you on every call. A waterfall is your saved plan: fixed order, speed, stop rules and merge, versioned and published under your own name.

Can I run a CSV through it?

Yes. Send up to 1,000 JSON rows or a CSV to the batch endpoint; rows are paced per provider and each result lands in the call log.

Docs and related pages

More in GridRouter

Try it on your own data

Free while we launch. Bring your vendor keys; no card needed.

Get your free API keyTry the demo