# Choosing request depth

> Pick the right depth for latency, coverage, and cost: lookup_mode (fast / balanced / deep), search type (light / medium / premium), the person_enrich tier, and the search feature toggles that change the price.

HTML version: https://api.nyne.ai/documentation/request-depth

Every request trades latency, coverage, and cost against each other. Four dials set that balance: `lookup_mode` on enrichment, the search `type`, the higher-tier `person_enrich` mode, and the search feature toggles that change the price. Deeper is not always better - the right depth is the shallowest one that still answers your question. The ladder runs shallow to deep: `fast` / `light` -> `balanced` / `medium` -> `deep` / `premium`.

## Enrichment depth: lookup_mode

On `/person/enrichment`, the `lookup_mode` field sets how hard the provider waterfalls work. It takes one of three values, and the default is `deep`:

| lookup_mode | Behavior | Latency | Coverage |
| --- | --- | --- | --- |
| fast (prefill timeout 0) | Fast-path: skips the deeper enrichment-prefill augmentation. Lowest latency, lower coverage. | Lowest | Lower |
| balanced (5s prefill timeout) | A 5-second prefill timeout at the initial and post-waterfall stages. The middle ground. | Medium | Medium |
| deep (no timeout cap, default) | Runs the full provider waterfalls with no timeout cap. Highest coverage, highest latency. | Highest | Highest |

Pass it in the JSON body. Here is the middle-ground `balanced` mode:

```bash
curl -X POST https://api.nyne.ai/person/enrichment \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-API-Secret: YOUR_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{ "email": "jane.doe@acme.com", "lookup_mode": "balanced" }'
```

**Deep is the default.** If you send no `lookup_mode`, you get `deep` - the full waterfalls, best coverage, highest latency. Drop to `balanced` or `fast` when a caller is waiting on the response.

## Search tier: type

On `/person/search`, the `type` field picks the search tier. Result quality and coverage rise with the tier, and so does cost. Internally it maps to provider speed tiers (`light` is the fastest, `premium` the deepest). The default is `premium`:

| type | Provider tier | Quality | Notes |
| --- | --- | --- | --- |
| light | Fastest provider tier | Lower | Lowest cost and latency. For light, insights and high_freshness are force-disabled. |
| medium | Middle provider tier | Medium | A balance of result quality and cost. |
| premium (default) | Deepest provider tier | Highest | Highest result quality and coverage, and the highest cost. |

```bash
curl -X POST https://api.nyne.ai/person/search \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-API-Secret: YOUR_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{ "query": "VP of Product in San Francisco", "type": "premium", "show_emails": true }'
```

**type also sets queue priority.** Beyond result depth, `type` maps to the Gearman queue priority that runs your search, so a higher tier can also mean a faster start. Note that for `light`, `insights` and `high_freshness` are force-disabled - they do not apply at the fastest tier.

## The person_enrich tier

Standard `person_enrichment` is the right call most of the time. When it is not enough, the higher-tier `person_enrich` mode forces all newsfeed sources (force-newsfeed) to pull a fuller, fresher record - the complete social activity, not just the merged profile.

It is worth the upgrade for hard-to-find people the standard enrichment misses, or when you specifically need full social activity rather than a static profile. It also costs more: `person_enrich` cross-links additional credit-bearing sources, so reach for it deliberately, not by default. Start standard, escalate when it falls short.

## Search feature toggles that change the price

Several search flags each change the credit price when you turn them on. Broadly, turning more on means better and richer results, a higher cost, and often higher latency. See [Credits & pricing](https://api.nyne.ai/documentation/credits.md) for the exact per-feature costs.

| Toggle | Tradeoff |
| --- | --- |
| show_emails | Return matched email addresses. Adds to the credit price. |
| show_phone_numbers | Return matched phone numbers. Adds to the credit price. |
| insights | Attach AI-derived insights to each result. Richer, higher cost and latency. |
| profile_scoring | Score and rank results against your query. Higher cost. |
| high_freshness | Prefer fresher records over cached ones. Higher cost and latency. |
| require_emails | Drop results without an email. Fewer but better-qualified results. |
| require_phone_numbers | Drop results without a phone. Fewer but better-qualified results. |
| require_phones_or_emails | Drop results without a phone or an email. Fewer but contactable results. |

The `require_*` toggles narrow results rather than enrich them - use them to trim what you never wanted, not to widen coverage. Every added signal has a price; leave off the ones you will not read.

## Picking a depth

Stated plainly: a deeper `lookup_mode`, a higher search `type`, and more toggles all buy you better coverage at a higher cost and higher latency. There is no universally right setting - only the right one for a given call. Start from the use case:

| Use case | lookup_mode | search type | Notes |
| --- | --- | --- | --- |
| Interactive / autocomplete / low latency | fast | light | Answer while the user waits. |
| General enrichment / balanced | balanced | medium | The default-ish middle ground. |
| Hard-to-find / maximum recall / batch | deep | premium | Add person_enrich when the standard record is not enough. |

**Measure on your own data.** These are starting points, not verdicts. Coverage and latency depend on the identifiers and audience you send, so run each candidate depth against a sample of your real inputs before you commit. The [Evaluating the API](https://api.nyne.ai/documentation/evaluating.md) guide walks through how to compare depths fairly.

## What's next

- [Credits & pricing](https://api.nyne.ai/documentation/credits.md) - how each mode, tier, and toggle maps to credits.
- [Writing effective requests](https://api.nyne.ai/documentation/effective-requests.md) - the identifiers and query shapes that raise coverage before you pay for more depth.
- [Evaluating the API](https://api.nyne.ai/documentation/evaluating.md) - measure coverage, latency, and cost on your own data before committing.
- [Async & polling](https://api.nyne.ai/documentation/async.md) - why deeper modes take longer and how to poll for the result.