Research a Company or Person by URL
Files a research request for the company, Product, Service, or person at url and returns the run, owned by you. Send name when known. A url an existing profile owns refreshes that profile; any other url researches a new one, so this is how to add a subject that POST /v1/lookup answers NO_MATCH. A new run reserves one company or person research unit, spent only once the run saves research and returned when it ends without any. Your own queued or running run for the same subject, mode, and presets is returned instead, uncharged. A record is researched at most once per rolling 24 hours across all callers: while it is already being researched, or when research on it completed inside that window, nothing is filed or charged and the request answers 429 whose detail says when to retry. A url that matches more than one record answers 409, and a spent allowance answers 429. You may set only url, name, model, mode, userPrompt, taskPresetKey, and finding; any other field is refused with 403, and a userPrompt longer than 2000 characters is refused with 400. Follow progress with GET /v1/research-runs/{runId}; you are notified when the run completes.
Authentication
Your aVenture API key (https://aventure.vc/settings/api-keys) or OAuth access token
Request
Official website or profile URL of the company, Product, Service, or person to research; a URL no current record owns researches a new one
Facts you already researched, each citing the page and exact text that support it. Send them with a taskPresetKey whose task accepts findings; the run checks each quote against its page and writes only the facts it confirms. Any other run refuses findings with 400.
Optional orchestrator model override; omitted uses the configured role default
Name of the subject at url, such as Clarity Health; the run verifies it and uses it to pick the right subject when the site names several
Response headers
Requests allowed per client IP in the current rate-limit window.
Requests left before the tightest applicable rate-limit bucket rejects.
Seconds until the exhausted rate-limit bucket admits another request; 0 when none is exhausted.
Response
True when the chassis router, not a caller, picked chassis
Parallel read-only scout fan-out width N
Read-only research, cohort, and completion sub-agent model id
Run kind: ENRICHMENT for a research request a caller filed, TASK for a narrower run aVenture scheduled
Why the run failed; null unless failed
Typed terminal-failure class from the harness retry classifier (e.g. runtime_cap, escalated, provider_capacity, context_overflow); null unless failed
Latest enrich-loop status as an opaque JSON string
Earliest re-claim time when waiting on retry backoff
Instant past which a warm resume is no longer guaranteed; the harness writes it with session_resume from the model’s cache window. Warm-resumable now iff failed/stopped and this is in the future. Null when there is no resume window.