Skip to main content

Automated Rules

An Automated Rule automates changes to Campaigns, Ad Squads and Ads. A rule takes 1 or 2 conditions. If it has two, both must be the same type. Each rule checks its conditions on a schedule, and when the conditions are met it runs an action, such as pausing or unpausing delivery. Rules belong to an Ad Account.

Automated Rule Attributes​

AttributeDescriptionRequiredPossible Values
rule_idAutomated Rule IDRead-only
rule_nameAutomated Rule name. It can be at most 150 characters. The service rejects a longer name with status_code 400 and an error message.R
ad_account_idAd Account ID, always taken from the request pathRead-only
rule_typeType of the Automated RuleRSee Automated Rule Enum Values
ad_entitiesThe entities the rule acts onRSee ad_entities
excluded_entity_valuesIDs of entities excluded from the ruleRead-only
conditionArray of conditions; the action runs when the conditions are met. A rule needs 1 or 2 conditions. With 2, both must have the same condition_type. Otherwise the service rejects the request with status_code 400 and an error message.RSee condition
actionThe action to run when the conditions are metRSee action
action_frequencyHow often the action can runRSee Automated Rule Enum Values
rule_frequencyWhen the rule is evaluatedR (not sent for a single TIME condition with value_time)See rule_frequency
rule_limitsLimits for bid and budget increase rulesOSee rule_limits
notificationEmail notification settingsOSee notification
created_byEmail address (or user ID) of the person who created the rule. Read-only: it is set from the caller, and any value you send is ignoredRead-only
rule_statusStatus of the Automated RuleRead-onlySee Automated Rule Enum Values
associated_ad_entityThe entity the rule is associated withRead-onlySee Automated Rule Enum Values
created_time_stampCreation time in epoch milliseconds, returned as a stringRead-only"1793129614503"

ad_entities​

AttributeDescriptionRequiredPossible Values
entity_typeType of the entities the rule acts onRCAMPAIGN, AD_SET, AD (only works with the CHANGE_DELIVERY_STATUS action)
all_activeIf true, the rule applies to all active entities of entity_type. Use either all_active or entity_values, not bothOtrue
entity_values.valuesArray of entity IDs. This is only required when all_active is not set. ad_entities takes either all_active: true or entity_values with a list of IDs (max 100, no duplicates)O["0a76084c-5c12-3864-9e63-e283360d3631"]

condition​

AttributeDescriptionRequiredPossible Values
condition_typeThe metric the condition checksRSee Automated Rule Enum Values
operatorComparison operatorRSee Automated Rule Enum Values
value_number.valueThreshold value for SPENT, RESULT and COST_PER_RESULT conditions. Monetary thresholds use micro-currency. Returned as a string in responsesR (not used with TIME)50000000
value_number.condition_time_horizonTime period the metric is measured over. Not used with TIMEOSee Automated Rule Enum Values
value_time.time_zoneIANA time zone for the TIME condition. Optional: set value_time instead of value_number for a one-time TIME conditionR when value_time is setAmerica/Los_Angeles
value_time.valueTime threshold in epoch millisecondsR when value_time is set1793129614503

action​

AttributeDescriptionRequiredPossible Values
action_typeThe action to runRSee Automated Rule Enum Values
value_string.valueTarget value for CHANGE_DELIVERY_STATUSOENTITY_PAUSED, ENTITY_UNPAUSED
value_number.amountAdjustment amount for bid and budget actions. When unit is PERCENTAGE, the absolute value of amount must be between 1 and 100 (negative decreases, positive increases). Otherwise the service rejects the request with status_code 400 and an error message.O10
value_number.unitUnit for value_number.amountOSee Automated Rule Enum Values

rule_frequency​

Set either daily_fixed or daily_custom, not both.

AttributeDescriptionRequiredPossible Values
daily_fixed.hourHour of the day the rule is evaluated (0-23)R9
daily_fixed.minuteMinute of the hour the rule is evaluatedO0 (default)
daily_fixed.time_zoneIANA time zone used for hour and minuteRAmerica/Los_Angeles
daily_custom.itemsArray of 1 to 7 schedules, one per day of the week. The same day cannot appear twiceR
daily_custom.items[].dayDay of the week the rule is evaluatedRSUNDAY, MONDAY, TUESDAY, WEDNESDAY, THURSDAY, FRIDAY, SATURDAY
daily_custom.items[].hourHour of the day the rule is evaluated (0-23)R9
daily_custom.items[].minuteMinute of the hour the rule is evaluated (0-59)O0 (default)
daily_custom.items[].time_zoneIANA time zone used for hour and minuteRAmerica/Los_Angeles

rule_limits​

Set exactly one of bid, daily_budget or lifetime_budget, matching the action:

  • CHANGE_BID uses bid.
  • CHANGE_BUDGET_DAILY uses daily_budget.
  • CHANGE_BUDGET_LIFETIME uses lifetime_budget.

Other actions ignore rule_limits. Seasonal budget rules (SEASONAL_BUDGET_ADJUSTMENT) must not send rule_limits.

AttributeDescriptionRequiredPossible Values
bid.maximum_bid_capMaximum bid allowed for bid increase rules (greater than 0)O
bid.minimum_bid_floorMinimum bid allowed for bid increase rules (0 or more)O
daily_budget.maximum_daily_budget_capMaximum daily budget allowed for daily budget increase rules (greater than 0)O
daily_budget.minimum_daily_budget_floorMinimum daily budget allowed for daily budget increase rules (0 or more)O
lifetime_budget.maximum_lifetime_budget_capMaximum lifetime budget allowed for lifetime budget increase rules (greater than 0)O
lifetime_budget.minimum_lifetime_budget_floorMinimum lifetime budget allowed for lifetime budget increase rules (0 or more)O

notification​

AttributeDescriptionRequiredPossible Values
enabledWhether email notifications are sentOtrue, false (default)
email_idsEmail addresses that are notified. A rule can have up to 15 addresses, and each one must be a valid email address of someone in the Ad Account's Organization. Otherwise the gateway rejects the request with an HTTP error (E1008) explaining the errorO["honey.badger@example.com"]

Errors​

Errors are reported by one of two layers. Always check both the HTTP status and, for service errors, status_code in the response body.

Automated Rules service errors. These are returned with HTTP status 200. The status_code attribute in the response body holds the actual status, and error.error_message describes the error.

status_codeMeaning
400Validation failure
404Unknown rule
409Conflict, on create, update and when turning a rule ON. "A conflicting active rule already exists for the same entity and action type."
500Any other exception
{
"request_status": "SUCCESS",
"request_id": "ef7009ab-0d9e-4566-bf45-b35127ee80d2",
"status_code": "400",
"error": {
"error_message": "..."
}
}

Gateway errors. The gateway rejects some requests before they reach the service, and returns a real HTTP error (not 200). It rejects invalid email addresses in notification.email_ids (E1008) and invalid entity IDs in ad_entities (E3004). For other failures, such as missing permissions or unknown Ad Accounts, see Errors.

Create an Automated Rule​

This endpoint creates an Automated Rule within a specified Ad Account.

If the new rule overlaps with an existing rule, the response includes conflict_warnings. When a rule for specific entities overlaps with a rule for the whole Ad Account, the more specific rule takes priority.

HTTP Request​

POST https://adsapi.snapchat.com/v1/adaccounts/{ad_account_id}/smart-rules

Parameters​

ParameterDescription
ad_account_idAd Account ID

Example - Create an Automated Rule​

This rule pauses an Ad Squad once it has spent more than 50.00 in a day. The rule is evaluated every day at 9:00 in the America/Los_Angeles time zone.

curl -X POST \
-H "Authorization: Bearer meowmeowmeow" \
-H "Content-Type: application/json" \
-d '{"rule_name":"Badger Spend Guard","rule_type":"SCHEDULED_DELIVERY","ad_entities":{"entity_type":"AD_SET","entity_values":{"values":["0a76084c-5c12-3864-9e63-e283360d3631"]}},"condition":[{"condition_type":"SPENT","operator":"GREATER_THAN","value_number":{"value":50000000,"condition_time_horizon":"HORIZON_TODAY"}}],"action":{"action_type":"CHANGE_DELIVERY_STATUS","value_string":{"value":"ENTITY_PAUSED"}},"action_frequency":"ONCE_DAILY","rule_frequency":{"daily_fixed":{"hour":9,"time_zone":"America/Los_Angeles"}}}' \
"https://adsapi.snapchat.com/v1/adaccounts/22225ba6-7559-4000-9663-bace8adff5f2/smart-rules"

The above command returns JSON structured like this:

{
"request_status": "SUCCESS",
"request_id": "8db78718-881c-4f22-815d-51a890620fa3",
"status_code": "200",
"success": {
"rule_id": "1be199c0-28ce-43dc-ada1-f7f608f70d2f",
"conflict_warnings": [
"A global rule exists for this action type. This specific rule will take priority over the global rule."
]
}
}

Get a specific Automated Rule​

This endpoint retrieves a specific Automated Rule.

HTTP Request​

GET https://adsapi.snapchat.com/v1/adaccounts/{ad_account_id}/smart-rules/{rule_id}

URL Parameters​

ParameterDescription
ad_account_idAd Account ID
rule_idAutomated Rule ID

Example - Get a specific Automated Rule​

curl "https://adsapi.snapchat.com/v1/adaccounts/22225ba6-7559-4000-9663-bace8adff5f2/smart-rules/1be199c0-28ce-43dc-ada1-f7f608f70d2f" \
-H "Authorization: Bearer meowmeowmeow"

The above command returns JSON structured like this:

{
"request_status": "SUCCESS",
"request_id": "c791b681-cdb9-4d9e-9585-fc384bd587bd",
"status_code": "200",
"rule": {
"rule_id": "1be199c0-28ce-43dc-ada1-f7f608f70d2f",
"rule_name": "Badger Spend Guard",
"ad_account_id": "22225ba6-7559-4000-9663-bace8adff5f2",
"associated_ad_entity": {
"entity_type": "AD_SQUAD",
"entity_value": "0a76084c-5c12-3864-9e63-e283360d3631"
},
"rule_type": "SCHEDULED_DELIVERY",
"condition": [
{
"condition_type": "SPENT",
"operator": "GREATER_THAN",
"value_number": {
"value": "50000000",
"condition_time_horizon": "HORIZON_TODAY"
}
}
],
"action": {
"action_type": "CHANGE_DELIVERY_STATUS",
"value_string": {
"value": "ENTITY_PAUSED"
}
},
"action_frequency": "ONCE_DAILY",
"rule_frequency": {
"daily_fixed": {
"hour": 9,
"minute": 0,
"time_zone": "America/Los_Angeles"
}
},
"created_by": "honey.badger@example.com",
"rule_status": "ON",
"created_time_stamp": "1793129614503",
"ad_entities": {
"entity_type": "AD_SET",
"entity_values": {
"values": ["0a76084c-5c12-3864-9e63-e283360d3631"]
}
},
"excluded_entity_values": []
}
}

Automated Rule Enum Values​

AttributePossible Values
rule_typeBID_ADJUSTMENT, BUDGET_ADJUSTMENT, BID_STRATEGY_ADJUSTMENT, SEASONAL_BID_ADJUSTMENT, SEASONAL_BUDGET_ADJUSTMENT, SCHEDULED_DELIVERY
rule_statusON, OFF, EXPIRED
ad_entities.entity_typeCAMPAIGN, AD_SET, AD
associated_ad_entity.entity_typeCAMPAIGN, AD_SQUAD, AD
condition.condition_typeTIME, SPENT, RESULT, COST_PER_RESULT
condition.operatorGREATER_THAN, LESS_THAN, EQUALS
value_number.condition_time_horizonHORIZON_ALL, HORIZON_TODAY, HORIZON_YESTERDAY, HORIZON_7D, HORIZON_14D
action.action_typeCHANGE_BID, CHANGE_BUDGET_DAILY, CHANGE_BUDGET_LIFETIME, CHANGE_BID_STRATEGY, CHANGE_DELIVERY_STATUS
action.value_string.valueENTITY_PAUSED, ENTITY_UNPAUSED
action.value_number.unitABSOLUTE, PERCENTAGE
action_frequencyONCE_DAILY, ONCE_LIFETIME (TIME condition with value_time)
entity_enabled_status.before/afterENTITY_PAUSED, ENTITY_UNPAUSED

Update an Automated Rule (PATCH)​

This endpoint updates a specific Automated Rule. Only the attributes included in the request body are changed.

To turn a rule on or off, use the status attribute with the value ON or OFF. The current value is returned as rule_status.

HTTP Request​

PATCH https://adsapi.snapchat.com/v1/adaccounts/{ad_account_id}/smart-rules/{rule_id}

Parameters​

ParameterDescription
ad_account_idAd Account ID
rule_idAutomated Rule ID

Example - Turn off and rename an Automated Rule​

curl -X PATCH \
-H "Authorization: Bearer meowmeowmeow" \
-H "Content-Type: application/json" \
-d '{"status":"OFF","rule_name":"Badger Spend Guard - Paused"}' \
"https://adsapi.snapchat.com/v1/adaccounts/22225ba6-7559-4000-9663-bace8adff5f2/smart-rules/1be199c0-28ce-43dc-ada1-f7f608f70d2f"

The above command returns JSON structured like this:

{
"request_status": "SUCCESS",
"request_id": "f9265192-d9b7-4ac0-a0fe-bdadd8529479",
"status_code": "200",
"rule_id": "1be199c0-28ce-43dc-ada1-f7f608f70d2f",
"conflict_warnings": []
}

Get all Automated Rules under an Ad Account​

This endpoint retrieves all Automated Rules under a specified Ad Account. Results are paginated. To get the next page, pass the next_page_token value from the response as the page_token parameter.

HTTP Request​

GET https://adsapi.snapchat.com/v1/adaccounts/{ad_account_id}/smart-rules

Parameters​

ParameterDescription
ad_account_idAd Account ID
page_sizeOptional, the number of rules to return per page
page_tokenOptional, the next_page_token from the previous response
rule_typesOptional, comma-separated list of rule_type values to filter by, e.g. BID_ADJUSTMENT

Example - Get all Automated Rules under an Ad Account​

curl "https://adsapi.snapchat.com/v1/adaccounts/22225ba6-7559-4000-9663-bace8adff5f2/smart-rules" \
-H "Authorization: Bearer meowmeowmeow"

The above command returns JSON structured like this:

{
"request_status": "SUCCESS",
"request_id": "ee82921a-6038-495b-8bd0-92d85e8362dd",
"status_code": "200",
"success": {
"rules": [
{
"rule_id": "8e42f5d3-e819-4738-bb3b-8a3e3b6b0b57",
"rule_name": "Morning Wake-up",
"ad_account_id": "22225ba6-7559-4000-9663-bace8adff5f2",
"associated_ad_entity": {
"entity_type": "AD_SQUAD",
"entity_value": "0a76084c-5c12-3864-9e63-e283360d3631"
},
"rule_type": "SCHEDULED_DELIVERY",
"condition": [
{
"condition_type": "SPENT",
"operator": "LESS_THAN",
"value_number": {
"value": "80000000",
"condition_time_horizon": "HORIZON_TODAY"
}
}
],
"action": {
"action_type": "CHANGE_DELIVERY_STATUS",
"value_string": {
"value": "ENTITY_UNPAUSED"
}
},
"action_frequency": "ONCE_DAILY",
"rule_frequency": {
"daily_fixed": {
"hour": 1,
"minute": 0,
"time_zone": "America/Los_Angeles"
}
},
"notification": {
"email_ids": [],
"enabled": false
},
"created_by": "honey.badger@example.com",
"rule_status": "ON",
"created_time_stamp": "1793076158044",
"ad_entities": {
"entity_type": "AD_SET",
"entity_values": {
"values": ["0a76084c-5c12-3864-9e63-e283360d3631"]
}
},
"excluded_entity_values": []
}
],
"next_page_token": "MDoxNzkxODAyODExMTI3OmYzY2EwZDJmLWFhMDItNDA3ZC04NzJmLTI0NmQzZWIyNGU2ZTo="
}
}

Get Automated Rule Execution History​

This endpoint retrieves the history of Automated Rule executions for a specified Ad Account. Each entry shows the entity the rule acted on and its state before and after the action. Results are paginated in the same way as Get all Automated Rules under an Ad Account.

HTTP Request​

GET https://adsapi.snapchat.com/v1/adaccounts/{ad_account_id}/smart-rules/executions

Parameters​

ParameterDescription
ad_account_idAd Account ID
rule_idOptional, only return executions of this Automated Rule
start_timestampOptional, start of the time range in epoch milliseconds
end_timestampOptional, end of the time range in epoch milliseconds
page_sizeOptional, the number of executions to return per page
page_tokenOptional, the next_page_token from the previous response

Example - Get Automated Rule Execution History​

curl "https://adsapi.snapchat.com/v1/adaccounts/22225ba6-7559-4000-9663-bace8adff5f2/smart-rules/executions" \
-H "Authorization: Bearer meowmeowmeow"

The above command returns JSON structured like this:

{
"request_status": "SUCCESS",
"request_id": "9b72ad70-3985-4e37-a683-9d612cb8418b",
"status_code": "200",
"success": {
"execution_history": [
{
"rule_execution_id": "b3e27d28-2ad6-3b79-b852-9fc259464189",
"rule_id": "86d1d4d5-7416-49a2-aed1-e695b0120db8",
"rule_execution_timestamp": "1793100479468",
"entity_enabled_status": {
"before": "ENTITY_UNPAUSED",
"after": "ENTITY_PAUSED"
},
"associated_ad_entity": {
"entity_type": "CAMPAIGN",
"entity_value": "5c408c9d-7c6a-3817-8ed5-d479c5848f90"
},
"ad_account_id": "22225ba6-7559-4000-9663-bace8adff5f2"
}
],
"next_page_token": "MTc5MzAyNTk3MzQxMzowNWFiNWJhNC1hYTMzLTM2NzgtYjM5My02YmQyZTgxNjgzMDA="
}
}

Delete an Automated Rule​

This endpoint deletes a specific Automated Rule. The API performs a hard delete, i.e. the delete is permanent and can't be undone.

  • Deleting an unknown or already-deleted ID returns HTTP 404, so a repeat delete isn't idempotent.
  • A managed rule, meaning any seasonal budget rule, can't be deleted. The service returns status_code 400 with "a managed rule cannot be deleted".
  • Deleting a rule does not cancel a plan that is already pending, so that plan still runs after the delete. Plans usually run within about 30 minutes of being created, so a delete only affects a plan when it happens inside that window.

HTTP Request​

DELETE https://adsapi.snapchat.com/v1/adaccounts/{ad_account_id}/smart-rules/{rule_id}

URL Parameters​

ParameterDescription
ad_account_idAd Account ID
rule_idThe ID of the Automated Rule to delete

Example - Delete an Automated Rule​

curl -X DELETE "https://adsapi.snapchat.com/v1/adaccounts/22225ba6-7559-4000-9663-bace8adff5f2/smart-rules/1be199c0-28ce-43dc-ada1-f7f608f70d2f" \
-H "Authorization: Bearer meowmeowmeow"

The above command returns JSON structured like this:

{
"request_status": "SUCCESS",
"request_id": "ef7009ab-0d9e-4566-bf45-b35127ee80d2",
"status_code": "200",
"rule_id": "1be199c0-28ce-43dc-ada1-f7f608f70d2f"
}
Was this page helpful?
Yes
No