Data freshness

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`	Whether the profile exists and when it was last updated	0	Instant
Fetch	`/v2/fetch/*`	Cached profile data	1	Instant
Live	`*/live`	Fresh data delivered via webhook	2	Async

Optimize your requests

Use Check → Fetch → Live to optimize every request:

Decision tree

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

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)