Sync vs async
Which Fiber operations return in one call, which run as background jobs, how batch jobs are charged, and how to paginate every family correctly.
Sync vs async
Most Fiber operations are synchronous: you call, you wait, results come back. The slow or large ones are asynchronous: you start a job, get an ID back immediately, and poll until it is done. Picking the right mode, and paginating the way each family expects, is the difference between a clean integration and one that times out at the worst moment.
Synchronous calls, and how slow they really are
Single-record lookups (person or company enrichment, live LinkedIn fetches, social lookups) return in seconds. Search endpoints return the first page in seconds too. A few synchronous operations are genuinely slow because of amount of processing they do: natural-language search, multi-source search, and website screenshots all carry a one-minute recommended client timeout. Set your HTTP client's timeout to 60 seconds for those, and page through results only after the first page lands.
The async pattern
Every async operation is a trigger plus a poll, sometimes with a cancel:
- Start. Call the trigger with your full input. You get a job ID at once, plus how many items were enqueued (duplicates are skipped and reported, not charged).
- Poll. Call the poll with the job ID until a
doneflag or a completed status appears. Polling is always free. - Collect. Results page out with the poll using a cursor; statuses end
at done/failed (a
canceledstate exists where cancel is offered). - Optionally, cancel. Batch contact reveal supports cancel, which stops the job and refunds the profiles it never reached. Already-delivered results stay charged.
Job results stay available for retrieval after completion, so a crashed worker can re-poll later instead of re-paying. For batch contact reveal, the legacy storage window was 30 days; current jobs live in our primary store with no removal schedule you need to race.
How async jobs are charged
Charging happens when the job starts, sized by the items enqueued
(deduped, not raw input). If a job cannot deliver everything it charged for,
the shortfall is refunded automatically: malformed identifiers are refunded
on the spot, and whatever the workers cannot deliver is refunded as the job
finishes. A failed start is refunded in full. The response's chargeInfo
block is always the authoritative amount charged.
Inputs and outputs
What each async family returns, its caps, and its poll page size:
| Family | Trigger returns | Batch cap | Poll page size |
|---|---|---|---|
| Batch contact reveal | taskId, enqueued and duplicate counts | 2,000 people | cursor, up to 100 |
| Batch live LinkedIn fetch | taskId, enqueued count | 10,000 identifiers | cursor, up to 100 |
| Exhaustive contact reveal | taskId | 1 person (deepest pass) | single response |
| Google Maps business sweep | searchId | 10,000 businesses | cursor, up to 1,000 |
| Domain lookup (AI agent) | run ID | 400 companies | cursor, up to 100 |
| Local business AI search | run ID | 500 companies | cursor, up to 1,000 |
| GitHub to LinkedIn | run ID | 1,000 usernames | cursor, up to 100 |
| LinkedIn to GitHub | run ID | 1,000 people | single response |
| Social media batch lookup | run ID, enqueued count | 100 people | nextPageToken, up to 100 |
| Depth chart | report ID | 10,000 employees per report | single report |
Full request and response shapes for every pair live in the operation's reference page linked from the operations index.
Pagination, family by family
| Style | Where you see it | Mechanics |
|---|---|---|
cursor / nextCursor | Structured search (people, companies, jobs, stealth founders), combined search, audiences and saved-search reads, most poll endpoints | Opaque keyset cursor. Pass the returned cursor to get the next page; an absent cursor means the end. Max page size is 1,000 for searches, 100 to 500 for list reads. |
pageToken / nextPageToken | Natural-language search, social media batch poll, TikTok, Instagram, YouTube, Reddit | Same loop, Google-style naming. Social networks page at vendor-fixed sizes; natural-language search pages up to 1,000. |
request: "initial" / "subsequent" | Multi-source search, combined search | Page size locks in on the initial call; subsequent calls send only the cursor while the server remembers your query. |
cursor + take | Batch reveal and batch live-fetch polls | Fetch up to take (max 100) results per poll. |
| Offset tokens | Yelp business search and reviews | The token wraps the offset; pages are fixed at 10 businesses or 49 reviews. |
Two rules to save you the trouble:
- Never change filters mid-pagination. : Changing the parameters with an old cursor provided can result in unexpected behaviour. Some poll endpoints don't allow you to do that. Some endpoints won't check parameters when a pagination cursor is provided.
- Empty string is not page one. A blank cursor is rejected, not treated as the first page. First call: omit the field.
Using it effectively
- Count before you search, batch before you loop. One batch call processing 2,000 people beats 2,000 sequential single calls on throughput and on rate limits, and the per-item price is the same.
- Respect the trigger limits. Triggers run at 10 to 30 requests per minute depending on family; polls allow 120 to 360. Pace starts, poll as often as you like.
- Let webhooks replace the poll loop. Every async family emits a completion event, so you can stop polling entirely and react. See Webhooks.
- For small result sets, stay synchronous. Under ~1,000 results, the paginated sync search endpoints are simpler and just as fast; batch jobs earn their setup cost at scale.
- Small budgets: use per-key credit ceilings. Async jobs charge upfront, so cap what a given API key can spend before you wire an unsupervised worker to a trigger. See API keys.
Use cases
- Nightly enrichment of yesterday's saved-search output (batch reveal, poll with webhooks as the completion signal).
- One-off backfills (batch live fetch at 10,000 identifiers per job).
- Interactive tools where sync lookups keep the UI simple.
Operations
| Operation | What it does | Reference |
|---|---|---|
| Batch contact reveal (start) | Enqueue up to 2,000 people for email and phone reveal | startBatchContactDetails |
| Batch contact reveal (poll) | Page through completed results, free | pollBatchContactDetails |
| Batch live fetch (start) | Enqueue up to 10,000 identifiers for live LinkedIn refresh | startBatchLiveEnrich |
| Google Maps sweep (start) | Sweep a geography for local businesses, up to 10,000 | google-maps-search |
| Social media batch lookup (start) | Person-first social lookup for up to 100 people | socialMediaLookupBatchTrigger |
| People search | Synchronous structured search, up to 1,000 per page | peopleSearch |
Credits for async jobs are charged at trigger time by items enqueued; polls are free. See Billing for the full pricing table.