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

# Get Flow Runs

> Get a list of all flow runs in your workspace

Retrieves a paginated list of flow runs with optional filtering by flow ID or status.

## Usage Notes

* Results are paginated with a default limit of 100
* Results are ordered by creation date (newest first)
* Use filters to narrow down results by flow or status
* The response includes complete flow run details

## Request

<ParamField query="flow_id" type="string">
  Filter by a specific flow ID to only return runs for that flow.
</ParamField>

<ParamField query="status" type="string">
  Filter by status. Valid values: `processing`, `review`, `completed`, or `failed`.
</ParamField>

<ParamField query="limit" type="number" default="100">
  Maximum number of results to return. Maximum value is 1000.
</ParamField>

<ParamField query="offset" type="number" default="0">
  Number of results to skip for pagination.
</ParamField>

## Response

<ResponseExample>
  ```json theme={null}
  {
    "flow_runs": [
      {
        "id": "Wp7kRnT2mX4vQ9bL",
        "flow_id": "dk4g1tUg1uHLs8YU",
        "workspace_id": "uT2bJNWN75YPU95r",
        "status": "completed",
        "status_history": [
          {
            "status": "processing",
            "time": 1682366228,
            "message": "Flow started via api"
          },
          {
            "status": "completed",
            "time": 1682366258,
            "message": "Flow completed successfully"
          }
        ],
        "error": null,
        "metadata": {
          "customer_id": "12345",
          "order_number": "PO-2024-001"
        },
        "trigger_method": "api",
        "start_time": 1682366228,
        "end_time": 1682366258,
        "duration": 30000,
        "drive_files": {},
        "created_at": 1682366228,
        "updated_at": 1682366258
      },
      {
        "id": "hN3cYs8fKj6pA5wD",
        "flow_id": "dk4g1tUg1uHLs8YU",
        "workspace_id": "uT2bJNWN75YPU95r",
        "status": "processing",
        "status_history": [
          {
            "status": "processing",
            "time": 1682366328,
            "message": "Flow started via api"
          }
        ],
        "error": null,
        "metadata": {
          "customer_id": "67890"
        },
        "trigger_method": "api",
        "start_time": 1682366328,
        "end_time": null,
        "duration": 0,
        "drive_files": {},
        "created_at": 1682366328,
        "updated_at": 1682366328
      }
    ],
    "pagination": {
      "total": 250,
      "limit": 100,
      "offset": 0,
      "next_offset": 100,
      "filter": "all"
    }
  }
  ```
</ResponseExample>

<RequestExample>
  ```bash cURL theme={null}
  curl --request GET \
    --url 'https://api.tableflow.com/v2/flows/runs?status=completed&limit=50' \
    --header 'Authorization: Bearer YOUR_API_KEY'
  ```

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

  response = requests.get(
      "https://api.tableflow.com/v2/flows/runs",
      headers={
          "Authorization": "Bearer YOUR_API_KEY"
      },
      params={
          "status": "completed",
          "limit": 50
      }
  )

  result = response.json()
  flow_runs = result["flow_runs"]
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch("https://api.tableflow.com/v2/flows/runs?status=completed&limit=50", {
    method: "GET",
    headers: {
      "Authorization": "Bearer YOUR_API_KEY"
    }
  });

  const result = await response.json();
  const flowRuns = result.flow_runs;
  ```
</RequestExample>

<ResponseField name="flow_runs" type="array" required>
  Array of flow run objects

  <Expandable title="Flow Run Object">
    <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: processing, review, completed, or failed
    </ResponseField>

    <ResponseField name="status_history" type="array" required>
      History of status changes
    </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="drive_files" type="object">
      Google Drive files created during the flow
    </ResponseField>

    <ResponseField name="created_at" type="number" required>
      Unix timestamp when created
    </ResponseField>

    <ResponseField name="updated_at" type="number" required>
      Unix timestamp when last updated
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="pagination" type="object" required>
  Pagination information

  <Expandable title="Pagination Object">
    <ResponseField name="total" type="number" required>
      Total number of items
    </ResponseField>

    <ResponseField name="limit" type="number" required>
      Number of items per page
    </ResponseField>

    <ResponseField name="offset" type="number" required>
      Current offset
    </ResponseField>

    <ResponseField name="next_offset" type="number" required>
      Offset for the next page (0 if no more pages)
    </ResponseField>

    <ResponseField name="filter" type="string" required>
      The filter used (always "all" for this endpoint)
    </ResponseField>
  </Expandable>
</ResponseField>