API Calls

Updated: Jun 16, 2026

See examples of API calls to use the Ad Rules Engine.

Read all rules of an account

curl -G   \
-d 'fields=name,evaluation_spec,execution_spec,status'   \
-d 'access_token=<ACCESS_TOKEN>'   \
https://graph.facebook.com/<VERSION>/<AD_ACCOUNT_ID>/adrules_library

Read a rule

curl -G   \
-d 'fields=name,evaluation_spec,execution_spec,status'   \
-d 'access_token=<ACCESS_TOKEN>'   \
https://graph.facebook.com/<VERSION>/<AD_RULE_ID>

Update a rule

To update a spec, provide all fields, including those that are unchanged. The following is an example updating the rule's trigger to be for every 1,000 impressions. Updating a rule's status requires no spec changes.

curl \
-F 'evaluation_spec={
      "evaluation_type": ...,
      "trigger" : {
        "type": "STATS_MILESTONE",
        "field": "impressions",
        "value": 1000,
        "operator": "EQUAL"
      },
      "filters": ...
     ]
   }' \
-F 'access_token=<ACCESS_TOKEN>'   \
https://graph.facebook.com/<VERSION>/<AD_RULE_ID>

Here is an example updating the filters to select all ads that have more than 200 clicks. Other filters such as entity_type and time_preset must still be in this update.

curl \
-F 'evaluation_spec={
      "evaluation_type": ...,
      "filters" : [
       {
         "field": "clicks",
         "value": 200,
         "operator": "GREATER_THAN",
       },
       {
       ...
     ]
   }' \
-F 'access_token=<ACCESS_TOKEN>'   \
https://graph.facebook.com/<VERSION>/<AD_RULE_ID>

Delete a rule

curl -X DELETE \
-d 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/<VERSION>/<AD_RULE_ID>

Access a rule's execution history

Access historic data for each rule's executions through a dedicated endpoint. By default, this endpoint provides relevant data, such as results and actions. You can also check the state of the rule at each execution to track edits.

curl -G   \
-d 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/<VERSION>/<AD_RULE_ID>/history

In addition, this endpoint supports three filtering mechanisms on the data: object_id, action, and hide_no_changes. You can filter the results by an object_id or an action to see results for only that object_id or action type.

You can also filter the results using the hide_no_changes flag to exclude executions that made no changes. You can combine the object_id, action, and hide_no_changes filters to further narrow your results.

curl -G   \
-d 'object_id=123' \
-d 'action=CHANGED_BID' \
-d 'hide_no_changes=true' \
-d "access_token=<ACCESS_TOKEN>" \
https://graph.facebook.com/<VERSION>/<AD_RULE_ID>/history

Access an account's execution history

Access aggregated history data for all rules under your account through a dedicated endpoint. By default, this endpoint provides the same relevant data as the rule's execution history, but also includes the id of the rules for each entry.

Entries in this endpoint are ordered from newest to oldest. This endpoint also supports the same filtering mechanisms as above: object_id, action, and hide_no_changes.

curl -G   \
-d 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/<VERSION>/<AD_ACCOUNT_ID>/adrules_history

Preview a rule

Preview the evaluation of a Schedule Based Rule by sending a POST request to this endpoint, which returns a list of objects that satisfy all specified filters of the rule at that time.

curl \
-F 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/<VERSION>/<AD_RULE_ID>/preview

Manually execute a rule

Manually execute a Schedule Based Rule by sending a POST request to this endpoint. When a POST request is sent to this endpoint, the engine immediately schedules the rule to run.

curl \
-F 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/<VERSION>/<AD_RULE_ID>/execute

You can fetch results from the execution history once execution completes.

Read governing rules for an object

Read all the rules that govern each ad, ad set, and ad campaign through these endpoints. By default, a rule governs an object if it statically references it by the id filter or dynamically references it by the entity_type filter.

This endpoint also supports an optional pass_evaluation. With pass_evaluation, you can further limit the list of rules, by whether or not the object would pass the rule's filters at that time. If pass_evaluation is true, you receive all rules that, when previewed, would return the object. If it is false, you receive all rules that would not.

curl \
-F 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/<VERSION>/<AD_OBJECT_ID>/adrules_governed