> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cloudsquid.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Start AI run (asynchronous)

> Start AI processing for a row in an extraction or reconciliation table. This is an asynchronous operation; use the returned run_id to check status and retrieve results.

<Note>
  **This is step 2 of 3** in the async run pattern. You need a `row_id` from [uploading a file](/api-reference/tables/upload-a-new-file-into-a-table) first. After starting the run, [poll for results](/api-reference/tables/get-ai-run-status-&-result) using the returned `run_id`.

  See the full [async run pattern guide](/concepts/async-run-pattern) for a complete working example.
</Note>

## What this does

Enqueues an AI job for the given row and returns immediately with a `run_id`. Processing happens asynchronously — the run status transitions from `pending` → `running` → `done` (or `error`).

## Zero retention mode

Pass `"zero_retention": true` to run extraction without persisting intermediate results. Useful for privacy-sensitive workloads where you want the final output but not intermediate artifacts stored on Cloudsquid infrastructure.

## Example

```python Python theme={null}
import requests

response = requests.post(
    "https://api.cloudsquid.io/api/projects/my-project/tables/TABLE_ID/run",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"row_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"}
)
run_id = response.json()["run_id"]
```

Pass `run_id` to `GET /run/{run_id}` to check status and retrieve results.


## OpenAPI

````yaml post /projects/{project_name}/tables/{table_id}/run
openapi: 3.0.3
info:
  title: Cloudsquid
  description: This is the backend of cloudsquid specification
  termsOfService: cloudsquid.io
  contact:
    email: info@cloudsquid.io
  license:
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.html
  version: 1.0.11
servers:
  - url: https://api.cloudsquid.io/api
    description: API
security:
  - api-key: []
paths:
  /projects/{project_name}/tables/{table_id}/run:
    parameters:
      - name: project_name
        in: path
        required: true
        description: The name of the project
        schema:
          type: string
      - name: table_id
        in: path
        required: true
        description: The id of the table
        schema:
          type: string
          format: uuid
    post:
      tags:
        - tables
      summary: Request starts the analyze process for a table
      description: >-
        Start an AI run for a file. The runs are asynchronous and the status can
        be checked with the run_id.
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                row_id:
                  type: string
                  format: uuid
                  description: Row to start run
                zero_retention:
                  type: boolean
                  description: >-
                    indicates if the extraction is run in zero-retention mode.
                    Default false
              required:
                - row_id
      responses:
        '202':
          description: Analysis started successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  run_id:
                    type: string
                    format: uuid
                    description: The id of the run
                required:
                  - run_id
        '400':
          description: Bad or malformed request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Something unexpectedly went wrong internally
components:
  schemas:
    Error:
      type: object
      properties:
        errorMessage:
          type: string
      required:
        - errorMessage
  securitySchemes:
    api-key:
      type: apiKey
      in: header
      name: X-API-Key

````