📘
URL: POST /api/v1/recommendations/list

Request Parameters

Parameter	Notes	Type	Required	Possible Values
advertiserId	ID of advertiser to fetch recommendations for	integer	Y	valid advertiser ID
filter[outcome]	Filter by business outcome the recommendation is trying to improve: improve_performance: improve performance improve_engagement: improve engagement maximize_reach_and_awareness: maximize reach and awareness If not specified, recommendations for all outcomes are returned.	Array<string>	N	improve_performance improve_engagement maximize_reach_and_awareness
filter[recommendationIds]	Filter by specific recommendation IDs. Use this to request only particular recommendations. Max size: 20.	Array<string>	N
filter[recommendationType]	Filter by type of change suggested: budget_reallocation: proposed reallocation of budgets across entities targeting: proposed changes to targeting (audiences, keywords, contextual) schedule: proposed changes to an entity's schedule bid: proposed changes to ad group's bid If not specified, recommendations of all types are returned.	Array<string>	N	budget_reallocation targeting schedule bid
filter[entities]	Filter by specific entities (campaigns or ad groups). Each entity is defined by its ID and type. Max size: 20. *The entities objects are detailed here*	Array<object>	N
filter[recommendationStatus]	Use this filter to retrieve recommendations by status, and constrain results by a date range. If omitted, API returns only active recommendations (default behavior). The values: active: Recommendation is currently actionable and has not been acted upon accepted: Recommendation was accepted by the user rejected: Recommendation was rejected by the user expired: Recommendation expired without being acted upon (system-driven) The filter[recommendationStatus] objects are detailed here	object	N	active accepted rejected expired
viewMode	Controls how much detail is returned for each recommendation: SUMMARY: summary view. Fields returned: recommendationId outcome recommendationType status entity proposal DETAILED: detailed view. Fields returned: recommendationId outcome recommendationType status createdAt entity expectedImpact proposal action Default: summary	string	N	summary (default) detailed

entities Objects

Parameters	Notes	Type	Required	Possible Values
id	ID of the entity	integer	Y	Unique ID value
type	Type of entity the ID refers to	string	Y	campaign, ad_group

filter[recommendationStatus] Objects

Parameters	Notes	Type	Required	Possible Values
status	List of recommendation status to filter on. Use this to include recommendations that were accepted, rejected, expired or active. Must contain at only 1 value.	Array[string]	Y	accepted rejected expired active
dateTimeRange	Restricts results to a date range based on the recommendation’s action/expiry timestamp *Note:* Required field when status includes any of accepted, rejected, expired and optional when status is only active	object	Conditional

dateTimeRange Objects

Parameters	Notes	Type	Required	Possible Values
startDate	Start timestamp (inclusive). Recommendations on or after this time are included.	timestamp	Y	ISO-8601 format (e.g. 2025-07-18T08:00:00Z)
endDate	End timestamp (inclusive). Recommendations actioned on or before this time are included. Must be: • not after the current time • not before dateTimeRange.startDate	timestamp	Y	ISO-8601 format (e.g. 2025-07-18T08:00:00Z)

Headers

Header Name	Description	Required	Values
Authorization	The token will provide you the access to the API. It is same for all advertisers you access through the API.	Y	Please utilize the generated `auth_token` shared with you at the time of partner onboarding from the Getting Started Guide
Content-Type	Format of the message body	Y	application/json
WM_CONSUMER.ID	Unique ID for consumer. We will provide you the consumer ID to access the API. It is same for all advertisers you access through the API.	Y	Please use the generated `ConsumerId` shared with you at the time of partner onboarding. Refer to the Getting Started Guide for more information
WM_SEC.AUTH_SIGNATURE	Signature for authentication	Y	Use the signature generator code from Getting Started Guide to generate this value
WM_SEC.KEY_VERSION	Key version. We will provide you with the KEY VERSION to access the API. It is same for all advertisers you access through the API.	Y	1
WM_CONSUMER.intimestamp	Timestamp for which the auth signature is generated. Use Unix epoch format for the timestamp.	Y	Use the signature generator code from Getting Started Guide to generate this value

👉
Rules/Constraints/Validations:

If no filters are passed, the API returns only active recommendations
filter[recommendationStatus].dateTimeRange rules
- If status contains only active:
  - dateTimeRange is optional
  - If omitted, API returns all active recommendations for the advertiser (subject to other filters)
- If status contains any of accepted, rejected, or expired:
  - dateTimeRange is required
  - The date range (endDate - startDate) must be ≤ 30 days.
- Date range validation
  - startDate must be \<= endDate
  - Maximum allowed range is 30 days
    - Requests exceeding this will be rejected with a validation error
- dateTimeRange does not filter by when the recommendation was created - it filters by when it was accepted/rejected or expired.

Sample Request - Fetch summary of all active recommendations in an advertiser account. (viewMode = summary)

curl -X POST \ 'https://developer.api.us.stg.walmart.com/api-proxy/service/display/api/v1/api/v1/recommendations/list' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer <auth_token>' \ --header 'WM_SEC.AUTH_SIGNATURE: **************' \ --header 'WM_SEC.KEY_VERSION: 1' \ --header 'WM_CONSUMER.ID: adfwe-v23-faasd2r-afs-asdfqeff' \ --header 'WM_CONSUMER.intimestamp: 1565309779' \ --data '{ "advertiserId": 12345, "viewMode": "summary"
}'

Sample Request - Fetch summary of all active targeting (keyword) recommendations in an advertiser account. (viewMode = summary)

curl -X POST \ 'https://developer.api.us.stg.walmart.com/api-proxy/service/display/api/v1/api/v1/recommendations/list' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer <auth_token>' \ --header 'WM_SEC.AUTH_SIGNATURE: **************' \ --header 'WM_SEC.KEY_VERSION: 1' \ --header 'WM_CONSUMER.ID: adfwe-v23-faasd2r-afs-asdfqeff' \ --header 'WM_CONSUMER.intimestamp: 1565309779' \ --data '{ "advertiserId": 12345, "filter[recommendationType]": [ "targeting" ], "viewMode": "summary"
}'

Sample Request - Fetch summary of all active targeting (contextual) recommendations in an advertiser account. (viewMode = summary)

curl -X POST \ 'https://developer.api.us.stg.walmart.com/api-proxy/service/display/api/v1/api/v1/recommendations/list' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer <auth_token>' \ --header 'WM_SEC.AUTH_SIGNATURE: **************' \ --header 'WM_SEC.KEY_VERSION: 1' \ --header 'WM_CONSUMER.ID: adfwe-v23-faasd2r-afs-asdfqeff' \ --header 'WM_CONSUMER.intimestamp: 1565309779' \ --data '{ "advertiserId": 12345, "filter[recommendationType]": [ "targeting" ], "viewMode": "summary"
}'

Sample Request - Fetch summary of all active targeting (behavioral) recommendations for a specific ad group. (viewMode = summary)

curl -X POST \ 'https://developer.api.us.stg.walmart.com/api-proxy/service/display/api/v1/api/v1/recommendations/list' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer <auth_token>' \ --header 'WM_SEC.AUTH_SIGNATURE: **************' \ --header 'WM_SEC.KEY_VERSION: 1' \ --header 'WM_CONSUMER.ID: adfwe-v23-faasd2r-afs-asdfqeff' \ --header 'WM_CONSUMER.intimestamp: 1565309779' \ --data '{ "advertiserId": 12345, "filter[recommendationType]": [ "targeting" ], "filter[entities]": [ { "id": 1898, "type": "ad_group" } ], "viewMode": "summary"
}'

Sample Request - Fetch summary of all active budget reallocation recommendations in an advertiser account. (viewMode = summary)

curl -X POST \ 'https://developer.api.us.stg.walmart.com/api-proxy/service/display/api/v1/api/v1/recommendations/list' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer <auth_token>' \ --header 'WM_SEC.AUTH_SIGNATURE: **************' \ --header 'WM_SEC.KEY_VERSION: 1' \ --header 'WM_CONSUMER.ID: adfwe-v23-faasd2r-afs-asdfqeff' \ --header 'WM_CONSUMER.intimestamp: 1565309779' \ --data '{ "advertiserId": 12345, "filter[recommendationType]":["budget_reallocation" ] }'

Sample Request - Fetch summary of all active schedule recommendations in an advertiser account. (viewMode = summary)

curl -X POST \ 'https://developer.api.us.stg.walmart.com/api-proxy/service/display/api/v1/api/v1/recommendations/list' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer <auth_token>' \ --header 'WM_SEC.AUTH_SIGNATURE: **************' \ --header 'WM_SEC.KEY_VERSION: 1' \ --header 'WM_CONSUMER.ID: adfwe-v23-faasd2r-afs-asdfqeff' \ --header 'WM_CONSUMER.intimestamp: 1565309779' \ --data '{ "advertiserId": 12345, "filter[recommendationType]":["schedule" ] }'

Sample Request - Fetch details of all active recommendations in an advertiser account (viewMode = detailed)

curl -X POST \ 'https://developer.api.us.stg.walmart.com/api-proxy/service/display/api/v1/api/v1/recommendations/list' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer <auth_token>' \ --header 'WM_SEC.AUTH_SIGNATURE: **************' \ --header 'WM_SEC.KEY_VERSION: 1' \ --header 'WM_CONSUMER.ID: adfwe-v23-faasd2r-afs-asdfqeff' \ --header 'WM_CONSUMER.intimestamp: 1565309779' \ --data '{ "advertiserId": 12345, "viewMode": "detailed" }'

Sample Request - Fetch all recommendations that were accepted in an advertiser account between a specific date range (viewMode = detailed)

curl -X POST \ 'https://developer.api.us.stg.walmart.com/api-proxy/service/display/api/v1/api/v1/recommendations/list' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer <auth_token>' \ --header 'WM_SEC.AUTH_SIGNATURE: **************' \ --header 'WM_SEC.KEY_VERSION: 1' \ --header 'WM_CONSUMER.ID: adfwe-v23-faasd2r-afs-asdfqeff' \ --header 'WM_CONSUMER.intimestamp: 1565309779' \ --data '{ "advertiserId": 12345, "filter[recommendationStatus]": { "status": [ "accepted" ], "dateTimeRange": { "startDate": "2026-01-01T00:00:00Z", "endDate": "2026-01-20T00:00:00Z" }, "viewMode": "detailed" }
}'

Sample Request - Fetch all recommendations that were expired in an advertiser account between a specific date range (viewMode = detailed)

curl -X POST \ 'https://developer.api.us.stg.walmart.com/api-proxy/service/display/api/v1/api/v1/recommendations/list' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer <auth_token>' \ --header 'WM_SEC.AUTH_SIGNATURE: **************' \ --header 'WM_SEC.KEY_VERSION: 1' \ --header 'WM_CONSUMER.ID: adfwe-v23-faasd2r-afs-asdfqeff' \ --header 'WM_CONSUMER.intimestamp: 1565309779' \ --data '{ "advertiserId": 12345, "filter[recommendationStatus]": { "status": [ "expired" ], "dateTimeRange": { "startDate": "2026-01-01T00:00:00Z", "endDate": "2026-01-20T00:00:00Z" }, "viewMode": "detailed" }
}'

Sample Request - Fetch summary of all active bid recommendations in an advertiser account. (viewMode = summary)

curl -X POST \ 'https://developer.api.us.stg.walmart.com/api-proxy/service/display/api/v1/api/v1/recommendations/list' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer <auth_token>' \ --header 'WM_SEC.AUTH_SIGNATURE: **************' \ --header 'WM_SEC.KEY_VERSION: 1' \ --header 'WM_CONSUMER.ID: adfwe-v23-faasd2r-afs-asdfqeff' \ --header 'WM_CONSUMER.intimestamp: 1565309779' \ --data '{ "advertiserId": 12345, "filter[recommendationType]":["BID" ] }'

Sample Request - Failure scenario (invalid outcome)

curl -X POST \ 'https://developer.api.us.stg.walmart.com/api-proxy/service/display/api/v1/api/v1/recommendations/list' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer <auth_token>' \ --header 'WM_SEC.AUTH_SIGNATURE: **************' \ --header 'WM_SEC.KEY_VERSION: 1' \ --header 'WM_CONSUMER.ID: adfwe-v23-faasd2r-afs-asdfqeff' \ --header 'WM_CONSUMER.intimestamp: 1565309779' \ --data '{ "advertiserId": 12345, "filter[outcome]": "improve_performances"
}'

Response

Element	Description	Nullable?	Type
totalResults	Total number of recommendations returned for the request criteria	N	integer
recommendations	List of recommendation objects matching the request criteria	Y	Array <object>

recommendations object details

Element	Description	Nullable?	Type	Possible values
recommendationId	Unique ID of the recommendation	N	string
outcome	Business outcome this recommendation is designed to improve	N	string	IMPROVE_PERFORMANCE, IMPROVE_ENGAGEMENT, MAXIMIZE_REACH_AND_AWARENESS
recommendationType	Type of change being recommended	N	string	BUDGET_REALLOCATION, TARGETING, SCHEDULE, BID
status	status of recommendation Current status of the recommendation: ACTIVE: recommendation is valid and not yet applied. ACCEPTED: recommendation has been applied REJECTED: recommendation has been rejected/dismissed EXPIRED: recommendation has been expired *Note:* returned only when available and viewMode = DETAILED" for both expectedImpact and action fields	N	string	ACTIVE, ACCEPTED, REJECTED, EXPIRED
entity	Entity (campaign or ad group) for which the recommendation is suggested The entity objects are detailed here	N	object	See entity sub-table below
expectedImpact	Metrics describing the expected impact if the recommendation is applied Note: Returned only when available and viewMode = DETAILED The expectedImpact objects are detailed here	Y	Array <object>	See expectedImpact sub-table below
proposal	Details of the proposed change to apply if the recommendation is accepted. The proposal objects are detailed here	N	object	See proposal sub-table below
action	Details of the user action taken on this recommendation (if any)	Y	Array <object>	See action sub-table below
trigger	Root object describing the recommendation trigger	N	object	See trigger sub-table below

entity Objects

Element	Description	Nullable?	Type	Possible values
id	ID of the entity	N	integer
type	Type of the entity	N	string	CAMPAIGN, AD_GROUP
name	Name of the entity.	N	string
parent	Object with details of the parent entity.	Y	object

trigger object details

Element	Description	Nullable?	Type	Possible values
triggerType	Describes the primary signal or event that caused the recommendation to be generated, i.e., the “why” behind the recommendation.	Y	string	UNDER_DELIVERY

parent object details

Element	Description	Nullable?	Type	Possible values
id	ID of the parent entity, i.e. campaign id for the adgroup	N	integer
type	Type of the parent entity. For entity.type = ADGROUP, parent.type = CAMPAIGN	N	string	CAMPAIGN
name	Name of the parent entity.	N	string

expectedImpact Objects

Metrics measuring the expected impact if the recommendation is applied.

Element	Description	Nullable?	Type	Possible values
metric	Type of metric being reported	N	integer	IMPRESSIONS, CLICKS, SALES
current	Current value of the metric without applying the recommendation.	N	double
predicted	Predicted value of the metric after applying the recommendation.	N	double
uplift	Difference between predicted and current, representing uplift based on forecasted impressions/sales/clicks	N	double
unit	Unit for the metric values above. (Examples in responses include "ABSOLUTE_VALUE")	N	string	ABSOLUTE_VALUE

proposal Objects

Contains the recommended changes for a recommendation. Its shape depends on recommendationType.
It contains exactly one of the following objects based on recommendationType:

If recommendationType = TARGETING, proposal.targeting MUST be present
If recommendationType = BUDGET_REALLOCATION, proposal.budgetReallocation MUST be present
If recommendationType = SCHEDULE, proposal.schedule MUST be present
If recommendationType = BID, proposal.bid MUST be present

Element	Description	Nullable?	Type
schedule	proposal payload to propose changes to an entity's schedule (only applicable if recommendationType = SCHEDULE)	Y	object
budgetReallocation	Proposal payload for reallocating budgets across entities(only applicable if recommendationType = BUDGET_REALLOCATION)	Y	object
targeting	Proposal payload for targeting recommendations (only applicable if recommendationType = TARGETING)	Y	object
bid	Proposal payload for bid recommendations. (only applicable when recommendationType = BID)	Y	object

targeting object details

Element	Description	Nullable?	Type	Possible values
inclusions	List of recommended targeting additions/changes (inclusive targeting). *The inclusions objects are detailed here*	Y	Array <object>
exclusions	List of recommended targeting removals/changes (exclusive targeting). The exclusions objects are detailed here	Y	Array <object>
subType	Targeting subtype describing what kind of targeting values are included/excluded	Y	string	BEHAVIORAL_TARGETING, CONTEXTUAL_TARGETING, KEYWORD_TARGETING

schedule object details

Element	Description	Nullable?	Type	Possible values
currentStartDateTime	current start datetime of schedule Recommendation	N	string	Timestamp in ISO8601 format normalized to ET
currentEndDateTime	current end datetime of schedule Recommendation	Y	string	Timestamp in ISO8601 format normalized to ET
recommendedStartDateTime	recommended start datetime of schedule Recommendation	N	string	Timestamp in ISO8601 format normalized to ET
recommendedEndDateTime	recommended end datetime of schedule Recommendation	Y	string	Timestamp in ISO8601 format normalized to ET

budgetReallocation object details

Element	Description	Nullable?	Type	Possible values
reallocations	List of entities with current vs recommended budget values after reallocation	N	Array<object>

bid object details

Element	Description	Nullable?	Type	Possible values
bidType	The type of the bid	N	string	MAX_BID
currentValue	The current value of the bid	N	Double
recommendedValue	The recommended value of the bid	Y	Double

reallocations object details

Element	Description	Nullable?	Type	Possible values
entityType	Type of the entity for which budget reallocation is recommended	Y	string	AD_GROUP
entityId	ID of the entity for which budget reallocation is recommended	Y	string
entityName	Name of the entity for which budget reallocation is recommended	Y	string
budgetType	Budget dimension being reallocated	Y	string	TOTAL, DAILY
currentValue	Current value for budget	Y	Double
recommendedValue	Recommended value of budget	Y	Double

inclusions/exclusions Objects

Specify what targeting to add or remove for TARGETING recommendations

Element	Description	Nullable?	Type	Possible values
action	Action to be taken on this targeting set	N	string	ADD, REMOVE
values	List of targeting values affected by the action The values objects are detailed here	N	Array <object>

action object details

Element	Description	Nullable?	Type	Possible values
state	Type of action taken on the recommendation.	N	string	ACCEPTED, REJECTED
actedAt	Timestamp when the action was taken	N	timestamp	Timestamp in ISO8601 format normalized to ET

values Objects

Element	Description	Nullable?	Type	Possible values
type	Type discriminator for targeting value	N	string	BEHAVIORAL, CONTEXTUAL, KEYWORD
text	Keyword text value. (applicable only for type KEYWORD, Negative keywords are sent as part of exclusions)	Y	string
matchType	Match type for keyword (applicable only for type KEYWORD)	Y	string	BROAD, EXACT
id	id of contextual target or audience (applicable only for type BEHAVIORAL or CONTEXTUAL)	Y	integer
name	name of contextual target or audience (applicable only for type BEHAVIORAL or CONTEXTUAL)	Y	string

👉
Rules/Constraints/Validations:

action object is returned only for recommendations that have been accepted or rejected.
Each recommendation is valid for approximately 1 day if not acted upon. A new recommendationId may be generated daily for the same ad group; older IDs expire if no action was taken.
Recommendations may overlap (for example, a campaign-level change may supersede an ad group-level change). When you act on one recommendation, any overlapping recommendations may be automatically marked invalid and removed from the active set.
Proposal object contains exactly one of the following objects based on recommendationType:
If recommendationType = TARGETING, proposal.targeting MUST be present
If recommendationType = BUDGET_REALLOCATION, proposal.budgetReallocation MUST be present
If recommendationType = SCHEDULE, proposal.schedule MUST be present
For Keyword recommendations (proposal.targeting.subType="KEYWORD_TARGETING")
Negative keyword recommendations, if any, are sent as part of exclusions
For Schedule recommendations (proposal.schedule)
If the recommendation includes a start time change, both currentStartDateTime and recommendedStartDateTime are returned
If the start time is not relevant to the recommendation, both currentStartDateTime and recommendedStartDateTimeTime fields are omitted.
If the recommendation includes an end time change, both currentStartDateTime and recommendedStartDateTime are returned
If the end time is not relevant to the recommendation, both currentStartDateTime and recommendedStartDateTime are omitted.

Sample Response - Fetch summary of all active recommendations in an advertiser account. (viewMode = summary)

{ "totalResults": 1, "recommendations": [ { "id": "c4-targeting", "outcome": "MAXIMIZE_REACH_AND_AWARENESS", "recommendationType": "TARGETING", "trigger": { "triggerType": "UNDER_DELIVERY" }, "status": "ACTIVE", "entity": { "id": 189, "type": "AD_GROUP", "name": "Test_AdGroup_1", "parent": { "id": 1314591, "type": "CAMPAIGN", "name": "Test_Campaign_1" } }, "proposal": { "targeting": { "subType": "KEYWORD_TARGETING", "inclusions": [ { "action": "add", "values": [ { "type": "KEYWORD", "text": "wet wipe", "matchType": "exact" } ] } ], "exclusions": [] } } } ]
}

Sample Response - Fetch summary of all active targeting (keyword) recommendations in an advertiser account. (viewMode = summary)

{ "totalResults": 1, "recommendations": [ { "recommendationId": "a52a0748-d9a5targeting", "outcome": "MAXIMIZE_REACH_AND_AWARENESS", "recommendationType": "TARGETING", "trigger": { "triggerType": "UNDER_DELIVERY" }, "status": "ACTIVE", "entity": { "id": 1925, "type": "AD_GROUP", "name": "KEYWORD_TARGETING_ADGROUP_1", "parent": { "id": 1334, "type": "CAMPAIGN", "name": "Test_Campaign" } }, "proposal": { "targeting": { "subType": "KEYWORD_TARGETING", "inclusions": [ { "action": "add", "values": [ { "type": "KEYWORD", "text": "drinks", "matchType": "exact" }, { "type": "KEYWORD", "text": "coke", "matchType": "broad" } ] } ], "exclusions": [] } } } ]
}

Sample Response - Fetch summary of all active targeting (contextual) recommendations in an advertiser account. (viewMode = summary)

{ "totalResults": 1, "recommendations": [ { "recommendationId": "a52a0_a5targeting", "outcome": "MAXIMIZE_REACH_AND_AWARENESS", "recommendationType": "TARGETING", "trigger": { "triggerType": "UNDER_DELIVERY" }, "status": "ACTIVE", "entity": { "id": 1925, "type": "AD_GROUP", "name": "CONTEXTUAL_TARGETING_ADGROUP_1", "parent": { "id": 1334, "type": "CAMPAIGN", "name": "Test_Campaign_2" } }, "proposal": { "targeting": { "subType": "CONTEXTUAL_TARGETING", "inclusions": [ { "action": "add", "values": [ { "type": "CONTEXTUAL", "id": 205, "name": "clothing, shoes & accessories|full-body garments & suits" } ] } ], "exclusions": [] } } } ]
}

Sample Response - Fetch summary of all active targeting (behavioral) recommendations for a specific ad group. (viewMode = summary)

{ "totalResults": 1, "recommendations": [ { "recommendationId": "a5-d9a5targeting", "outcome": "MAXIMIZE_REACH_AND_AWARENESS", "recommendationType": "TARGETING", "trigger": { "triggerType": "UNDER_DELIVERY" }, "status": "ACTIVE", "entity": { "id": 1898, "type": "AD_GROUP", "name": "BEHAVIORAL_TARGETING_ADGROUP_1", "parent": { "id": 1334, "type": "CAMPAIGN", "name": "Test_Campaign_3" } }, "proposal": { "targeting": { "subType": "BEHAVIOURAL_TARGETING", "inclusions": [ { "action": "add", "values": [ { "type": "BEHAVIOURAL", "id": 100, "name": "parent's choice" } ] } ], "exclusions": [] } } } ]
}

Sample Response - Fetch summary of all active budget reallocation recommendations in an advertiser account. (viewMode = summary)

{ "totalResults": 1, "recommendations": [ { "recommendationId": "ddc7ef56-f997", "outcome": "MAXIMIZE_REACH_AND_AWARENESS", "recommendationType": "BUDGET_REALLOCATION", "trigger": { "triggerType": "UNDER_DELIVERY" }, "status": "ACTIVE", "entity": { "id": 131, "type": "CAMPAIGN", "name": "Test_Campaign_4" }, "expectedImpact": [ { "metric": "IMPRESSIONS", "current": 2686.0, "predicted": 25365.0, "uplift": 22679.0, "unit": "ABSOLUTE_VALUE" } ], "proposal": { "budgetReallocation": { "reallocations": [ { "entityType": "AD_GROUP", "entityId": 1898246, "entityName": "Test_Adgroup_1", "budgetType": "TOTAL", "currentValue": 1000.0, "recommendedValue": 900.0 }, { "entityType": "AD_GROUP", "entityId": 1898, "entityName": "Test_Adgroup_2", "budgetType": "TOTAL", "currentValue": 300.0, "recommendedValue": 400.0 } ] } } } ]
}

Sample Response - Fetch summary of all active schedule recommendations in an advertiser account. (viewMode = summary)

{ "totalResults": 1, "recommendations": [ { "recommendationId": "ddc7ef56-f997", "outcome": "MAXIMIZE_REACH_AND_AWARENESS", "recommendationType": "BUDGET_REALLOCATION", "trigger": { "triggerType": "UNDER_DELIVERY" }, "status": "ACTIVE", "entity": { "id": 131, "type": "CAMPAIGN", "name": "Test_Campaign_5" }, "expectedImpact": [ { "metric": "IMPRESSIONS", "current": 2686.0, "predicted": 25365.0, "uplift": 22679.0, "unit": "ABSOLUTE_VALUE" } ], "proposal": { "scheduleRecommendation": { "currentStartDateTime": "2026-01-29T00:00:00-05:00", "currentEndDateTime": "2026-02-12T00:00:00-05:00", "recommendedStartDateTime": "2026-01-29T00:00:00-05:00", "recommendedEndDateTime": "2026-02-22T00:00:00-05:00" } } } ]
}

Sample Response - Fetch details of all active recommendations in an advertiser account (viewMode = detailed)

{ "totalResults": 1, "recommendations": [ { "recommendationId": "b52a0748-d9a5targeting", "outcome": "MAXIMIZE_REACH_AND_AWARENESS", "recommendationType": "TARGETING", "trigger": { "triggerType": "UNDER_DELIVERY" }, "status": "ACTIVE", "entity": { "id": 1925, "type": "AD_GROUP", "name": "Test_Adgroup_6", "parent": { "id": 1334, "type": "CAMPAIGN", "name": "Test_Campaign_6" } }, "expectedImpact": [ { "metric": "IMPRESSIONS", "current": 2686.0, "predicted": 25365.0, "uplift": 22679.0, "unit": "ABSOLUTE_VALUE" } ], "proposal": { "targeting": { "subType": "KEYWORD_TARGETING", "inclusions": [ { "action": "add", "values": [ { "type": "KEYWORD", "text": "drinks", "matchType": "exact" }, { "type": "KEYWORD", "text": "coke", "matchType": "broad" } ] } ], "exclusions": [] } } } ]
}

Sample Response - Fetch all recommendations that were accepted in an advertiser account between a specific date range (viewMode = detailed)

 { "totalResults": 1, "recommendations": [ { "recommendationId": "b52a0748-d9a5targeting", "outcome": "MAXIMIZE_REACH_AND_AWARENESS", "recommendationType": "TARGETING", "trigger": { "triggerType": "UNDER_DELIVERY" }, "status": "ACCEPTED", "entity": { "id": 1925, "type": "AD_GROUP", "name": "Test_Adgroup_7", "parent": { "id": 1334, "type": "CAMPAIGN", "name": "Test_Campaign_7" } }, "expectedImpact": [ { "metric": "IMPRESSIONS", "current": 2686.0, "predicted": 25365.0, "uplift": 22679.0, "unit": "ABSOLUTE_VALUE" } ], "proposal": { "targeting": { "subType": "BEHAVIOURAL_TARGETING", "inclusions": [ { "action": "add", "values": [ { "type": "BEHAVIOURAL", "id": 100, "name": "parent's choice" } ] } ], "exclusions": [] } }, "action": [ { "state": "ACCEPTED", "actedAt": "2026-01-29T00:00:00-05:00" } ] } ]
}

Sample Response - Fetch all recommendations that were expired in an advertiser account between a specific date range (viewMode = detailed)

{ "totalResults": 1, "recommendations": [ { "recommendationId": "b52a0748-d9a5targeting", "outcome": "MAXIMIZE_REACH_AND_AWARENESS", "recommendationType": "TARGETING", "trigger": { "triggerType": "UNDER_DELIVERY" }, "status": "EXPIRED", "entity": { "id": 1925, "type": "AD_GROUP", "name": "Test_Adgroup_7", "parent": { "id": 1334, "type": "CAMPAIGN", "name": "Test_Campaign_7" } }, "expectedImpact": [ { "metric": "IMPRESSIONS", "current": 2686.0, "predicted": 25365.0, "uplift": 22679.0, "unit": "ABSOLUTE_VALUE" } ], "proposal": { "targeting": { "subType": "BEHAVIOURAL_TARGETING", "inclusions": [ { "action": "add", "values": [ { "type": "BEHAVIOURAL", "id": 100, "name": "parent's choice" } ] } ], "exclusions": [] } } } ]
}

Sample Response - Fetch summary of all active bid recommendations in an advertiser account. (viewMode = summary)

{ "totalResults": 1, "recommendations": [ { "recommendationId": "ddc7ef56-f997", "outcome": "MAXIMIZE_REACH_AND_AWARENESS", "recommendationType": "BID", "trigger": { "triggerType": "UNDER_DELIVERY" }, "status": "ACTIVE",             "entity": { "id": 1925, "type": "AD_GROUP", "name": "Test_Adgroup_7", "parent": { "id": 1334, "type": "CAMPAIGN", "name": "Test_Campaign_7" } },, "proposal": { "bid": { "bidType": "MAX_BID", "currentValue": 8.4 "recommendedValue": 10.4 } } } ]
}

Sample Response - Failure scenario (invalid outcome)

{ "code": "failure", "details": [ "string" ]
}