Running Rule Sets
Running a rule set inside an environment and reading what it produced.
Running a rule set means submitting input to an environment, which evaluates each rule's condition against that input and carries out the actions of every rule that matches. Runs are asynchronous: a run is queued and processed in the background, and you get back a correlation id that identifies it. You read the outcome afterward from the logs.
Ways to run
A rule set can be started three ways, all of which queue the same kind of run:
- Interactively from the RuleSet Runner in the app.
- On a schedule — see Scheduling.
- From your own code with an API key — see API Access.
The RuleSet Runner
The runner walks you through a short flow. First it presents the inputs. If the rule set has an authored runtime form, you fill that out; otherwise you build the input by hand, adding typed items where each item has a context key, a data type, and a value (text, numbers, dates, or an uploaded file). These values become the context available when the run begins.
Next you choose the target environment. Only environments that are registered and where you hold the Run (or Admin) role are selectable; others are shown disabled with the reason — Not Registered or No Run Permission. Submitting packages the inputs into one request and queues the run, returning its correlation id.
What if?
After a run, the runner offers a What if? expander — “Try changing an input and see which outcomes flip — without queueing a real run.” Edit the inputs (seeded from the run you just did) and click Compare: the rule set runs twice in the sandbox, baseline vs. modified, and the outcome differences are shown with a provenance chain back to the inputs.
These comparison runs are sandboxed the same way tests are — no side effects, unmetered, and nothing in run history. AI conditions need mocks or an explicit allow live AI, which adds a warning that results may differ on re-run because AI output is nondeterministic.
The comparison reports:
- Changed inputs — the values you edited, shown as old → new.
- Rule flips — a badge for each rule whose firing changed: Now fires, No longer fires, Fires more, or Fires less (with the before and after counts).
- Changed conclusions — each final-context change, expandable to a “Why it changed” chain of the firings that produced it, back to the inputs. Classic single-pass sets show the diff without the chain.
- Derived-fact changes and, for an inference set, the full modified trace.
Inputs and outputs
Each input you provide is a typed value, and file values can be uploaded alongside text, number, and date values. As the rule set runs, its actions read from and write to the run's context — an action can transform data, call an API, run an AI prompt, or write results back into the context for later actions to use.
Reading results
Because runs are queued, the response confirms that the work was accepted rather than returning final results inline. To see what happened — which rules matched, what each action did, and any errors — open Logs & Run History and view the run by its correlation id.
A rule set running in Inference or Goal-driven mode can also record a run trace — a firing-by-firing account of the run — that you can read back in run history once its Record run traces option is turned on.
A goal-driven rule set accepts a per-run override of the keys it works backwards from: the Run page offers a Goals for this run box, and the API takes a comma-separated goals query parameter. Leave it out and the rule set's own declared goals apply.
Run limits on the shared host
On a Shared or Free tier environment, each run counts against your plan's monthly run allowance. When the included runs are used up, runs draw on your organization's credits to cover the overage; if neither is available the run is rejected with a message to buy credits or upgrade. Dedicated environments run on your own resources and are not metered this way. See Plans & Tiers.