aVenture APIHarness Runs

Enrich one person

View as Markdown

Queues an enrichment run for the addressed person, owned by the authenticated principal. The run targets that person’s canonical aVenture profile, so it is billed as an update of a known record and reuses the person’s already-active run.

Authentication

AuthorizationBearer

User bearer token: Clerk session JWT, Clerk OAuth access token, or Clerk personal API key

Path parameters

personIdstringRequiredformat: "uuid"
Canonical person UUID.

Query parameters

modeenumOptional

Enrichment breadth; omitted requests the comprehensive default.

Allowed values:
modelstringOptional

Orchestrator model override; omitted uses the configured role default.

userPromptstringOptional
Optional steering prompt.
taskPresetKeylist of stringsOptional
Task preset keys that scope or emphasize this run.

Response

OK
attemptinteger
Retry attempt counter
createdAtdatetime
Creation timestamp
environmentenum
API environment
hasSourceDocumentboolean
Whether this run consumes an immutable private source document
idstringformat: "uuid"
Run id
iterationinteger
Current loop iteration
maxIterationinteger
Loop iteration cap
maxScoutConcurrentinteger

Parallel read-only scout fan-out width N

modeenum
Enrichment breadth selected for this run
modelstring
Orchestrator model id
statusenum
Current lifecycle state
subagentModelstring

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

typeenum

Run kind derived from task-key presence: ENRICHMENT for a client-submitted comprehensive or preset-scoped run, TASK for a platform-scheduled micro-task execution

updatedAtdatetime
Last update timestamp
urlstring
Company URL under enrichment
entitySlugstring or nullOptional
Canonical slug of the entity the run produced
errorstring or nullOptional
Terminal failure reason, when 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
Selected task preset keys filed with the run
userPromptstring or nullOptional
Optional steering prompt filed with the run

Errors

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