Build around what the data does
Practical decisions for integrating asynchronous profile extraction, including the cases that are easy to miss.
Search or lookup?
Use filters to discover profiles; max_items is a multiple of 25 between 25 and 2,000. Use lookup when you already have 1–2,000 profile URLs. Lookup normalizes and deduplicates that list, has no search floor and does not use start_page.
Polling and webhook notifications
Polling is the integration path you can implement now: every 5 seconds for the first minute, then every 20 seconds. A webhook_url can receive run.succeeded, run.partial, run.failed or run.cancelled with data.run matching the status response. Profiles are fetched separately. Customer access to the signing secret is not implemented yet, so authenticated polling remains the recommended source of truth; do not trust an unverified incoming notification as proof of completion.
Partial is a result, not an HTTP error
The terminal states are succeeded, partial, failed and cancelled. Partial means the run delivered less than requested; inspect profiles_delivered, failure, pagination and charged. Delivered rows are billed, with the search minimum applying. HTTP 200 when reading a run only means that the status request succeeded.
Reconcile a batch of URLs
Join returned profiles to inputs using requested_url. linkedin_url may contain a newer vanity slug. The run’s unresolved array reports requested_url, reason and detail for URLs without a usable profile: not_found means absent or renamed; unavailable may be worth retrying. Neither is billed. Deduplicate your original list before comparing counts.
Know when data is incomplete
The source measurements found roughly 40% of profiles with truncated experience and 68% with truncated skills. The per-row experience_truncated and skills_truncated flags let you identify them. total_months_experience is an undercount when work history is incomplete. Current role is derived from work history because the source current-position section was empty on 13 of 25 profiles in a verification sample; these are observations, not coverage guarantees.
Search pages are not result cursors
The predecessor’s repeated searches showed 30% overlap between consecutive pages and a drifting reported total in 28% of repeated searches. Prefer one run with an appropriate max_items over several start_page requests. In contrast, downloaded run results use next_cursor: pass it back as cursor until has_more is false.
Understand the invoice
The bill counts inserted profile rows, not requested profiles or raw source items. Each delivered profile costs $0.012. Search has a $0.12 minimum; lookup has no floor. A duplicate inside one run is discarded; the same profile in a later run is billed again. Card top-ups start at $5 and credit does not expire. GET /v1/usage and /v1/me require a signed-in session, not an API key. No subscription, seat fee or monthly minimum. Unused paid balance is not refundable on closure except where legally required or charges were incorrect.