---
title: "Start Ai Row Enrichment"
method: POST
path: "/api/rows/ai-enrich/start"
tags: ["growth-artifact-jobs"]
---

# Start Ai Row Enrichment

`POST /api/rows/ai-enrich/start`

## Request

- Base URL: `https://platform.verbiflow.com/api/bridge`
- URL: `https://platform.verbiflow.com/api/bridge/api/rows/ai-enrich/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`

## Headers

- `x-verbiflow-operation-partition` string, nullable

## Request body

- StartAiRowEnrichmentRequest
  - `agent` AnalysisAgentRequest
    - `kind` 'agent': Selects bounded tool-using evidence analysis.
    - `max_tool_calls` integer: Maximum combined immutable-evidence search and read calls per row.
  - `columns` string[]: Complete ordered source-column projection from staging.
  - `expected_pricing` ExpectedPricingRequest
    - `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 finite nonnegative Decimal customer-credit rate expected by the caller.
    - `pricing_version` string, required: Immutable published pricing revision expected by the caller.
    - `unit` string, required: Unit counted by the pricing basis.
  - `input_artifact_id` string, nullable: Immutable staged-input artifact identity, or null for a legacy upload.
  - `input_format` 'csv' | 'artifact_json_v1': Encoding of the staged input object.
  - `input_s3_key` string, required: Opaque staged-input key returned with upload_id.
  - `max_rows` integer: Maximum rows admitted for this partition.
  - `mode` 'medium' | 'max' | 'copy' | 'copy_verifier': Model-quality policy. copy and copy_verifier are legacy aliases that select writing and evaluation workloads.
  - `model_input_fields` string[], nullable: Exact source-column allowlist exposed to the model, or null for the canonical projection that omits evidence-reference and duplicate page fields.
  - `next_start_row` integer, nullable: One-based first row of the next partition, or null when complete.
  - `output_schema` AiAnalysisOutputSchemaInput, required: Caller-owned JSON Schema for the fields generated on every result row.
    - `additionalProperties` false: AI analysis never permits undeclared generated fields.
    - `properties` AiAnalysisOutputPropertiesInput, required: One to twenty-five caller-defined result fields.
    - `required` string[]: Caller-defined fields the model must always return.
    - `type` 'object', required: Required object root.
  - `prompt` string, required: Analysis instruction applied independently to every projected row.
  - `remaining_rows` integer: Source rows after this partition.
  - `row_count` integer, required: Rows present in this staged partition.
  - `start_row` integer: One-based first source row in this partition.
  - `submission_id` string, nullable: Stable caller submission identity for idempotent admission, or null.
  - `total_rows` integer, required: Rows in the complete source input.
  - `upload_id` string, required: Opaque identity returned by an AI input staging route.
  - `workload` 'analysis' | 'writing' | 'evaluation', nullable: Explicit model workload, or null to derive it from mode.

## Response `200`

Successful Response

- StartAiRowEnrichmentResponse
  - `accepted_pricing` AiAnalysisAcceptedPricing, required: Immutable pricing rule returned by AI analysis admission.
    - `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 nonnegative Decimal customer-credit rate encoded as a string.
    - `pricing_version` string, required: Immutable published pricing revision at admission.
    - `unit` string, required: Unit counted by the pricing basis.
    - `variant` 'provider_cost', required: AI analysis is always rated from measured provider cost.
  - `artifact_id` string, nullable, required: Immutable result artifact identity when admitted.
  - `execution_id` string, nullable, required: Customer-credit accounting execution identity.
  - `job_id` string, required: Durable analysis job identity.
  - `next_start_row` integer, nullable, required: One-based first row of the next chunk, or null.
  - `remaining_rows` integer, required: Rows after this admitted chunk.
  - `row_count` integer, required: Rows admitted in this job chunk.
  - `status` 'queued' | 'running' | 'blocked' | 'completed' | 'failed', required: Durable job lifecycle status.
  - `submission_id` string, nullable, required: Caller submission identity, or null for legacy admission.
  - `total_rows` integer, required: Rows in the complete caller input.
  - `workflow_run_id` string, required: Workflow progress identity; equal to job_id.

## 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)