Read or run Dex Research on a contact (v2)
Dex Research: a cited web research note about one contact (who they are, current focus, background, interests) plus structured findings (LinkedIn, website, email, phone) with per-finding confidence and evidence. The default body ({}) only READS the stored research and never generates — research is null when nothing has been researched yet — and reports where the contact's current or latest run is (in_progress, stage, run_id, failure). { run: true } starts the pipeline (web search + page extraction + LLM summary); a run whose stored result is under 30 days old returns the cached note at once unless force: true. Otherwise the run executes in the background and the call answers immediately with in_progress: true and the run's run_id — poll the default body every few seconds until in_progress is false: the run finished when research.run_id equals that run_id, and failed when failure is set (unavailable: a research provider is down, retry later). Runs usually take 20–60 seconds and occasionally over two minutes. in_progress: true on a run request can also mean another request's run is already in flight — poll it the same way instead of starting another. A run auto-fills the contact's EMPTY linkedin / website fields when a high-confidence finding exists (those findings come back auto_applied); email and phone findings stay pending for the user to apply. A run request that would start a paid run is refused with 429 research_limit_reached once the user has used up a fair-use window — 100 runs per UTC calendar month and 50 per UTC day, counting forced re-runs and runs that later fail but never cache hits or a run already in flight — with error.details { window: "month" | "day", limit, resets_at } and Retry-After set to the seconds until resets_at. Unlike the per-minute rate_limited 429 it will not clear on a retry: do not retry before resets_at. The default-body read is never limited this way. 404 when the contact does not belong to the authenticated user.
Path parameters
Headers
Optional. Accepted to dedupe retries on this endpoint. See apps/rest-api/src/shared/idempotency.ts.
Request body
Response
Successful response
Changes
Changed in 2 of the 37 revisions of this API.4
- ○
added the required property
/to the response with the statusresponse-required-property-added
- ○
added the required property
/to the response with the statusresponse-required-property-added
- ○
added the required property
/to the response with the statusresponse-required-property-added
- ○
- ○
endpoint added
endpoint-added
- ○