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
| Attribute | Description | Required | Possible Values |
|---|---|---|---|
| rule_id | Automated Rule ID | Read-only | |
| rule_name | Automated 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_id | Ad Account ID, always taken from the request path | Read-only | |
| rule_type | Type of the Automated Rule | R | See Automated Rule Enum Values |
| ad_entities | The entities the rule acts on | R | See ad_entities |
| excluded_entity_values | IDs of entities excluded from the rule | Read-only | |
| condition | Array 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. | R | See condition |
| action | The action to run when the conditions are met | R | See action |
| action_frequency | How often the action can run | R | See Automated Rule Enum Values |
| rule_frequency | When the rule is evaluated | R (not sent for a single TIME condition with value_time) | See rule_frequency |
| rule_limits | Limits for bid and budget increase rules | O | See rule_limits |
| notification | Email notification settings | O | See notification |
| created_by | Email 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 ignored | Read-only | |
| rule_status | Status of the Automated Rule | Read-only | See Automated Rule Enum Values |
| associated_ad_entity | The entity the rule is associated with | Read-only | See Automated Rule Enum Values |
| created_time_stamp | Creation time in epoch milliseconds, returned as a string | Read-only | "1793129614503" |
ad_entities
| Attribute | Description | Required | Possible Values |
|---|---|---|---|
| entity_type | Type of the entities the rule acts on | R | CAMPAIGN, AD_SET, AD (only works with the CHANGE_DELIVERY_STATUS action) |
| all_active | If true, the rule applies to all active entities of entity_type. Use either all_active or entity_values, not both | O | true |
| entity_values.values | Array 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
| Attribute | Description | Required | Possible Values |
|---|---|---|---|
| condition_type | The metric the condition checks | R | See Automated Rule Enum Values |
| operator | Comparison operator | R | See Automated Rule Enum Values |
| value_number.value | Threshold value for SPENT, RESULT and COST_PER_RESULT conditions. Monetary thresholds use micro-currency. Returned as a string in responses | R (not used with TIME) | 50000000 |
| value_number.condition_time_horizon | Time period the metric is measured over. Not used with TIME | O | See Automated Rule Enum Values |
| value_time.time_zone | IANA time zone for the TIME condition. Optional: set value_time instead of value_number for a one-time TIME condition | R when value_time is set | America/Los_Angeles |
| value_time.value | Time threshold in epoch milliseconds | R when value_time is set | 1793129614503 |
action
| Attribute | Description | Required | Possible Values |
|---|---|---|---|
| action_type | The action to run | R | See Automated Rule Enum Values |
| value_string.value | Target value for CHANGE_DELIVERY_STATUS | O | ENTITY_PAUSED, ENTITY_UNPAUSED |
| value_number.amount | Adjustment 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. | O | 10 |
| value_number.unit | Unit for value_number.amount | O | See Automated Rule Enum Values |
rule_frequency
Set either daily_fixed or daily_custom, not both.
| Attribute | Description | Required | Possible Values |
|---|---|---|---|
| daily_fixed.hour | Hour of the day the rule is evaluated (0-23) | R | 9 |
| daily_fixed.minute | Minute of the hour the rule is evaluated | O | 0 (default) |
| daily_fixed.time_zone | IANA time zone used for hour and minute | R | America/Los_Angeles |
| daily_custom.items | Array of 1 to 7 schedules, one per day of the week. The same day cannot appear twice | R | |
| daily_custom.items[].day | Day of the week the rule is evaluated | R | SUNDAY, MONDAY, TUESDAY, WEDNESDAY, THURSDAY, FRIDAY, SATURDAY |
| daily_custom.items[].hour | Hour of the day the rule is evaluated (0-23) | R | 9 |
| daily_custom.items[].minute | Minute of the hour the rule is evaluated (0-59) | O | 0 (default) |
| daily_custom.items[].time_zone | IANA time zone used for hour and minute | R | America/Los_Angeles |
rule_limits
Set exactly one of bid, daily_budget or lifetime_budget, matching the action:
CHANGE_BIDusesbid.CHANGE_BUDGET_DAILYusesdaily_budget.CHANGE_BUDGET_LIFETIMEuseslifetime_budget.
Other actions ignore rule_limits. Seasonal budget rules (SEASONAL_BUDGET_ADJUSTMENT) must not send rule_limits.
| Attribute | Description | Required | Possible Values |
|---|---|---|---|
| bid.maximum_bid_cap | Maximum bid allowed for bid increase rules (greater than 0) | O | |
| bid.minimum_bid_floor | Minimum bid allowed for bid increase rules (0 or more) | O | |
| daily_budget.maximum_daily_budget_cap | Maximum daily budget allowed for daily budget increase rules (greater than 0) | O | |
| daily_budget.minimum_daily_budget_floor | Minimum daily budget allowed for daily budget increase rules (0 or more) | O | |
| lifetime_budget.maximum_lifetime_budget_cap | Maximum lifetime budget allowed for lifetime budget increase rules (greater than 0) | O | |
| lifetime_budget.minimum_lifetime_budget_floor | Minimum lifetime budget allowed for lifetime budget increase rules (0 or more) | O |
notification
| Attribute | Description | Required | Possible Values |
|---|---|---|---|
| enabled | Whether email notifications are sent | O | true, false (default) |
| email_ids | Email 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 error | O | ["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_code | Meaning |
|---|---|
| 400 | Validation failure |
| 404 | Unknown rule |
| 409 | Conflict, on create, update and when turning a rule ON. "A conflicting active rule already exists for the same entity and action type." |
| 500 | Any 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
| Parameter | Description |
|---|---|
| ad_account_id | Ad 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
| Parameter | Description |
|---|---|
| ad_account_id | Ad Account ID |
| rule_id | Automated 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
| Attribute | Possible Values |
|---|---|
| rule_type | BID_ADJUSTMENT, BUDGET_ADJUSTMENT, BID_STRATEGY_ADJUSTMENT, SEASONAL_BID_ADJUSTMENT, SEASONAL_BUDGET_ADJUSTMENT, SCHEDULED_DELIVERY |
| rule_status | ON, OFF, EXPIRED |
| ad_entities.entity_type | CAMPAIGN, AD_SET, AD |
| associated_ad_entity.entity_type | CAMPAIGN, AD_SQUAD, AD |
| condition.condition_type | TIME, SPENT, RESULT, COST_PER_RESULT |
| condition.operator | GREATER_THAN, LESS_THAN, EQUALS |
| value_number.condition_time_horizon | HORIZON_ALL, HORIZON_TODAY, HORIZON_YESTERDAY, HORIZON_7D, HORIZON_14D |
| action.action_type | CHANGE_BID, CHANGE_BUDGET_DAILY, CHANGE_BUDGET_LIFETIME, CHANGE_BID_STRATEGY, CHANGE_DELIVERY_STATUS |
| action.value_string.value | ENTITY_PAUSED, ENTITY_UNPAUSED |
| action.value_number.unit | ABSOLUTE, PERCENTAGE |
| action_frequency | ONCE_DAILY, ONCE_LIFETIME (TIME condition with value_time) |
| entity_enabled_status.before/after | ENTITY_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
| Parameter | Description |
|---|---|
| ad_account_id | Ad Account ID |
| rule_id | Automated 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
| Parameter | Description |
|---|---|
| ad_account_id | Ad Account ID |
| page_size | Optional, the number of rules to return per page |
| page_token | Optional, the next_page_token from the previous response |
| rule_types | Optional, 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
| Parameter | Description |
|---|---|
| ad_account_id | Ad Account ID |
| rule_id | Optional, only return executions of this Automated Rule |
| start_timestamp | Optional, start of the time range in epoch milliseconds |
| end_timestamp | Optional, end of the time range in epoch milliseconds |
| page_size | Optional, the number of executions to return per page |
| page_token | Optional, 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_code400 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
| Parameter | Description |
|---|---|
| ad_account_id | Ad Account ID |
| rule_id | The 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"
}