Waterfalls

A waterfall is an enrichment strategy that tries providers in order until one returns a usable result. Use it when multiple providers solve the same problem with different coverage, latency, and price.

Shape

Field	Notes
`capability`	`work_email`, `mobile_phone`, or `linkedin_url`
`providers`	Ordered list of provider tools
`inputs`	Mapping from row fields to provider input names
`stop_when`	Optional predicate; defaults to "first non-null, non-error result"
`max_credits`	Hard run-level credit ceiling

Built-in strategies

Capability	Output
`work_email`	Work email, confidence, and provider provenance
`mobile_phone`	Mobile phone, region, optional verification
`linkedin_url`	LinkedIn profile URL, match confidence, and provider provenance

Preview output shows the current provider order and access status before you run live.

Previewing an enrichment

oxygen enrich-column preview <contacts-table> \
  --capability work_email \
  --linkedin-url-column linkedin_url \
  --company-domain-column domain \
  --limit 10 \
  --json

Override the default provider order with --provider-order when you have a reason to prefer a specific sequence.

Per-cell provenance

A waterfall-style enrichment cell records the call trace:

{
  "value": "ada@acme.com",
  "provenance": {
    "winning_provider": "leadmagic",
    "attempts": [
      { "provider": "hunter", "status": "not_found", "credits": 0 },
      { "provider": "leadmagic", "status": "succeeded", "credits": 1, "confidence": "verified" }
    ],
    "total_credits": 1
  }
}

Inspect with oxygen cells inspect.

Cost behavior

Credits charge per successful paid attempt according to provider behavior. A waterfall that resolves early usually costs less than one that exhausts the provider list. Use --max-credits on the live run to cap total spend.

Running live

oxygen enrich-column run <contacts-table> \
  --capability work_email \
  --linkedin-url-column linkedin_url \
  --company-domain-column domain \
  --limit 100 \
  --max-credits 100 \
  --json

Company field enrichment has its own helper:

oxygen companies enrich preview <accounts-table> --missing-fields headcount,industry --limit 10 --json
oxygen companies enrich run <accounts-table> --missing-fields headcount,industry --limit 100 --max-credits 100 --json

Columns — enrichment columns and materialized outputs.
Provider catalog — picking individual providers.
Cells — inspecting per-attempt history.