> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.aventure.vc/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.aventure.vc/_mcp/server.

# Get One Research Run

GET https://api.aventure.vc/v1/research-runs/{runId}

Returns one of your research runs with its status, latest progress, and, once available, the resulting profile and its public URL.

Reference: https://docs.aventure.vc/api-reference/research-runs/get-research-run

## Authentication

- `Authorization` header (bearer token, required) — Your aVenture API key (https://aventure.vc/settings/api-keys) or OAuth access token

## Request

### Path parameters

- `runId` (string, required) — Research run id

## Response

### 200

OK

- `run` (HarnessRun, required) — The research run
- `entity` (Entity, optional, nullable) — Current public profile the run resolved to
- `latestStatus` (HarnessRunProgress, optional, nullable) — Latest research progress; null when none is available
- `provider` (Entity, optional, nullable) — Parent organization's core record when the resolved entity is a Product/Service; null for every other entity type
- `publicUrl` (string, optional, nullable) — Exact renderable public profile URL for the resolved entity

## Errors

### 400 Bad Request Error

Bad Request

- `allowanceType` (enum, optional) — Which monthly allowance a BILLING_ALLOWANCE refusal exhausted.
  - Allowed values: `COMPANY`, `PERSON`, `ENTITY_VIEW`, `ENTITY_BRAND`, `PERSON_VIEW`, `WEB_SEARCH`
- `circuitBreaker` (string, optional, nullable)
- `code` (string, optional, nullable) — Machine-readable secondary code on ProblemDetail.code. Agents should branch on this value when the HTTP status alone does not identify the recovery path. Code groups include auth/session, rate limiting, job infrastructure, RBAC, external providers, image processing, R2 storage, search, and inference. Many codes describe server-side conditions a caller cannot fix: surface the error and stop rather than retry.
- `conflictingRecord` (CurrentSlugOwner, optional, nullable) — Current slug owner
- `detail` (string, optional)
- `details` (DomainConflictDetails, optional, nullable) — Structured conflict details. A possible duplicate or an ambiguous lookup returns its candidate records; score and threshold rank the candidates and do not prove that the requested record is absent.
- `error` (map from string to string, optional, nullable)
- `existingRecordId` (string, optional, nullable) — On a duplicate 409, the id of the stored record the request collided with; read or update that record instead of creating it again. Absent when the conflict names no single stored record.
- `existingRedirect` (RedirectSlugPath, optional, nullable) — Redirect slug path
- `feId` (string, optional, nullable)
- `field` (string, optional, nullable)
- `filedRunId` (list of string, optional, nullable) — Research request ids a batch filed or reused for its other records before returning this error; absent for every other error.
- `hammingDistance` (long, optional, nullable)
- `hint` (string, optional, nullable)
- `instance` (string, optional)
- `limit` (long, optional, nullable) — Cap the limitType meter allows for its current period.
- `limitType` (enum, optional) — Which meter refused the request; names what limit/used/remaining count.
  - Allowed values: `FORM`, `GLOBAL`, `SUBNET`, `IP`, `UNKNOWN`, `WEB_SEARCH`, `AGENT_HELP`, `NATURAL_SEARCH`, `BILLING_ALLOWANCE`, `BILLING_ADDITIONAL_USAGE`
- `matchedBlocklistKey` (string, optional, nullable)
- `mediaType` (string, optional, nullable)
- `moderationReason` (string, optional, nullable)
- `parseError` (string, optional, nullable)
- `path` (string, optional, nullable)
- `properties` (map from string to any, optional)
- `proseViolation` (list of ProseViolation, optional, nullable) — Every rejected passage of a PROSE_REJECTED write, once per problem it shows; absent for every other problem.
- `remaining` (long, optional, nullable) — Cap minus used for the limitType meter, never negative.
- `requiredRole` (string, optional, nullable)
- `resetAt` (datetime, optional, nullable) — When the limitType meter refills and the request can succeed again.
- `resolution` (ProblemResolution, optional, nullable) — Machine-readable next action for an aVenture ProblemDetail. For reviewCandidates, inspect ProblemDetail.details candidates and decide update, create-with-override, or block from those returned records.
- `retryAfterSeconds` (long, optional, nullable) — Seconds to wait before the same request can succeed. A BILLING_ALLOWANCE meter resets at the UTC month boundary, so this reaches weeks: read limitType before treating it as a burst backoff.
- `spanId` (string, optional, nullable)
- `status` (integer, optional)
- `suggestion` (string, optional, nullable)
- `suggestions` (map from string to string, optional, nullable)
- `suspectedFragment` (string, optional, nullable)
- `title` (string, optional)
- `traceId` (string, optional, nullable)
- `type` (string, optional)
- `unknownParameters` (list of string, optional, nullable)
- `used` (long, optional, nullable) — Requests already charged against the limitType meter this period.
- `validParameters` (list of string, optional, nullable)
- `value` (string, optional, nullable)
- `windowSeconds` (long, optional, nullable) — Length of a rolling throttle window; absent for period meters.

### 401 Unauthorized Error

Unauthorized

- `allowanceType` (enum, optional) — Which monthly allowance a BILLING_ALLOWANCE refusal exhausted.
  - Allowed values: `COMPANY`, `PERSON`, `ENTITY_VIEW`, `ENTITY_BRAND`, `PERSON_VIEW`, `WEB_SEARCH`
- `circuitBreaker` (string, optional, nullable)
- `code` (string, optional, nullable) — Machine-readable secondary code on ProblemDetail.code. Agents should branch on this value when the HTTP status alone does not identify the recovery path. Code groups include auth/session, rate limiting, job infrastructure, RBAC, external providers, image processing, R2 storage, search, and inference. Many codes describe server-side conditions a caller cannot fix: surface the error and stop rather than retry.
- `conflictingRecord` (CurrentSlugOwner, optional, nullable) — Current slug owner
- `detail` (string, optional)
- `details` (DomainConflictDetails, optional, nullable) — Structured conflict details. A possible duplicate or an ambiguous lookup returns its candidate records; score and threshold rank the candidates and do not prove that the requested record is absent.
- `error` (map from string to string, optional, nullable)
- `existingRecordId` (string, optional, nullable) — On a duplicate 409, the id of the stored record the request collided with; read or update that record instead of creating it again. Absent when the conflict names no single stored record.
- `existingRedirect` (RedirectSlugPath, optional, nullable) — Redirect slug path
- `feId` (string, optional, nullable)
- `field` (string, optional, nullable)
- `filedRunId` (list of string, optional, nullable) — Research request ids a batch filed or reused for its other records before returning this error; absent for every other error.
- `hammingDistance` (long, optional, nullable)
- `hint` (string, optional, nullable)
- `instance` (string, optional)
- `limit` (long, optional, nullable) — Cap the limitType meter allows for its current period.
- `limitType` (enum, optional) — Which meter refused the request; names what limit/used/remaining count.
  - Allowed values: `FORM`, `GLOBAL`, `SUBNET`, `IP`, `UNKNOWN`, `WEB_SEARCH`, `AGENT_HELP`, `NATURAL_SEARCH`, `BILLING_ALLOWANCE`, `BILLING_ADDITIONAL_USAGE`
- `matchedBlocklistKey` (string, optional, nullable)
- `mediaType` (string, optional, nullable)
- `moderationReason` (string, optional, nullable)
- `parseError` (string, optional, nullable)
- `path` (string, optional, nullable)
- `properties` (map from string to any, optional)
- `proseViolation` (list of ProseViolation, optional, nullable) — Every rejected passage of a PROSE_REJECTED write, once per problem it shows; absent for every other problem.
- `remaining` (long, optional, nullable) — Cap minus used for the limitType meter, never negative.
- `requiredRole` (string, optional, nullable)
- `resetAt` (datetime, optional, nullable) — When the limitType meter refills and the request can succeed again.
- `resolution` (ProblemResolution, optional, nullable) — Machine-readable next action for an aVenture ProblemDetail. For reviewCandidates, inspect ProblemDetail.details candidates and decide update, create-with-override, or block from those returned records.
- `retryAfterSeconds` (long, optional, nullable) — Seconds to wait before the same request can succeed. A BILLING_ALLOWANCE meter resets at the UTC month boundary, so this reaches weeks: read limitType before treating it as a burst backoff.
- `spanId` (string, optional, nullable)
- `status` (integer, optional)
- `suggestion` (string, optional, nullable)
- `suggestions` (map from string to string, optional, nullable)
- `suspectedFragment` (string, optional, nullable)
- `title` (string, optional)
- `traceId` (string, optional, nullable)
- `type` (string, optional)
- `unknownParameters` (list of string, optional, nullable)
- `used` (long, optional, nullable) — Requests already charged against the limitType meter this period.
- `validParameters` (list of string, optional, nullable)
- `value` (string, optional, nullable)
- `windowSeconds` (long, optional, nullable) — Length of a rolling throttle window; absent for period meters.

### 403 Forbidden Error

Forbidden

- `allowanceType` (enum, optional) — Which monthly allowance a BILLING_ALLOWANCE refusal exhausted.
  - Allowed values: `COMPANY`, `PERSON`, `ENTITY_VIEW`, `ENTITY_BRAND`, `PERSON_VIEW`, `WEB_SEARCH`
- `circuitBreaker` (string, optional, nullable)
- `code` (string, optional, nullable) — Machine-readable secondary code on ProblemDetail.code. Agents should branch on this value when the HTTP status alone does not identify the recovery path. Code groups include auth/session, rate limiting, job infrastructure, RBAC, external providers, image processing, R2 storage, search, and inference. Many codes describe server-side conditions a caller cannot fix: surface the error and stop rather than retry.
- `conflictingRecord` (CurrentSlugOwner, optional, nullable) — Current slug owner
- `detail` (string, optional)
- `details` (DomainConflictDetails, optional, nullable) — Structured conflict details. A possible duplicate or an ambiguous lookup returns its candidate records; score and threshold rank the candidates and do not prove that the requested record is absent.
- `error` (map from string to string, optional, nullable)
- `existingRecordId` (string, optional, nullable) — On a duplicate 409, the id of the stored record the request collided with; read or update that record instead of creating it again. Absent when the conflict names no single stored record.
- `existingRedirect` (RedirectSlugPath, optional, nullable) — Redirect slug path
- `feId` (string, optional, nullable)
- `field` (string, optional, nullable)
- `filedRunId` (list of string, optional, nullable) — Research request ids a batch filed or reused for its other records before returning this error; absent for every other error.
- `hammingDistance` (long, optional, nullable)
- `hint` (string, optional, nullable)
- `instance` (string, optional)
- `limit` (long, optional, nullable) — Cap the limitType meter allows for its current period.
- `limitType` (enum, optional) — Which meter refused the request; names what limit/used/remaining count.
  - Allowed values: `FORM`, `GLOBAL`, `SUBNET`, `IP`, `UNKNOWN`, `WEB_SEARCH`, `AGENT_HELP`, `NATURAL_SEARCH`, `BILLING_ALLOWANCE`, `BILLING_ADDITIONAL_USAGE`
- `matchedBlocklistKey` (string, optional, nullable)
- `mediaType` (string, optional, nullable)
- `moderationReason` (string, optional, nullable)
- `parseError` (string, optional, nullable)
- `path` (string, optional, nullable)
- `properties` (map from string to any, optional)
- `proseViolation` (list of ProseViolation, optional, nullable) — Every rejected passage of a PROSE_REJECTED write, once per problem it shows; absent for every other problem.
- `remaining` (long, optional, nullable) — Cap minus used for the limitType meter, never negative.
- `requiredRole` (string, optional, nullable)
- `resetAt` (datetime, optional, nullable) — When the limitType meter refills and the request can succeed again.
- `resolution` (ProblemResolution, optional, nullable) — Machine-readable next action for an aVenture ProblemDetail. For reviewCandidates, inspect ProblemDetail.details candidates and decide update, create-with-override, or block from those returned records.
- `retryAfterSeconds` (long, optional, nullable) — Seconds to wait before the same request can succeed. A BILLING_ALLOWANCE meter resets at the UTC month boundary, so this reaches weeks: read limitType before treating it as a burst backoff.
- `spanId` (string, optional, nullable)
- `status` (integer, optional)
- `suggestion` (string, optional, nullable)
- `suggestions` (map from string to string, optional, nullable)
- `suspectedFragment` (string, optional, nullable)
- `title` (string, optional)
- `traceId` (string, optional, nullable)
- `type` (string, optional)
- `unknownParameters` (list of string, optional, nullable)
- `used` (long, optional, nullable) — Requests already charged against the limitType meter this period.
- `validParameters` (list of string, optional, nullable)
- `value` (string, optional, nullable)
- `windowSeconds` (long, optional, nullable) — Length of a rolling throttle window; absent for period meters.

### 404 Not Found Error

Not Found

- `allowanceType` (enum, optional) — Which monthly allowance a BILLING_ALLOWANCE refusal exhausted.
  - Allowed values: `COMPANY`, `PERSON`, `ENTITY_VIEW`, `ENTITY_BRAND`, `PERSON_VIEW`, `WEB_SEARCH`
- `circuitBreaker` (string, optional, nullable)
- `code` (string, optional, nullable) — Machine-readable secondary code on ProblemDetail.code. Agents should branch on this value when the HTTP status alone does not identify the recovery path. Code groups include auth/session, rate limiting, job infrastructure, RBAC, external providers, image processing, R2 storage, search, and inference. Many codes describe server-side conditions a caller cannot fix: surface the error and stop rather than retry.
- `conflictingRecord` (CurrentSlugOwner, optional, nullable) — Current slug owner
- `detail` (string, optional)
- `details` (DomainConflictDetails, optional, nullable) — Structured conflict details. A possible duplicate or an ambiguous lookup returns its candidate records; score and threshold rank the candidates and do not prove that the requested record is absent.
- `error` (map from string to string, optional, nullable)
- `existingRecordId` (string, optional, nullable) — On a duplicate 409, the id of the stored record the request collided with; read or update that record instead of creating it again. Absent when the conflict names no single stored record.
- `existingRedirect` (RedirectSlugPath, optional, nullable) — Redirect slug path
- `feId` (string, optional, nullable)
- `field` (string, optional, nullable)
- `filedRunId` (list of string, optional, nullable) — Research request ids a batch filed or reused for its other records before returning this error; absent for every other error.
- `hammingDistance` (long, optional, nullable)
- `hint` (string, optional, nullable)
- `instance` (string, optional)
- `limit` (long, optional, nullable) — Cap the limitType meter allows for its current period.
- `limitType` (enum, optional) — Which meter refused the request; names what limit/used/remaining count.
  - Allowed values: `FORM`, `GLOBAL`, `SUBNET`, `IP`, `UNKNOWN`, `WEB_SEARCH`, `AGENT_HELP`, `NATURAL_SEARCH`, `BILLING_ALLOWANCE`, `BILLING_ADDITIONAL_USAGE`
- `matchedBlocklistKey` (string, optional, nullable)
- `mediaType` (string, optional, nullable)
- `moderationReason` (string, optional, nullable)
- `parseError` (string, optional, nullable)
- `path` (string, optional, nullable)
- `properties` (map from string to any, optional)
- `proseViolation` (list of ProseViolation, optional, nullable) — Every rejected passage of a PROSE_REJECTED write, once per problem it shows; absent for every other problem.
- `remaining` (long, optional, nullable) — Cap minus used for the limitType meter, never negative.
- `requiredRole` (string, optional, nullable)
- `resetAt` (datetime, optional, nullable) — When the limitType meter refills and the request can succeed again.
- `resolution` (ProblemResolution, optional, nullable) — Machine-readable next action for an aVenture ProblemDetail. For reviewCandidates, inspect ProblemDetail.details candidates and decide update, create-with-override, or block from those returned records.
- `retryAfterSeconds` (long, optional, nullable) — Seconds to wait before the same request can succeed. A BILLING_ALLOWANCE meter resets at the UTC month boundary, so this reaches weeks: read limitType before treating it as a burst backoff.
- `spanId` (string, optional, nullable)
- `status` (integer, optional)
- `suggestion` (string, optional, nullable)
- `suggestions` (map from string to string, optional, nullable)
- `suspectedFragment` (string, optional, nullable)
- `title` (string, optional)
- `traceId` (string, optional, nullable)
- `type` (string, optional)
- `unknownParameters` (list of string, optional, nullable)
- `used` (long, optional, nullable) — Requests already charged against the limitType meter this period.
- `validParameters` (list of string, optional, nullable)
- `value` (string, optional, nullable)
- `windowSeconds` (long, optional, nullable) — Length of a rolling throttle window; absent for period meters.

### 406 Not Acceptable Error

Not Acceptable

- `allowanceType` (enum, optional) — Which monthly allowance a BILLING_ALLOWANCE refusal exhausted.
  - Allowed values: `COMPANY`, `PERSON`, `ENTITY_VIEW`, `ENTITY_BRAND`, `PERSON_VIEW`, `WEB_SEARCH`
- `circuitBreaker` (string, optional, nullable)
- `code` (string, optional, nullable) — Machine-readable secondary code on ProblemDetail.code. Agents should branch on this value when the HTTP status alone does not identify the recovery path. Code groups include auth/session, rate limiting, job infrastructure, RBAC, external providers, image processing, R2 storage, search, and inference. Many codes describe server-side conditions a caller cannot fix: surface the error and stop rather than retry.
- `conflictingRecord` (CurrentSlugOwner, optional, nullable) — Current slug owner
- `detail` (string, optional)
- `details` (DomainConflictDetails, optional, nullable) — Structured conflict details. A possible duplicate or an ambiguous lookup returns its candidate records; score and threshold rank the candidates and do not prove that the requested record is absent.
- `error` (map from string to string, optional, nullable)
- `existingRecordId` (string, optional, nullable) — On a duplicate 409, the id of the stored record the request collided with; read or update that record instead of creating it again. Absent when the conflict names no single stored record.
- `existingRedirect` (RedirectSlugPath, optional, nullable) — Redirect slug path
- `feId` (string, optional, nullable)
- `field` (string, optional, nullable)
- `filedRunId` (list of string, optional, nullable) — Research request ids a batch filed or reused for its other records before returning this error; absent for every other error.
- `hammingDistance` (long, optional, nullable)
- `hint` (string, optional, nullable)
- `instance` (string, optional)
- `limit` (long, optional, nullable) — Cap the limitType meter allows for its current period.
- `limitType` (enum, optional) — Which meter refused the request; names what limit/used/remaining count.
  - Allowed values: `FORM`, `GLOBAL`, `SUBNET`, `IP`, `UNKNOWN`, `WEB_SEARCH`, `AGENT_HELP`, `NATURAL_SEARCH`, `BILLING_ALLOWANCE`, `BILLING_ADDITIONAL_USAGE`
- `matchedBlocklistKey` (string, optional, nullable)
- `mediaType` (string, optional, nullable)
- `moderationReason` (string, optional, nullable)
- `parseError` (string, optional, nullable)
- `path` (string, optional, nullable)
- `properties` (map from string to any, optional)
- `proseViolation` (list of ProseViolation, optional, nullable) — Every rejected passage of a PROSE_REJECTED write, once per problem it shows; absent for every other problem.
- `remaining` (long, optional, nullable) — Cap minus used for the limitType meter, never negative.
- `requiredRole` (string, optional, nullable)
- `resetAt` (datetime, optional, nullable) — When the limitType meter refills and the request can succeed again.
- `resolution` (ProblemResolution, optional, nullable) — Machine-readable next action for an aVenture ProblemDetail. For reviewCandidates, inspect ProblemDetail.details candidates and decide update, create-with-override, or block from those returned records.
- `retryAfterSeconds` (long, optional, nullable) — Seconds to wait before the same request can succeed. A BILLING_ALLOWANCE meter resets at the UTC month boundary, so this reaches weeks: read limitType before treating it as a burst backoff.
- `spanId` (string, optional, nullable)
- `status` (integer, optional)
- `suggestion` (string, optional, nullable)
- `suggestions` (map from string to string, optional, nullable)
- `suspectedFragment` (string, optional, nullable)
- `title` (string, optional)
- `traceId` (string, optional, nullable)
- `type` (string, optional)
- `unknownParameters` (list of string, optional, nullable)
- `used` (long, optional, nullable) — Requests already charged against the limitType meter this period.
- `validParameters` (list of string, optional, nullable)
- `value` (string, optional, nullable)
- `windowSeconds` (long, optional, nullable) — Length of a rolling throttle window; absent for period meters.

### 422 Unprocessable Entity Error

Unprocessable Content

- `allowanceType` (enum, optional) — Which monthly allowance a BILLING_ALLOWANCE refusal exhausted.
  - Allowed values: `COMPANY`, `PERSON`, `ENTITY_VIEW`, `ENTITY_BRAND`, `PERSON_VIEW`, `WEB_SEARCH`
- `circuitBreaker` (string, optional, nullable)
- `code` (string, optional, nullable) — Machine-readable secondary code on ProblemDetail.code. Agents should branch on this value when the HTTP status alone does not identify the recovery path. Code groups include auth/session, rate limiting, job infrastructure, RBAC, external providers, image processing, R2 storage, search, and inference. Many codes describe server-side conditions a caller cannot fix: surface the error and stop rather than retry.
- `conflictingRecord` (CurrentSlugOwner, optional, nullable) — Current slug owner
- `detail` (string, optional)
- `details` (DomainConflictDetails, optional, nullable) — Structured conflict details. A possible duplicate or an ambiguous lookup returns its candidate records; score and threshold rank the candidates and do not prove that the requested record is absent.
- `error` (map from string to string, optional, nullable)
- `existingRecordId` (string, optional, nullable) — On a duplicate 409, the id of the stored record the request collided with; read or update that record instead of creating it again. Absent when the conflict names no single stored record.
- `existingRedirect` (RedirectSlugPath, optional, nullable) — Redirect slug path
- `feId` (string, optional, nullable)
- `field` (string, optional, nullable)
- `filedRunId` (list of string, optional, nullable) — Research request ids a batch filed or reused for its other records before returning this error; absent for every other error.
- `hammingDistance` (long, optional, nullable)
- `hint` (string, optional, nullable)
- `instance` (string, optional)
- `limit` (long, optional, nullable) — Cap the limitType meter allows for its current period.
- `limitType` (enum, optional) — Which meter refused the request; names what limit/used/remaining count.
  - Allowed values: `FORM`, `GLOBAL`, `SUBNET`, `IP`, `UNKNOWN`, `WEB_SEARCH`, `AGENT_HELP`, `NATURAL_SEARCH`, `BILLING_ALLOWANCE`, `BILLING_ADDITIONAL_USAGE`
- `matchedBlocklistKey` (string, optional, nullable)
- `mediaType` (string, optional, nullable)
- `moderationReason` (string, optional, nullable)
- `parseError` (string, optional, nullable)
- `path` (string, optional, nullable)
- `properties` (map from string to any, optional)
- `proseViolation` (list of ProseViolation, optional, nullable) — Every rejected passage of a PROSE_REJECTED write, once per problem it shows; absent for every other problem.
- `remaining` (long, optional, nullable) — Cap minus used for the limitType meter, never negative.
- `requiredRole` (string, optional, nullable)
- `resetAt` (datetime, optional, nullable) — When the limitType meter refills and the request can succeed again.
- `resolution` (ProblemResolution, optional, nullable) — Machine-readable next action for an aVenture ProblemDetail. For reviewCandidates, inspect ProblemDetail.details candidates and decide update, create-with-override, or block from those returned records.
- `retryAfterSeconds` (long, optional, nullable) — Seconds to wait before the same request can succeed. A BILLING_ALLOWANCE meter resets at the UTC month boundary, so this reaches weeks: read limitType before treating it as a burst backoff.
- `spanId` (string, optional, nullable)
- `status` (integer, optional)
- `suggestion` (string, optional, nullable)
- `suggestions` (map from string to string, optional, nullable)
- `suspectedFragment` (string, optional, nullable)
- `title` (string, optional)
- `traceId` (string, optional, nullable)
- `type` (string, optional)
- `unknownParameters` (list of string, optional, nullable)
- `used` (long, optional, nullable) — Requests already charged against the limitType meter this period.
- `validParameters` (list of string, optional, nullable)
- `value` (string, optional, nullable)
- `windowSeconds` (long, optional, nullable) — Length of a rolling throttle window; absent for period meters.

### 429 Too Many Requests Error

Too Many Requests

- `allowanceType` (enum, optional) — Which monthly allowance a BILLING_ALLOWANCE refusal exhausted.
  - Allowed values: `COMPANY`, `PERSON`, `ENTITY_VIEW`, `ENTITY_BRAND`, `PERSON_VIEW`, `WEB_SEARCH`
- `circuitBreaker` (string, optional, nullable)
- `code` (string, optional, nullable) — Machine-readable secondary code on ProblemDetail.code. Agents should branch on this value when the HTTP status alone does not identify the recovery path. Code groups include auth/session, rate limiting, job infrastructure, RBAC, external providers, image processing, R2 storage, search, and inference. Many codes describe server-side conditions a caller cannot fix: surface the error and stop rather than retry.
- `conflictingRecord` (CurrentSlugOwner, optional, nullable) — Current slug owner
- `detail` (string, optional)
- `details` (DomainConflictDetails, optional, nullable) — Structured conflict details. A possible duplicate or an ambiguous lookup returns its candidate records; score and threshold rank the candidates and do not prove that the requested record is absent.
- `error` (map from string to string, optional, nullable)
- `existingRecordId` (string, optional, nullable) — On a duplicate 409, the id of the stored record the request collided with; read or update that record instead of creating it again. Absent when the conflict names no single stored record.
- `existingRedirect` (RedirectSlugPath, optional, nullable) — Redirect slug path
- `feId` (string, optional, nullable)
- `field` (string, optional, nullable)
- `filedRunId` (list of string, optional, nullable) — Research request ids a batch filed or reused for its other records before returning this error; absent for every other error.
- `hammingDistance` (long, optional, nullable)
- `hint` (string, optional, nullable)
- `instance` (string, optional)
- `limit` (long, optional, nullable) — Cap the limitType meter allows for its current period.
- `limitType` (enum, optional) — Which meter refused the request; names what limit/used/remaining count.
  - Allowed values: `FORM`, `GLOBAL`, `SUBNET`, `IP`, `UNKNOWN`, `WEB_SEARCH`, `AGENT_HELP`, `NATURAL_SEARCH`, `BILLING_ALLOWANCE`, `BILLING_ADDITIONAL_USAGE`
- `matchedBlocklistKey` (string, optional, nullable)
- `mediaType` (string, optional, nullable)
- `moderationReason` (string, optional, nullable)
- `parseError` (string, optional, nullable)
- `path` (string, optional, nullable)
- `properties` (map from string to any, optional)
- `proseViolation` (list of ProseViolation, optional, nullable) — Every rejected passage of a PROSE_REJECTED write, once per problem it shows; absent for every other problem.
- `remaining` (long, optional, nullable) — Cap minus used for the limitType meter, never negative.
- `requiredRole` (string, optional, nullable)
- `resetAt` (datetime, optional, nullable) — When the limitType meter refills and the request can succeed again.
- `resolution` (ProblemResolution, optional, nullable) — Machine-readable next action for an aVenture ProblemDetail. For reviewCandidates, inspect ProblemDetail.details candidates and decide update, create-with-override, or block from those returned records.
- `retryAfterSeconds` (long, optional, nullable) — Seconds to wait before the same request can succeed. A BILLING_ALLOWANCE meter resets at the UTC month boundary, so this reaches weeks: read limitType before treating it as a burst backoff.
- `spanId` (string, optional, nullable)
- `status` (integer, optional)
- `suggestion` (string, optional, nullable)
- `suggestions` (map from string to string, optional, nullable)
- `suspectedFragment` (string, optional, nullable)
- `title` (string, optional)
- `traceId` (string, optional, nullable)
- `type` (string, optional)
- `unknownParameters` (list of string, optional, nullable)
- `used` (long, optional, nullable) — Requests already charged against the limitType meter this period.
- `validParameters` (list of string, optional, nullable)
- `value` (string, optional, nullable)
- `windowSeconds` (long, optional, nullable) — Length of a rolling throttle window; absent for period meters.

### 500 Internal Server Error

Internal Server Error

- `allowanceType` (enum, optional) — Which monthly allowance a BILLING_ALLOWANCE refusal exhausted.
  - Allowed values: `COMPANY`, `PERSON`, `ENTITY_VIEW`, `ENTITY_BRAND`, `PERSON_VIEW`, `WEB_SEARCH`
- `circuitBreaker` (string, optional, nullable)
- `code` (string, optional, nullable) — Machine-readable secondary code on ProblemDetail.code. Agents should branch on this value when the HTTP status alone does not identify the recovery path. Code groups include auth/session, rate limiting, job infrastructure, RBAC, external providers, image processing, R2 storage, search, and inference. Many codes describe server-side conditions a caller cannot fix: surface the error and stop rather than retry.
- `conflictingRecord` (CurrentSlugOwner, optional, nullable) — Current slug owner
- `detail` (string, optional)
- `details` (DomainConflictDetails, optional, nullable) — Structured conflict details. A possible duplicate or an ambiguous lookup returns its candidate records; score and threshold rank the candidates and do not prove that the requested record is absent.
- `error` (map from string to string, optional, nullable)
- `existingRecordId` (string, optional, nullable) — On a duplicate 409, the id of the stored record the request collided with; read or update that record instead of creating it again. Absent when the conflict names no single stored record.
- `existingRedirect` (RedirectSlugPath, optional, nullable) — Redirect slug path
- `feId` (string, optional, nullable)
- `field` (string, optional, nullable)
- `filedRunId` (list of string, optional, nullable) — Research request ids a batch filed or reused for its other records before returning this error; absent for every other error.
- `hammingDistance` (long, optional, nullable)
- `hint` (string, optional, nullable)
- `instance` (string, optional)
- `limit` (long, optional, nullable) — Cap the limitType meter allows for its current period.
- `limitType` (enum, optional) — Which meter refused the request; names what limit/used/remaining count.
  - Allowed values: `FORM`, `GLOBAL`, `SUBNET`, `IP`, `UNKNOWN`, `WEB_SEARCH`, `AGENT_HELP`, `NATURAL_SEARCH`, `BILLING_ALLOWANCE`, `BILLING_ADDITIONAL_USAGE`
- `matchedBlocklistKey` (string, optional, nullable)
- `mediaType` (string, optional, nullable)
- `moderationReason` (string, optional, nullable)
- `parseError` (string, optional, nullable)
- `path` (string, optional, nullable)
- `properties` (map from string to any, optional)
- `proseViolation` (list of ProseViolation, optional, nullable) — Every rejected passage of a PROSE_REJECTED write, once per problem it shows; absent for every other problem.
- `remaining` (long, optional, nullable) — Cap minus used for the limitType meter, never negative.
- `requiredRole` (string, optional, nullable)
- `resetAt` (datetime, optional, nullable) — When the limitType meter refills and the request can succeed again.
- `resolution` (ProblemResolution, optional, nullable) — Machine-readable next action for an aVenture ProblemDetail. For reviewCandidates, inspect ProblemDetail.details candidates and decide update, create-with-override, or block from those returned records.
- `retryAfterSeconds` (long, optional, nullable) — Seconds to wait before the same request can succeed. A BILLING_ALLOWANCE meter resets at the UTC month boundary, so this reaches weeks: read limitType before treating it as a burst backoff.
- `spanId` (string, optional, nullable)
- `status` (integer, optional)
- `suggestion` (string, optional, nullable)
- `suggestions` (map from string to string, optional, nullable)
- `suspectedFragment` (string, optional, nullable)
- `title` (string, optional)
- `traceId` (string, optional, nullable)
- `type` (string, optional)
- `unknownParameters` (list of string, optional, nullable)
- `used` (long, optional, nullable) — Requests already charged against the limitType meter this period.
- `validParameters` (list of string, optional, nullable)
- `value` (string, optional, nullable)
- `windowSeconds` (long, optional, nullable) — Length of a rolling throttle window; absent for period meters.

### 503 Service Unavailable Error

Service Unavailable

- `allowanceType` (enum, optional) — Which monthly allowance a BILLING_ALLOWANCE refusal exhausted.
  - Allowed values: `COMPANY`, `PERSON`, `ENTITY_VIEW`, `ENTITY_BRAND`, `PERSON_VIEW`, `WEB_SEARCH`
- `circuitBreaker` (string, optional, nullable)
- `code` (string, optional, nullable) — Machine-readable secondary code on ProblemDetail.code. Agents should branch on this value when the HTTP status alone does not identify the recovery path. Code groups include auth/session, rate limiting, job infrastructure, RBAC, external providers, image processing, R2 storage, search, and inference. Many codes describe server-side conditions a caller cannot fix: surface the error and stop rather than retry.
- `conflictingRecord` (CurrentSlugOwner, optional, nullable) — Current slug owner
- `detail` (string, optional)
- `details` (DomainConflictDetails, optional, nullable) — Structured conflict details. A possible duplicate or an ambiguous lookup returns its candidate records; score and threshold rank the candidates and do not prove that the requested record is absent.
- `error` (map from string to string, optional, nullable)
- `existingRecordId` (string, optional, nullable) — On a duplicate 409, the id of the stored record the request collided with; read or update that record instead of creating it again. Absent when the conflict names no single stored record.
- `existingRedirect` (RedirectSlugPath, optional, nullable) — Redirect slug path
- `feId` (string, optional, nullable)
- `field` (string, optional, nullable)
- `filedRunId` (list of string, optional, nullable) — Research request ids a batch filed or reused for its other records before returning this error; absent for every other error.
- `hammingDistance` (long, optional, nullable)
- `hint` (string, optional, nullable)
- `instance` (string, optional)
- `limit` (long, optional, nullable) — Cap the limitType meter allows for its current period.
- `limitType` (enum, optional) — Which meter refused the request; names what limit/used/remaining count.
  - Allowed values: `FORM`, `GLOBAL`, `SUBNET`, `IP`, `UNKNOWN`, `WEB_SEARCH`, `AGENT_HELP`, `NATURAL_SEARCH`, `BILLING_ALLOWANCE`, `BILLING_ADDITIONAL_USAGE`
- `matchedBlocklistKey` (string, optional, nullable)
- `mediaType` (string, optional, nullable)
- `moderationReason` (string, optional, nullable)
- `parseError` (string, optional, nullable)
- `path` (string, optional, nullable)
- `properties` (map from string to any, optional)
- `proseViolation` (list of ProseViolation, optional, nullable) — Every rejected passage of a PROSE_REJECTED write, once per problem it shows; absent for every other problem.
- `remaining` (long, optional, nullable) — Cap minus used for the limitType meter, never negative.
- `requiredRole` (string, optional, nullable)
- `resetAt` (datetime, optional, nullable) — When the limitType meter refills and the request can succeed again.
- `resolution` (ProblemResolution, optional, nullable) — Machine-readable next action for an aVenture ProblemDetail. For reviewCandidates, inspect ProblemDetail.details candidates and decide update, create-with-override, or block from those returned records.
- `retryAfterSeconds` (long, optional, nullable) — Seconds to wait before the same request can succeed. A BILLING_ALLOWANCE meter resets at the UTC month boundary, so this reaches weeks: read limitType before treating it as a burst backoff.
- `spanId` (string, optional, nullable)
- `status` (integer, optional)
- `suggestion` (string, optional, nullable)
- `suggestions` (map from string to string, optional, nullable)
- `suspectedFragment` (string, optional, nullable)
- `title` (string, optional)
- `traceId` (string, optional, nullable)
- `type` (string, optional)
- `unknownParameters` (list of string, optional, nullable)
- `used` (long, optional, nullable) — Requests already charged against the limitType meter this period.
- `validParameters` (list of string, optional, nullable)
- `value` (string, optional, nullable)
- `windowSeconds` (long, optional, nullable) — Length of a rolling throttle window; absent for period meters.

## Types

### HarnessRun

One research run on a company, Product, Service, or person

- `attempt` (integer, required) — Retry attempt counter
- `chassis` (enum, required) — Agent loop this run executes on
  - Allowed values: `claude-agent-sdk`, `pi-agent-sdk`
- `chassisRouted` (boolean, required) — True when the chassis router, not a caller, picked `chassis`
- `createdAt` (datetime, required) — Creation timestamp
- `environment` (enum, required) — API environment
  - Allowed values: `unassigned`, `development`, `staging`, `production`
- `hasSourceDocument` (boolean, required) — Whether this run consumes an immutable private source document
- `id` (string, required) — Run id
- `iteration` (integer, required) — Current loop iteration
- `lane` (enum, required) — Queue lane for admission priority
  - Allowed values: `interactive`, `background`
- `llmApi` (enum, required) — Gateway wire API every LLM call of this run uses
  - Allowed values: `anthropic`, `openai-chat`, `openai-responses`
- `maxIteration` (integer, required) — Loop iteration cap
- `maxScoutConcurrent` (integer, required) — Parallel read-only scout fan-out width N
- `mode` (enum, required) — Enrichment breadth selected for this run
  - Allowed values: `COMPREHENSIVE`, `INDIVIDUAL`
- `model` (string, required) — Model the run uses
- `status` (enum, required) — Current lifecycle state
  - Allowed values: `queued`, `running`, `completed`, `failed`, `stopped`
- `subagentModel` (string, required) — Read-only research, cohort, and completion sub-agent model id
- `type` (enum, required) — Run kind: ENRICHMENT for a research request a caller filed, TASK for a narrower run aVenture scheduled
  - Allowed values: `ENRICHMENT`, `TASK`
- `updatedAt` (datetime, required) — Last update timestamp
- `url` (string, required) — URL of the company, Product, Service, or person under research
- `entitySlug` (string, optional, nullable) — Slug of the profile the run produced
- `error` (string, optional, nullable) — Why the run failed; null unless failed
- `failureClass` (string, optional, nullable) — Typed terminal-failure class from the harness retry classifier (e.g. runtime_cap, escalated, provider_capacity, context_overflow); null unless failed
- `finishedAt` (datetime, optional, nullable) — Run completion timestamp
- `latestStatus` (string, optional, nullable) — Latest enrich-loop status as an opaque JSON string
- `nextAttemptAt` (datetime, optional, nullable) — Earliest re-claim time when waiting on retry backoff
- `resumeSafeUntil` (datetime, optional, nullable) — 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.
- `startedAt` (datetime, optional, nullable) — Run start timestamp
- `taskPresetKey` (list of string, optional, nullable) — Research presets filed with the run
- `userPrompt` (string, optional, nullable) — Optional instructions filed with the run

### Entity

Flat entity core record — identity, naming, status, image, and source metadata. An entity is our umbrella record for organizations such as companies, funds, investment firms and investors, accelerators, nonprofits, and government agencies, plus products and services connected to those organizations. Nested as .core inside EntityList for default list reads and EntityDetail for detail reads.

- `id` (string, required) — Unique entity identifier
- `image` (EntityImage, required) — Logo and monogram image metadata
- `nameAlias` (list of EntityNameAliasEntityAliasType, required) — All names this entity has been known by — current alternates, DBAs, former names, and rebrand-source identities. Naming history (e.g. `Metaphor Systems` for the current `Exa` entity) lives here; never as a separate relationship type or `formerName` field.
- `nameBrand` (string, required) — Resolved display brand name
- `slug` (string, required) — URL-safe identifier
- `typeRecord` (enum, required) — Entity type classification
  - Allowed values: `Company`, `Investment Firm`, `Fund`, `Nonprofit`, `Government`, `Organization`, `Business Line`, `Product`, `Service`
- `defaultCurrency` (string, optional, nullable) — Default currency code (ISO 4217)
- `foundedYear` (integer, optional, nullable) — Year the entity was founded
- `lastModifiedAt` (datetime, optional, nullable) — Provenance-grounded last-modified watermark (schema.org dateModified). Advances only when a real, consumer-meaningful data point changes via a recorded provenance event — never on timestamp-only writes, migrations, or index refreshes. Pairs with createdAt (dateCreated) and grounds the sitemap lastmod.
- `nameLegal` (string, optional, nullable) — Registered legal name
- `operatingStatus` (string, optional, nullable) — Current operating status. Use Acquired Subsidiary when the entity was acquired and still operates; use Closed (Acquihire) when the entity was acquired for its team and shut down, rendering like Closed everywhere; use Acquired only when it is terminal, folded, or closed.
- `publicId` (string, optional, nullable) — Stable, immutable public handle (e.g. `eV1StGXR8Z5a`). Never changes once assigned, unlike the slug. Null on projections that do not select it and on rows still awaiting handle backfill.
- `publicUrl` (string, optional, nullable) — Absolute public profile URL on the aVenture front-end, e.g. `https://aventure.vc/non-profits/{slug}`, derived from the typeRecord's canonical route family. Null when the route needs relationship context or the record has no direct public SSR route (Business Line, Organization, Product, Service, or a non-public slug). EntityDetail.publicUrl resolves Business Line parent context. Product/Service pages are provider-nested: compose the provider entity's publicUrl + `/products-services/` + this record's slug, or consume the sitemap-urls slot paths, which already emit the composed child routes.
- `sitemap` (EntitySitemap, optional, nullable) — Sub-route eligibility, populated by the sitemap projection. Null on non-sitemap reads to keep thin payloads compact.
- `updatedAt` (datetime, optional, nullable) — Last modification timestamp

### HarnessRunProgress

Current public progress of a harness run

- `complete` (boolean, required) — Whether the enrichment loop reports completion
- `entitySlug` (string, required, nullable) — Canonical entity slug currently reported by the loop
- `gateRemaining` (list of string, required) — Profile sections the run has not finished yet
- `whatElseRemaining` (list of string, required) — Additional work the loop reports as remaining
- `writeThisIteration` (list of string, required) — Writes completed during the current loop iteration
- `note` (string, optional, nullable) — Optional progress note from the loop

### CurrentSlugOwner

Current slug owner

- `id` (string, required)
- `isHidden` (boolean, required)
- `resourceType` (enum, required) — Resource type whose slug is being changed
  - Allowed values: `entity`, `person`, `news`, `blog`, `content`
- `showOnSitemap` (boolean, required)
- `slug` (string, required)
- `deletedAt` (datetime, optional, nullable)
- `nameBrand` (string, optional, nullable)

### DomainConflictDetails

Details of an HTTP 409 conflict. conflictType names the shape: URL_DUPLICATE when the URL is already a current URL on another record; STRICT_URL_LOOKUP when an exact URL lookup matches more than one record; DUPLICATE_CREATE_REVIEW when a create or lookup returns candidate records to review; CLASSIFICATION_INACTIVE_TAG when a classification value exists but is inactive; NEWS_SOURCE_URL when another article already has the same publication and URL.

- `conflictType`: `CLASSIFICATION_INACTIVE_TAG` (CLASSIFICATION_INACTIVE_TAG)
  - `availableOverrides` (list of enum, required) — Allowed inactiveTagOverride values for this conflict
    - Allowed values: `REACTIVATE`, `ATTACH_INACTIVE`
  - `slug` (string, required) — Existing dormant value slug or lookup key
  - `tagId` (integer, required) — Existing tag id
- `conflictType`: `DUPLICATE_CREATE_REVIEW` (DUPLICATE_CREATE_REVIEW)
  - `threshold` (integer, required) — Review threshold used by duplicate scoring. Scores below this value can still be useful candidate context; this value does not prove absence or authorize create.
  - `candidate` (list of SearchDuplicateCandidateScore, optional, nullable) — Entity/person candidates returned by lookup or create duplicate review. If a candidate is the requested record, read/update that candidate by id. Create with duplicate override only after every candidate is reviewed as distinct.
  - `newsCandidate` (list of NewsCandidateScore, optional, nullable) — News candidates returned by lookup or create duplicate review. If a candidate is the requested article, read/update that article by id. Otherwise block until source evidence proves a distinct article.
  - `overridePath` (string, optional, nullable) — Create endpoint to retry only after reviewing the returned candidates and supplying overrideGate=duplicate and overrideReason as query parameters. Null for detail lookup ambiguity, where the next action is review/update/block.
- `conflictType`: `NEWS_SOURCE_URL` (NEWS_SOURCE_URL)
  - `conflictingArticleId` (integer, required) — Existing article id (NewsId.value) that already owns this publication + URL pair.
  - `conflictingArticleSlug` (string, required) — Existing article slug, or empty string when the existing article has no slug. Use with GET /v1/news/lookup?slug= to fetch the conflicting article.
  - `conflictingArticleTitle` (string, required) — Existing article title for human-readable diagnostics.
- `conflictType`: `STRICT_URL_LOOKUP` (STRICT_URL_LOOKUP)
  - `candidateEntityId` (list of string, required) — Every entity id that currently owns the normalized URL. May be empty when the conflict is between persons; combined with candidatePersonId always > 1.
  - `candidatePersonId` (list of string, required) — Every person id that currently owns the normalized URL. May be empty when the conflict is between entities; combined with candidateEntityId always > 1.
  - `hint` (string, required) — Human-readable hint describing which disambiguating query parameters to add.
  - `url` (string, required) — Raw URL the caller queried.
  - `normalizedUrl` (string, optional, nullable) — Normalized URL match key the lookup resolved against. Null when normalization could not produce a stable key.
  - `urlType` (string, optional, nullable) — URL type the caller specified, or null if the lookup did not constrain by urlType.
- `conflictType`: `URL_DUPLICATE` (URL_DUPLICATE)
  - `existingJoin` (list of UrlDuplicateJoin, required) — Every current owner that already holds the normalized URL with this urlType. Non-empty when this conflict is emitted.
  - `fragmentIgnored` (boolean, required) — True when URL fragment differences were ignored during duplicate matching (i.e., the conflict ignores everything after '#').
  - `guidance` (string, required) — Human-readable guidance on how to resolve the conflict. Defaults to the standard inspect-then-demote/promote sequence.
  - `requestedOwner` (EntityPersonOwner, required) — Owner the caller attempted to attach the URL to.
  - `url` (string, required) — Raw URL as submitted by the caller (pre-normalization).
  - `urlType` (string, required) — URL type submitted by the caller (e.g., 'website', 'twitter'). The conflict applies only within this urlType.
  - `normalizedUrl` (string, optional, nullable) — Normalized URL match key used for duplicate detection. Null when normalization could not produce a stable key (e.g., malformed input).

### RedirectSlugPath

Redirect slug path

- `oldUrl` (string, required)
- `newUrl` (string, optional, nullable)
- `targetCurrentSlug` (string, optional, nullable)
- `targetId` (string, optional, nullable)
- `targetResourceType` (enum, optional, nullable) — Resource type whose slug is being changed
  - Allowed values: `entity`, `person`, `news`, `blog`, `content`

### ProseViolation

One rejected passage and one problem it shows; a passage with several problems appears once per problem.

- `overridable` (boolean, required) — Whether proseOverrideReason can accept this problem; ProblemDetail.hint says when an override is allowed.
- `passage` (string, required) — The rejected sentence, the whole text for a text-contract violation, or the source URL for a legal-page source.
- `problem` (string, required) — The problem this passage shows.
- `reason` (string, required) — Why the passage was rejected and how to fix it.

### ProblemResolution

Machine-readable next action for an aVenture ProblemDetail. For reviewCandidates, inspect ProblemDetail.details candidates and decide update, create-with-override, or block from those returned records.

- `action` (enum, required) — Next action category for the client or agent.
  - Allowed values: `setField`, `setParameter`, `removeParameter`, `useEndpoint`, `reviewCandidates`, `authenticate`
- `acceptedValue` (list of string, optional, nullable) — Accepted values for the field or parameter, when enumerable.
- `endpoint` (string, optional, nullable) — Endpoint to call for the next action, when applicable.
- `fieldPath` (string, optional, nullable) — Request-body field path that needs attention, when applicable.
- `parameter` (string, optional, nullable) — Query or path parameter that needs attention, when applicable.
- `retryable` (boolean, optional, nullable) — Whether the same logical request can be retried after the next action.

### EntityImage

Grouped entity image fields for square, standard, and monogram logo state

- `isMonogram` (boolean, required) — Whether entity image monogram
- `logo` (string, optional, nullable)
- `logoSquare` (string, optional, nullable)

### EntityNameAliasEntityAliasType

Alternate name used for search and display

- `name` (string, required) — Alternate name text
- `displayable` (boolean, optional, nullable) — Show this alias in public name displays.
- `type` (enum, optional, nullable) — Alias type classification
  - Allowed values: `alternativeDba`, `relatedLegal`

### EntitySitemap

Sub-route eligibility GATE for sitemap.xml emission, not a write receipt. Each boolean is true only when the underlying rows EXIST AND every entity that sub-route renders (this entity and any counterpart, e.g. the acquired/acquirer company behind `hasAcquisitions`) currently passes publication visibility (not hidden, on sitemap). A `false` flag when you know the data exists means an unmet visibility prerequisite -- publish the hidden entity -- confirmed against the owning command-side read; it is an active gate result, not refresh lag, and a flag being `false` says nothing succeeded-and-is-fine. Served from a materialized projection (`mv_entity_sitemap_url_slots`) refreshed asynchronously, so a `true` flag can trail a gate that was just satisfied, but a successful write alone does not flip any flag.

- `hasAnalysis` (boolean, required) — Whether the profile Analysis sub-route should be emitted.
- `hasEmployees` (boolean, required) — Whether the profile Employees sub-route should be emitted.
- `hasFundraising` (boolean, required) — Whether the profile Fundraising sub-route should be emitted.
- `hasNews` (boolean, required) — Whether the profile News sub-route should be emitted.
- `productServiceSlug` (list of string, required) — Slugs of related Product/Service entities that should each get their own `/companies/<slug>/products-services/<productSlug>` URL, capped at `MAX_PRODUCT_SERVICE_SLUGS` server-side. Derived from current `productService` relationships in either stored direction; the entity relationships resource is the authoritative, read-your-writes view of those joins.
- `hasAcquisitions` (boolean, optional, default: false) — Whether `/companies/<slug>/acquisitions` should be emitted. True only when an acquisition relationship exists AND both the acquired and acquirer entities are publicly visible. A confirmed acquisition relationship row with this flag `false` (or with `entities acquisitions list` returning zero rows) means a counterpart entity is still hidden -- publish it -- it is a visibility gate, not list lag.

### SearchDuplicateCandidateScore

Duplicate candidate scoring result. Use id/name/slug/typeRecord/reason to decide whether the candidate is the requested record. score ranks review priority; it does not prove absence.

- `id` (string, required) — Candidate id to read or update when this candidate is the requested record.
- `reason` (list of string, required) — Match reasons such as name-exact, slug-exact, url-match, url-current, url-type, or precomputed-similarity. url-match proves the supplied URL/domain matched; url-current additionally proves the candidate still holds that address today, so a candidate with url-match but no url-current matched only through a URL it no longer uses, such as an acquisition redirect. url-type only means the candidate has the same URL category and is review context, not URL identity evidence.
- `score` (integer, required) — Ranking score for duplicate review. It is not an absence proof; a low score can still be the intended record when reason/name/slug/typeRecord match.
- `externalId` (string, optional, nullable) — Matched external identifier when duplicate scoring used one.
- `name` (string, optional, nullable) — Candidate display name from the existing record.
- `operatingStatus` (string, optional, nullable) — Current operating status for entity candidates.
- `publicPath` (string, optional, nullable) — Public API/UI path for the candidate when available.
- `slug` (string, optional, nullable) — Candidate slug from the existing record.
- `typeRecord` (enum, optional, nullable) — Candidate entity type from the existing record.
  - Allowed values: `Company`, `Investment Firm`, `Fund`, `Nonprofit`, `Government`, `Organization`, `Business Line`, `Product`, `Service`

### NewsCandidateScore

Duplicate candidate scoring result for news articles. Use id/slug/externalId/reason to decide whether the candidate is the requested article. score ranks review priority; it does not prove absence.

- `id` (integer, required) — News article id to read or update when this candidate is the requested article.
- `reason` (list of string, required) — Match reasons for reviewing the candidate. Exact reasons are decision signals regardless of whether score crosses the review threshold.
- `score` (integer, required) — Ranking score for duplicate review. It is not an absence proof; a low score can still be the intended article when reason/slug/externalId match.
- `externalId` (string, optional, nullable) — Matched external article identifier when duplicate scoring used one.
- `slug` (string, optional, nullable) — Candidate article slug from the existing record.

### UrlDuplicateJoin

Entity or person that currently owns a normalized URL.

- `owner` (EntityPersonOwner, required) — Owner of the URL: either entityId or personId is populated depending on the owner kind. Use the populated id to read or update the owner's URL.
- `urlId` (integer, required) — Identifier of the existing URL record that already holds this address.

### EntityPersonOwner

Exactly one of entityId or personId is set; ids only, no name fields. Resolve display names with GET /v1/entities/detail or GET /v1/people/\{personId}.

- `entityId` (string, optional, nullable) — Owning entity id; set only when personId is absent.
- `personId` (string, optional, nullable) — Owning person id; set only when entityId is absent.

## Examples

**Response**

```json
{
  "run": {
    "attempt": 1,
    "chassis": "claude-agent-sdk",
    "chassisRouted": true,
    "createdAt": "2024-01-15T09:30:00Z",
    "environment": "unassigned",
    "hasSourceDocument": true,
    "id": "string",
    "iteration": 1,
    "lane": "interactive",
    "llmApi": "anthropic",
    "maxIteration": 1,
    "maxScoutConcurrent": 1,
    "mode": "COMPREHENSIVE",
    "model": "string",
    "status": "queued",
    "subagentModel": "string",
    "type": "ENRICHMENT",
    "updatedAt": "2024-01-15T09:30:00Z",
    "url": "string",
    "entitySlug": "string",
    "error": "string",
    "failureClass": "string",
    "finishedAt": "2024-01-15T09:30:00Z",
    "latestStatus": "string",
    "nextAttemptAt": "2024-01-15T09:30:00Z",
    "resumeSafeUntil": "2024-01-15T09:30:00Z",
    "startedAt": "2024-01-15T09:30:00Z",
    "taskPresetKey": [
      "string"
    ],
    "userPrompt": "string"
  },
  "entity": {
    "id": "string",
    "image": {
      "isMonogram": true,
      "logo": "string",
      "logoSquare": "string"
    },
    "nameAlias": [
      {
        "name": "Bun",
        "displayable": true,
        "type": "alternativeDba"
      }
    ],
    "nameBrand": "string",
    "slug": "aventure-vc",
    "typeRecord": "Company",
    "defaultCurrency": "string",
    "foundedYear": 1,
    "lastModifiedAt": "2024-01-15T09:30:00Z",
    "nameLegal": "string",
    "operatingStatus": "string",
    "publicId": "eV1StGXR8Z5a",
    "publicUrl": "string",
    "sitemap": {
      "hasAnalysis": true,
      "hasEmployees": true,
      "hasFundraising": true,
      "hasNews": true,
      "productServiceSlug": [
        "string"
      ],
      "hasAcquisitions": false
    },
    "updatedAt": "2024-01-15T09:30:00Z"
  },
  "latestStatus": {
    "complete": true,
    "entitySlug": "aventure-vc",
    "gateRemaining": [
      "string"
    ],
    "whatElseRemaining": [
      "string"
    ],
    "writeThisIteration": [
      "string"
    ],
    "note": "string"
  },
  "provider": {
    "id": "string",
    "image": {
      "isMonogram": true,
      "logo": "string",
      "logoSquare": "string"
    },
    "nameAlias": [
      {
        "name": "Bun",
        "displayable": true,
        "type": "alternativeDba"
      }
    ],
    "nameBrand": "string",
    "slug": "aventure-vc",
    "typeRecord": "Company",
    "defaultCurrency": "string",
    "foundedYear": 1,
    "lastModifiedAt": "2024-01-15T09:30:00Z",
    "nameLegal": "string",
    "operatingStatus": "string",
    "publicId": "eV1StGXR8Z5a",
    "publicUrl": "string",
    "sitemap": {
      "hasAnalysis": true,
      "hasEmployees": true,
      "hasFundraising": true,
      "hasNews": true,
      "productServiceSlug": [
        "string"
      ],
      "hasAcquisitions": false
    },
    "updatedAt": "2024-01-15T09:30:00Z"
  },
  "publicUrl": "string"
}
```

**SDK Code**

```python
import requests

url = "https://api.aventure.vc/v1/research-runs/runId"

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers)

print(response.json())
```

```javascript
const url = 'https://api.aventure.vc/v1/research-runs/runId';
const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.aventure.vc/v1/research-runs/runId"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.aventure.vc/v1/research-runs/runId")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body
```

```java
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.get("https://api.aventure.vc/v1/research-runs/runId")
  .header("Authorization", "Bearer <token>")
  .asString();
```

```php
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://api.aventure.vc/v1/research-runs/runId', [
  'headers' => [
    'Authorization' => 'Bearer <token>',
  ],
]);

echo $response->getBody();
```

```csharp
using RestSharp;

var client = new RestClient("https://api.aventure.vc/v1/research-runs/runId");
var request = new RestRequest(Method.GET);
request.AddHeader("Authorization", "Bearer <token>");
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = ["Authorization": "Bearer <token>"]

let request = NSMutableURLRequest(url: NSURL(string: "https://api.aventure.vc/v1/research-runs/runId")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "GET"
request.allHTTPHeaderFields = headers

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```