---
title: "Start Investor Portfolio Artifact"
method: POST
path: "/api/investor-portfolio/artifact/start"
tags: ["investor_portfolio"]
---

# Start Investor Portfolio Artifact

`POST /api/investor-portfolio/artifact/start`

## Request

- Base URL: `https://platform.verbiflow.com/api/bridge`
- URL: `https://platform.verbiflow.com/api/bridge/api/investor-portfolio/artifact/start`
- Auth: one of:
  - HTTP bearer and API key in header `x-flage-org-id`
  - HTTP bearer and API key in header `x-flage-org-slug`

## Request body

- InvestorPortfolioArtifactStartRequest
  - `force` boolean: When true, bypass fresh cached portfolio results and refresh each investor lookup.
  - `names` string[], required: Investor, fund, or accelerator names to resolve into portfolio-company rows.

## Response `200`

Successful Response

- InvestorPortfolioArtifactStartResponse
  - `artifact_id` string, required: Inspectable artifact that will own terminal company rows.
  - `failed` boolean, required: Whether the terminal job failed.
  - `finished` boolean, required: Whether the job is terminal.
  - `job_id` string, required: Durable portfolio job identity.
  - `phase` string, required: Latest persisted execution phase.
  - `progress_current` integer, required: Number of investor inputs terminally processed.
  - `progress_total` integer, required: Total admitted investor inputs.
  - `rows` InvestorPortfolioArtifactRow[]: Admission preview rows; terminal rows are read from the artifact.
    - `cached` boolean, required: Whether this lookup adopted a fresh persisted portfolio result instead of refreshing provider evidence.
    - `company_name` string, nullable, required: Portfolio company name as observed on the investor-owned page, or null on an explicit zero-result row.
    - `error` string, nullable, required: Fail-closed lookup detail, including an unauthorized cache miss; null when portfolio evidence was available.
    - `expires_at` string, nullable, required: UTC ISO-8601 cache expiry, or null when not persisted.
    - `fetched_at` string, nullable, required: UTC ISO-8601 fetch time, or null before a successful fetch.
    - `investor_name` string, required: Requested investor, fund, or accelerator display name.
    - `portfolio_company_name` string, nullable, required: Lossless portfolio-source company label retained for downstream identity resolution; currently equal to company_name.
    - `portfolio_url` string, nullable, required: Authoritative investor-owned portfolio page, or null when it could not be resolved.
  - `status` 'queued' | 'running' | 'blocked' | 'completed' | 'failed', required: Latest persisted job status.
  - `summary` InvestorPortfolioProgress: Incremental admission and work metadata; fields appear as work commits.
    - `accepted_pricing` AcceptedJobPricing: Immutable rule used to rate this job; final usage determines the actual charge.
      - `basis` 'none' | 'successful_execution' | 'successful_provider_attempt' | 'requested_record' | 'delivered_record' | 'successful_record' | 'provider_unit' | 'provider_cost_usd' | 'resolver_reported', required
      - `billing_owner` 'none' | 'growth_capability' | 'source_execution' | 'enrichment_reservation', required
      - `credits_per_unit` string, required: Exact Decimal customer-credit rate per unit, encoded as a string. This is not the final charge.
      - `pricing_version` string, required: Immutable published rate-book revision captured when the job was admitted.
      - `unit` string, required: Unit counted by basis, such as a record or execution.
    - `artifact_id` string, nullable: Exact durable artifact identity when allocated.
    - `auth_scope_id` string, nullable: Organization-scoped authorization identity for the job.
    - `capability_id` 'investor.portfolio.find': Canonical metered capability identity.
    - `columns` string[]: Ordered committed artifact column names.
    - `completeness` 'complete' | 'capped' | 'partial': Complete means all investor lookups terminalized; inspect each row's error and company name before treating it as a company.
    - `error` string: Persisted failure explanation when work failed.
    - `execution_contract_digest` string: Digest of the pinned execution contract.
    - `force` boolean: Whether fresh cached portfolio results were bypassed.
    - `generation_id` string: Immutable result generation identity.
    - `investor_count` integer: Number of investor names admitted.
    - `operation_key` string: Stable logical operation identity.
    - `provider_lookup_count` integer: Names requiring authorized provider work after fresh-cache adoption.
    - `replayed` boolean: Whether admission adopted an existing logical job.
    - `request_digest` string: Digest of the admitted provider request.
    - `requested_units` integer: Work units admitted before execution.
    - `result_kind` 'investor_portfolio': Terminal result discriminator.
    - `result_manifest_digest` string: Digest of the committed terminal result manifest.
    - `row_count` integer: Portfolio rows durably committed so far.
    - `semantic_fingerprint` string: Digest of the canonical business request.
    - `source_digest` string, nullable: Optional managed source-snapshot digest.
    - `tool_kind` 'investor_portfolio': Artifact-job implementation discriminator.
    - `workflow_status` unknown

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/verbiflow/apis/verbiflow-sdk-http-contract.md) - [All operations](https://skmtc.dev/verbiflow/apis/verbiflow-sdk-http-contract/llms.txt) - [OpenAPI document](https://skmtc.dev/verbiflow/apis/verbiflow-sdk-http-contract/revisions/c80e903ef8f3?raw)