# Data freshness

> Choose the right endpoint mode for your freshness and cost requirements.

You control the balance between data freshness and cost. The API offers three modes. Pick the one that fits your use case.

## Three modes

| Mode | Endpoint pattern | What you get | Credits | Speed |
| ---- | ---------------- | ------------ | :-----: | :---: |
| **Check** | [`*/check`](https://docs.reversecontact.com/endpoints/check-person) | Whether the profile exists and when it was last updated | 0 | Instant |
| **Fetch** | [`/v2/fetch/*`](https://docs.reversecontact.com/endpoints/fetch-profile) | Cached profile data | 1 | Instant |
| **Live** | [`*/live`](https://docs.reversecontact.com/endpoints/fetch-profile-live) | Fresh data delivered via webhook | 2 | Async |

## Optimize your requests

Use Check → Fetch → Live to optimize every request:

**Decision tree**

```bash [Text]
1. Call CHECK (free)
   │
   ├─ Profile not found?
   │  └─ Call LIVE (2 credits) → fresh data via webhook
   │
   └─ Profile found
      │
      ├─ Updated recently (< your threshold)?
      │  └─ Call FETCH (1 credit) → instant cached data
      │
      └─ Data is stale?
         └─ Call LIVE (2 credits) → fresh data via webhook
```

This pattern can **cut your costs by up to 50%** if many of the profiles you query are already fresh in our database.

## When to use each mode

### Check (0 credits)

- Before every fetch/live call in a batch pipeline
- To monitor data freshness across your lead list
- To build a smart queue that prioritizes stale profiles for live refresh

### Fetch (1 credit)

- When the profile exists and was updated within your acceptable freshness window
- For high-volume pipelines where real-time accuracy isn't critical
- As the default mode. Fall back to Live only when Check shows stale data

### Live (2 credits)

- When the profile doesn't exist in our database yet
- When cached data is too old for your use case
- For high-stakes enrichment (e.g. before a sales call or outreach campaign)
- For activity endpoints (posts, comments, reactions) which are always live

## Example: batch pipeline

Here's a pipeline that enriches 1,000 profiles at minimum cost:

**Batch pipeline**

```bash [Text]
For each profile URL:
  1. POST /v2/fetch/persons/check  (free)
  2. If exists + updated < 30 days:
       POST /v2/fetch/persons       (1 credit)
  3. Else:
       POST /v2/fetch/persons/live  (2 credits, webhook)
```

If 60% of profiles are fresh in our database, the cost for 1,000 profiles is:

- 600 × 1 credit (Fetch) = 600
- 400 × 2 credits (Live) = 800
- **Total: 1,400 credits** (vs 2,000 if using Live for all)