Web research

Add source-backed web research to the person context available from enrichment.

Start a run

{ "phoneNumber": "+14155550123" }

Knowline enriches the number using the default lookup sequence and starts research only after a person match. No person match returns 404. A lookup failure stops the request before research starts.

A successful create returns HTTP 202. Save the run ID before doing anything else.

// Response excerpt
{
  "runId": "agent_run_example",
  "status": "queued"
}

The response also includes enrichmentStatus with lookup-match flags. These describe matches rather than source availability. Add ?includeEnrichment=true to include the original enrichment in the create response without repeating the lookup.

Read the current snapshot

Your application owns polling. States are queued, running, completed, failed, and cancelled. Research can return structured output, text, grounding citations, usage, and costs when available.

Completion and coverage

Inspect stopReason: schema_satisfied, budget_reached, stopped, error, or cancelled. A completed run can still have unsupported fields and coverage gaps. Output is candidate context, and results require judgment.

Handle an ambiguous create carefully

Some upstream errors include mayHaveStarted. Do not automatically repeat a create after an ambiguous failure: the first request may already have started a billable run. Preserve a returned run ID and follow the retry guidance.