Skip to navigation
aVenture APIAgents and SystemResearch Runs

Enrich One Company, Product, or Service

View as Markdown

Queues a run that researches the addressed entity and updates its aVenture profile, owned by the authenticated caller. Take entityId from match.owner when POST /v1/lookup or POST /v1/entities/lookup returns MATCHED (CLI: lookup, entities lookup). When a run for this entity is already queued or running, returns that run instead of queuing and charging another; a new run reserves one company research unit from the plan’s research allowance, spent only once the run saves a research write and returned when it ends without one. After the run completes, read the updated profile with GET /v1/entities/{entityId} (CLI: entities get). Check the run’s progress with GET /v1/research-runs/{runId} (CLI: research-runs get).

Authentication

AuthorizationBearer

Your aVenture API key (https://aventure.vc/settings/api-keys) or OAuth access token

Path parameters

entityIdstringRequiredformat: "uuid"
Canonical entity UUID.

Query parameters

modeenumOptional

COMPREHENSIVE (the default) researches the whole profile; INDIVIDUAL runs only the tasks named in taskPresetKey.

Allowed values:
modelstringOptional

Model id for the run’s lead agent; omit to use aVenture’s default model.

userPromptstringOptionalDeprecated

Deprecated: send userPrompt in the EnrichmentPrompt body. Used only when the body carries no userPrompt; longer than 2000 characters is refused with 400.

taskPresetKeylist of stringsOptional

Task preset keys that scope or emphasize this run; at least one is required when mode is INDIVIDUAL, and an unknown key is a 400.

Request

This endpoint expects an object.
userPromptstring or nullOptional0-2000 characters

Plain-language instruction for this run, such as which facts or sources to check first

Response headers

X-RateLimit-Limitinteger

Requests allowed per client IP in the current rate-limit window.

X-RateLimit-Remaininginteger

Requests left before the tightest applicable rate-limit bucket rejects.

X-RateLimit-Resetinteger

Seconds until the exhausted rate-limit bucket admits another request; 0 when none is exhausted.

Response

The queued enrichment run for the addressed entity.
attemptinteger
Retry attempt counter
chassisenum
Agent loop this run executes on
Allowed values:
chassisRoutedboolean

True when the chassis router, not a caller, picked chassis

createdAtdatetime
Creation timestamp
environmentenum
API environment
Allowed values:
hasSourceDocumentboolean
Whether this run consumes an immutable private source document
idstringformat: "uuid"
Run id
iterationinteger
Current loop iteration
laneenum
Queue lane for admission priority
Allowed values:
llmApienum
Gateway wire API every LLM call of this run uses
Allowed values:
maxIterationinteger
Loop iteration cap
maxScoutConcurrentinteger

Parallel read-only scout fan-out width N

modeenum
Enrichment breadth selected for this run
Allowed values:
modelstring
Model the run uses
statusenum
Current lifecycle state
Allowed values:
subagentModelstring

Read-only research, cohort, and completion sub-agent model id

typeenum

Run kind: ENRICHMENT for a research request a caller filed, TASK for a narrower run aVenture scheduled

Allowed values:
updatedAtdatetime
Last update timestamp
urlstring
URL of the company, Product, Service, or person under research
entitySlugstring or nullOptional
Slug of the profile the run produced
errorstring or nullOptional

Why the run failed; null unless failed

failureClassstring or nullOptional

Typed terminal-failure class from the harness retry classifier (e.g. runtime_cap, escalated, provider_capacity, context_overflow); null unless failed

finishedAtdatetime or nullOptional
Run completion timestamp
latestStatusstring or nullOptional

Latest enrich-loop status as an opaque JSON string

nextAttemptAtdatetime or nullOptional

Earliest re-claim time when waiting on retry backoff

resumeSafeUntildatetime or nullOptional

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.

startedAtdatetime or nullOptional
Run start timestamp
taskPresetKeylist of strings or nullOptional
Research presets filed with the run
userPromptstring or nullOptional
Optional instructions filed with the run

Errors

400
Bad Request Error
401
Unauthorized Error
402
Payment Required Error
403
Forbidden Error
404
Not Found Error
406
Not Acceptable Error
409
Conflict Error
415
Unsupported Media Type Error
422
Unprocessable Entity Error
429
Too Many Requests Error
500
Internal Server Error
503
Service Unavailable Error