Skip to main content
Talk to salesStart

Running safely: filtering + spend control

Run only the rows you want by combining scope filters, unprocessed-only behavior, staged rollout caps, and max-credit guardrails before execution.

Updated September 28, 2026

This page recommends the Autotouch CLI for the fastest execution path. Use the API reference when you need the raw HTTP contract.

Why this matters

Safe execution is mostly about controlling eligibility before a run starts. Filtering, unprocessed-only behavior, rollout caps, and preflight estimates help control spend and unintended bulk actions. Estimates are non-billable snapshots; rows or cell state can change before execution, so the run response is the admission record.

How row selection works

  1. Apply scope: "filtered" with your filters rules.
  2. Apply unprocessedOnly: true to skip rows already completed.
  3. Apply firstN as a final rollout cap.

firstN + unprocessedOnly means "first N currently eligible unprocessed rows." Use it for staged rollout, not an exact-count guarantee: fewer rows may qualify, and concurrent table changes can affect the set before admission. The CLI --max-credits guard estimates before submission; the HTTP run body has no maxCredits field, so an HTTP client must enforce its own estimate threshold before submitting.

Recommended run pattern

  1. Call estimate with your exact payload.
  2. Enforce a max-credit budget in your app or agent.
  3. Run with the same payload only when estimate is acceptable.

CLI example

# 1) Estimate targeted rows first
autotouch columns estimate --table-id "<TABLE_ID>" --column-id "<COLUMN_ID>" --scope filtered --filters-file filters.json --unprocessed-only

# 2) Run the same scope with a rollout cap
autotouch columns run --table-id "<TABLE_ID>" --column-id "<COLUMN_ID>" --scope filtered --filters-file filters.json --unprocessed-only --first-n 200 --show-estimate --wait

# 3) Block execution if estimated spend is too high
autotouch columns run --table-id "<TABLE_ID>" --column-id "<COLUMN_ID>" --scope filtered --filters-file filters.json --unprocessed-only --max-credits 50

Select up to N eligible rows

autotouch columns run-next --table-id "<TABLE_ID>" --column-id "<COLUMN_ID>" --count 5 --filters-file filters.json --show-estimate --wait

run-next resolves candidate row IDs first and submits those IDs with scope=subset. This makes the admitted ID set explicit, but the command may select fewer than --count when fewer eligible rows match. Later table changes do not redefine the submitted ID set.

Track and cancel an HTTP run

A successful run submission returns an operationRunId for durable progress. Most are canonical IDs for GET /api/operation-runs/{operation_run_id}; bounded column planning can return an arplan_ pre-admission alias, which you resolve with Get column planning status before polling the nested canonical operation. Both reads use jobs:read; cancel with POST /api/operation-runs/{operation_run_id}/cancel using columns:run. The response may also include a native jobId for executor compatibility. Canonical statuses include queued, running, waiting, completed, partial, error, failed, cancelled, and missing. Cancellation is a request; inspect the returned run state. Column run submission has no idempotency-key or retry endpoint. If a response is lost or a run fails, list runs for the table and inspect results before submitting another run.

cURL payload example

{
  "scope": "filtered",
  "filters": {
    "mode": "and",
    "filters": [
      { "columnKey": "linkedin_url", "operator": "isNotEmpty" },
      { "columnKey": "country", "operator": "equals", "value": "United States" }
    ]
  },
  "unprocessedOnly": true,
  "firstN": 200
}

For a scalar nested in a JSON output column, add jsonPath to the filter leaf. Paths use dotted object keys, with numeric indexes for arrays; filter a scalar leaf rather than a whole object or array.

{
  "mode": "and",
  "filters": [
    {
      "columnKey": "research_profile",
      "jsonPath": "school_domain",
      "operator": "equals",
      "value": "example.edu"
    }
  ]
}

Related pages

Docs