API - Rule Execution

Authentication required

Before calling this API, ensure you have a valid Bearer token. See API Authentication for how to obtain one.

The Rule Execution API triggers execution of live rules that are scheduled for a specific date. It's typically called on demand after a batch of transactions has been uploaded, to run or re-run those rules without waiting for their normal schedule.

Important

When using the endpoint to run rules outside of their schedules, execution_date needs to be a past date.

If you need a business rule to run again on the same day, set the force flag to true.

Choosing an Execution Mode

The request body controls which rules run and how their alerts are generated. Choose one of the three modes below — rule_ids and rule_group_ids are mutually exclusive and cannot be combined in the same request.

Request body	Which rules run	Alerts produced
(neither field provided)	All live rules scheduled for execution_date	One alert per rule
rule_ids	Only the listed rules, always as standalone rules	One alert per entity per rule — never aggregated, even if a rule belongs to a group
rule_group_ids	All rules belonging to each listed group	One aggregated alert per entity per group, if the group's alert aggregation is enabled; otherwise the group's rules produce individual alerts instead

note

Alert Aggregation is configured on the rule group itself, in the rule group settings — not in the request body.

Rule scheduling notes

• Rule scheduling: execution is driven by the scheduled day configured in the business rule manager. For example, calling the endpoint on November 22nd processes all live rules scheduled for November 22nd, regardless of the time of day.
• Multiple daily runs: to run the same rule more than once in a day, trigger execution again for that rule.
• The force flag cannot override a rule's schedule. If a rule isn't scheduled for the requested date, it won't run, no matter what force is set to.

Understanding the Response

The response shape depends on which execution mode you used.

• Running individual rules (default, or rule_ids)

  The response contains two lists:

  • accepted_rules — rules that will be executed for the given execution_date.
  • rejected_rules — rules that will not be executed, each with a reason. Review these carefully.

  Rejection reasons:

  Reason	When it's returned
  Rule is not live	rule_ids was provided and the requested rule isn't in the current live rules set
  Rule is not scheduled to run on <date>	The rule is live, but its schedule doesn't match the requested execution_date
  Rule has already run for <date>	The rule already has an execution record for that date and force is false. Set force to true to run it again

  If rule_ids isn't provided (i.e. all scheduled rules run), "Rule has already run for <date>" is the only rejection reason you'll see — the other two don't apply because every rule considered is already live and scheduled.

• Running rule groups (rule_group_ids)

  Instead of a single result, the response content is a list with one entry per rule group. Each entry contains:

  • rule_group_id
  • execution_id — a separate execution ID per rule group.
  • accepted_rules
  • rejected_rules

  This differs from the individual-rule response in two ways:

  • rejected_rules is a plain list of rule IDs, with no reason field.
  • The only rejection reason is a rule having already run for <date>. Rules in the group that simply aren't scheduled for <date> aren't reported as rejected — they're just left out of both lists.

Using execution_id for Monitoring

When rules are accepted for execution (HTTP 202 or HTTP 207), the response includes an execution_id and a list of accepted_rules. This information can be used to monitor execution progress using the Rule Execution Status endpoint or the Observability API.

Execution Timing

Rule execution does not occur immediately if transaction or entity ingestion processes are still in progress. Once ingestion is complete, the rules will automatically execute based on the submitted request.

---

Loading ...