API Calls

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

In order to update a spec, provide all fields, including those that are unchanged. The following is an example updating the rules trigger to be for every 1000 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 who 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

There is an endpoint to access historic data for each rule's executions. 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 all executions for which there are no changes at all. You can combine these 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

There is an endpoint to access aggregated history data for all rules under your account. 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

There is an endpoint to preview the evaluation of a Schedule Based Rule. When a POST request is sent, this endpoint 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

There is an endpoint to manually execute a Schedule Based Rule. When a POST request is sent to this endpoint, the rule is immediately scheduled to run.

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

Results can be fetched from the execution history when the rule execution is complete.

Read Governing Rules for an Object

There are endpoints to read all the rules that govern each ad, ad set, and ad campaign. 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 it, 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, we return all rules that, when previewed, would return the object. If it is false, we return all rules that would not.

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