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

# Run Flow

> Execute a flow with uploaded files

Executes a flow by uploading files and triggering the configured workflow steps.

## Usage Notes

* Files are uploaded as multipart/form-data
* File field names must match the flow's configuration
* Required files must be provided or the request will fail
* The flow executes asynchronously - use the returned ID to check status
* Use metadata to include custom data that will be preserved in the flow run

## Request

<ParamField path="id" type="string" required>
  The ID of the flow to run
</ParamField>

<ParamField body="file" type="file">
  File(s) to upload. The field name must match the `key` defined in the flow's `file_input_config.file_fields`.
  For fields that accept multiple files, append an index starting at 1 (e.g., `attachments_1`, `attachments_2`).
</ParamField>

<ParamField body="name" type="string">
  Optional name for the flow run. This is useful for identifying flow runs in the TableFlow UI.
</ParamField>

<ParamField body="{file_key}_metadata" type="string">
  JSON string containing metadata for a specific file. Replace `{file_key}` with the file field key
  (e.g., `purchase_order_metadata`). This metadata is associated with the individual file's extraction.
</ParamField>

<ParamField body="{file_key}_guidance" type="string">
  Optional extraction guidance for a specific file. Replace `{file_key}` with the file field key
  (e.g., `purchase_order_guidance`). Use this to provide hints to the AI about the document structure
  or specific values to look for in that particular file.
</ParamField>

<ParamField body="metadata" type="string">
  JSON string containing metadata for the entire flow run. This metadata will be included in all flow run responses and webhooks.
</ParamField>

## Response

<ResponseExample>
  ```json theme={null}
  {
    "id": "Wp7kRnT2mX4vQ9bL",
    "flow_id": "dk4g1tUg1uHLs8YU",
    "workspace_id": "uT2bJNWN75YPU95r",
    "status": "processing",
    "status_history": [
      {
        "status": "processing",
        "time": 1682366228,
        "message": "Flow started via api"
      }
    ],
    "error": null,
    "metadata": {
      "customer_id": "12345",
      "order_number": "PO-2024-001"
    },
    "trigger_method": "api",
    "start_time": 1682366228,
    "end_time": null,
    "duration": 0,
    "drive_files": {},
    "created_at": 1682366228,
    "updated_at": 1682366228
  }
  ```
</ResponseExample>

<RequestExample>
  ```bash cURL theme={null}
  curl --request POST \
    --url https://api.tableflow.com/v2/flows/dk4g1tUg1uHLs8YU/run \
    --header 'Authorization: Bearer YOUR_API_KEY' \
    --header 'Content-Type: multipart/form-data' \
    --form 'purchase_order=@/path/to/po.pdf' \
    --form 'invoice=@/path/to/invoice.pdf' \
    --form 'name=PO-123 Reconciliation' \
    --form 'purchase_order_metadata={"po_number": "PO-123"}' \
    --form 'purchase_order_guidance=The PO number may include revision info like REV:0 at the end — strip that and only extract the base PO number' \
    --form 'metadata={"customer_id": "12345"}'
  ```

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

  files = {
      "purchase_order": open("po.pdf", "rb"),
      "invoice": open("invoice.pdf", "rb")
  }

  data = {
      "name": "PO-123 Reconciliation",
      "purchase_order_metadata": json.dumps({"po_number": "PO-123"}),
      "purchase_order_guidance": "The PO number may include revision info like REV:0 at the end — strip that and only extract the base PO number",
      "metadata": json.dumps({"customer_id": "12345"})
  }

  response = requests.post(
      "https://api.tableflow.com/v2/flows/dk4g1tUg1uHLs8YU/run",
      headers={
          "Authorization": "Bearer YOUR_API_KEY"
      },
      files=files,
      data=data
  )

  flow_run = response.json()
  ```

  ```javascript JavaScript theme={null}
  const formData = new FormData();
  formData.append("purchase_order", purchaseOrderFile);
  formData.append("invoice", invoiceFile);
  formData.append("name", "PO-123 Reconciliation");
  formData.append("purchase_order_metadata", JSON.stringify({ po_number: "PO-123" }));
  formData.append("purchase_order_guidance", "The PO number may include revision info like REV:0 at the end — strip that and only extract the base PO number");
  formData.append("metadata", JSON.stringify({ customer_id: "12345" }));

  const response = await fetch("https://api.tableflow.com/v2/flows/dk4g1tUg1uHLs8YU/run", {
    method: "POST",
    headers: {
      "Authorization": "Bearer YOUR_API_KEY"
    },
    body: formData
  });

  const flowRun = await response.json();
  ```
</RequestExample>

<ResponseField name="id" type="string" required>
  The unique identifier for the flow run
</ResponseField>

<ResponseField name="flow_id" type="string" required>
  The ID of the flow being executed
</ResponseField>

<ResponseField name="workspace_id" type="string" required>
  The workspace ID
</ResponseField>

<ResponseField name="status" type="string" required>
  Current status of the flow run: processing, review, completed, or failed
</ResponseField>

<ResponseField name="status_history" type="array" required>
  History of status changes

  <Expandable title="Status History Entry">
    <ResponseField name="status" type="string" required>
      The status value
    </ResponseField>

    <ResponseField name="time" type="number" required>
      Unix timestamp of the status change
    </ResponseField>

    <ResponseField name="message" type="string" required>
      Description of the status change
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="error" type="string">
  Error message if the flow run failed
</ResponseField>

<ResponseField name="metadata" type="object">
  Custom metadata provided when running the flow
</ResponseField>

<ResponseField name="trigger_method" type="string" required>
  How the flow was triggered: api or manual
</ResponseField>

<ResponseField name="start_time" type="number" required>
  Unix timestamp when the flow run started
</ResponseField>

<ResponseField name="end_time" type="number">
  Unix timestamp when the flow run completed
</ResponseField>

<ResponseField name="duration" type="number" required>
  Duration of the flow run in milliseconds
</ResponseField>

<ResponseField name="created_at" type="number" required>
  Unix timestamp when the flow run was created
</ResponseField>

<ResponseField name="updated_at" type="number" required>
  Unix timestamp when the flow run was last updated
</ResponseField>