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

# Running and monitoring tools

> How to run a processor tool and track its progress in real time.

## Running a tool

Once a tool is configured, click **Run** in the right-hand panel of the tool editor. Filla starts processing your records immediately.

<Warning>
  Running a tool on a large table can make permanent changes to your Airtable records. Preview your configuration against a small test set (using a view filter) before running on your full table.
</Warning>

## Plan-limit gating

Tool runs count toward your workspace's records limit (Free plan: 20 records lifetime; paid plans: monthly cap — see [Billing](/docs/billing)). When your workspace is at the cap:

* **Manual runs** return "Workspace has reached its plan limit for this period" — the click is rejected and no run record is created.
* **Webhook triggers** return `429 Too Many Requests` with a `Retry-After` header set to the time remaining in your billing period.
* **Scheduled (cron) runs** are skipped silently for the period and resume automatically when usage frees up. The cron stays alive — the next tick after upgrade or period reset goes through normally.

Mid-run, if you cross the cap before the batch finishes, Filla stops cleanly at the boundary instead of writing past the limit. The execution log records a "plan limit reached" warning with the count of records that were skipped, and the run completes as partially-successful. Re-run the tool after upgrading or after the period rolls over to process the remainder.

The persistent **Plan usage banner** appears at the top of every tool editor when usage is at 80% or higher (always visible on the Free plan), so you don't get surprised at click-time.

## What happens when you run

<Steps>
  <Step title="Filla reads your records">
    Filla fetches records from your Airtable table in pages of up to 100. If you've set a source view or filter, only matching records are fetched.
  </Step>

  <Step title="Processing runs in the background">
    The HTTP response returns immediately. You don't wait for the entire run to complete. Processing continues on the server even if you close the browser tab.
  </Step>

  <Step title="Results are written back">
    As each batch completes, Filla writes results back to Airtable. Progress updates in real time in the monitoring panel.
  </Step>
</Steps>

## Monitoring progress

The run panel shows live metrics:

| Metric            | What it means                          |
| ----------------- | -------------------------------------- |
| **Records total** | Total records matched by the filter    |
| **Processed**     | Records Filla has attempted to process |
| **Succeeded**     | Records processed without errors       |
| **Failed**        | Records that encountered an error      |
| **Status**        | Running, Completed, or Failed          |

Below the metrics, an **execution log** shows a timestamped list of messages (info, warnings, and errors) for each step of the run.

## Run history

Each run creates a log entry. You can see past runs in the run history panel, including the status, start time, completion time, and record counts for each run.

## Downloading output files

For tools that produce downloadable files (like the CSV Exporter), a download link appears in the run panel after the run completes. The link is available for a limited time.

## Canceling a run

There is no cancel button once a run has started. To stop processing, you would need to close the tab, but the server-side process may continue for a moment before timing out. Use filters to limit the scope of a run before starting if you're concerned about processing too many records.

## Common questions

<AccordionGroup>
  <Accordion title="Can I run the same tool multiple times?">
    Yes. Click Run again at any time. Each run creates a new log entry. Some tools have a "Skip already processed" option to avoid re-processing records that already have output values.
  </Accordion>

  <Accordion title="How long does a run take?">
    It depends on the number of records and the tool type. Tools that make network requests per record (Geocoder, Email Validator with MX check) are slower. A table of 1,000 records might take 1-5 minutes.
  </Accordion>

  <Accordion title="What happens to the run if I close the browser?">
    Processing continues on the server. Open the tool again to see the run status and results.
  </Accordion>

  <Accordion title="Does Filla respect Airtable's API rate limits?">
    Yes. Filla includes built-in rate limit management and pauses between write batches to stay within Airtable's limits.
  </Accordion>
</AccordionGroup>