# Waterfall enrichment explained: how it works and where it breaks

Waterfall enrichment tries one data provider, then the next on a miss. How it works, why order matters, a prompt to run it with an agent, and the limits.

## Summary

Waterfall enrichment is a simple idea. You ask one data provider for a field. If it has the answer, you stop. If it does not, you ask the next provider, and so on until you get an answer or run out of providers.

People know the term from Clay enrichment, where the waterfall is a set of columns. The idea is older and simpler than any one tool. This post explains how it works, what decides whether it pays off, and where it fails.

## Why a waterfall exists

No single provider knows everyone. One may be strong on US software companies. Another may know more about small businesses in Europe. If you rely on one, every row it misses stays empty.

A waterfall turns many partial sources into one better source. You pay for extra calls only on the rows that need them.

## How it works, step by step

1. Take a row, for example a person and a company domain.
2. Call the first provider for the field you want, say a work email.
3. If the result is a real value, store it, note which provider answered, and stop.
4. If the result is empty or fails a check, call the second provider.
5. Repeat until a provider answers or the list ends.
6. If nothing answers, mark the row as not found. Do not fill it with a guess.

Step three has a trap. A provider may return a value that looks right but is not. For emails, add a verification call before you accept the result.

## Why the order matters

Every row goes through the first provider. Only the misses go to the second. So the first provider decides most of your cost and most of your speed.

There are two sensible ways to order the list. One is cheapest first, which keeps the average price low when the cheap provider hits often. The other is highest hit rate first, which keeps the number of calls low. Measure both on a sample of 100 rows and compare the cost per row that returned a value.

Tip: Put a provider that bills for misses behind one that does not, when their hit rates are close. You then pay for fewer misses.

## What a miss costs

Whether a miss costs money depends on the provider. Some bill only for found values. Some bill every call. Read the endpoint page before you assume a miss is free. The live block below shows the current cheapest priced work email endpoint, and the [public catalog](https://looot.ai/public-catalog) shows the rest.

Cheapest live price for the first step of an email waterfall: live prices per lookup are read from the catalog when the page loads, see https://looot.ai/blog/waterfall-enrichment-explained.

- Find a work email
- Verify an email

## Running a waterfall with an agent

In a spreadsheet tool the waterfall is columns and conditions you click together. With an agent it is a few lines of instruction. looot holds several email providers behind one key, so the agent does not need a separate account for each step.

The column that records which provider answered is the useful part. Over a few hundred rows it tells you which provider earns its place in the order.

## Honest limits

A waterfall raises coverage. It does not create data that no provider has. If a person has no public work email anywhere, adding a fifth provider will not find one.

It also raises cost per row on the hard rows. The rows that fall through every step cost the most and return nothing. Set a cap on how many providers you try.

Quality can drift. A second provider may return a lower-confidence value than the first. Keep the verification step so a weak match does not slip through.

Finally, a waterfall is a one-off run unless you repeat it. Re-running a list on a schedule needs scheduled runs, which are not available yet. For now you ask your agent to run it again.

## When it is not worth it

- Your list is small. Calling one good provider and checking by hand is faster.
- You need a field only one provider sells. There is nothing to fall back to.
- Your hit rate on the first provider is already high, so the second step rarely runs.

Look at your own numbers before you build the extra steps. The method is the same one in the [Clay alternatives post](https://looot.ai/blog/clay-alternatives-for-ai-agents), and the cost side is in [what 1,000 lookups cost](https://looot.ai/blog/what-1000-lookups-cost).

[See the enrich a company list recipe](https://looot.ai/recipes/enrich-a-company-list)

## Questions

### What is waterfall enrichment?

Waterfall enrichment asks one data provider for a field and, when it finds nothing, asks the next provider, until a provider answers or the list ends.

### How does Clay enrichment waterfall work?

In Clay the steps are columns with conditions. An agent can do the same in a prompt or script, calling providers in order and stopping at the first valid answer.

### Does the order of waterfall enrichment matter?

Yes. Every row hits the first provider, so it drives most of your cost and speed. Test cheapest first against highest hit rate first on a sample.

### Does a miss cost money in waterfall enrichment?

It depends on the provider. Read the endpoint page. Some bill only found values and some bill every call.

### Can waterfall enrichment find every email?

No. It raises coverage by combining providers. If no provider has the address, the row stays not found.

### Can I schedule waterfall enrichment to repeat?

Scheduled runs are not available yet in looot. You ask your agent to run the waterfall again when you need it.

## For agents

### Prompt for an email waterfall

```text
For each person and company domain I give you, find a work email. Try the cheapest email finder first. If it returns nothing, try the next one. Verify every address you find. Return a table with the email, the verification result and the provider that answered. Mark rows as not found if every provider fails. Run the first 10 rows and stop so I can check them.
```