Amazon Ads API MCP

{"openapi":"3.0.2","info":{"title":"AmazonAdsAPI - Forecasts (beta)","version":"v1","description":"The Forecasts API offers campaign-level performance, delivery, and spend forecasts currently available on forecasting widgets. This includes campaign flight level forecasts for spend, reach, CPC, CPA, and ROAS. The API provides forecasts both for new orders and existing orders that are spending budget."},"tags":[{"name":"Campaign Forecasts"}],"paths":{"/adsApi/v1/retrieve/campaignForecasts/dsp":{"post":{"tags":["Campaign Forecasts"],"description":"A retrieve by ID read. More performant than query.","operationId":"DSPRetrieveCampaignForecast","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DSPRetrieveCampaignForecastRequest"}}}},"parameters":[{"$ref":"#/components/parameters/AccountIdHeader"},{"$ref":"#/components/parameters/ClientIdHeader"},{"$ref":"#/components/parameters/ManagerAccountIdHeader"}],"responses":{"207":{"description":"DSPRetrieveCampaignForecast 207 response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DSPCampaignForecastMultiStatusResponse"}}}},"400":{"description":"BadRequest 400 response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BadRequestResponseContent"}}}},"401":{"description":"Unauthorized 401 response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnauthorizedResponseContent"}}}},"403":{"description":"Forbidden 403 response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ForbiddenResponseContent"}}}},"404":{"description":"NotFound 404 response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotFoundResponseContent"}}}},"413":{"description":"ContentTooLarge 413 response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContentTooLargeResponseContent"}}}},"429":{"description":"TooManyRequests 429 response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TooManyRequestsResponseContent"}}}},"500":{"description":"InternalServerError 500 response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InternalServerErrorResponseContent"}}}},"502":{"description":"BadGateway 502 response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BadGatewayResponseContent"}}}},"503":{"description":"ServiceUnavailableError 503 response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServiceUnavailableErrorResponseContent"}}}},"504":{"description":"GatewayTimeout 504 response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GatewayTimeoutResponseContent"}}}}}}}},"components":{"schemas":{"BadGatewayResponseContent":{"type":"object","properties":{"message":{"type":"string"},"code":{"type":"string"}},"required":["code","message"]},"BadRequestResponseContent":{"type":"object","properties":{"message":{"type":"string"},"code":{"$ref":"#/components/schemas/ErrorCode"}},"required":["code","message"]},"ContentTooLargeResponseContent":{"type":"object","properties":{"message":{"type":"string"},"code":{"$ref":"#/components/schemas/ErrorCode"}},"required":["code","message"]},"DSPBudget":{"type":"object","properties":{"budgetValue":{"$ref":"#/components/schemas/DSPBudgetValue"}},"required":["budgetValue"]},"DSPBudgetValue":{"oneOf":[{"type":"object","title":"monetaryBudgetValue","properties":{"monetaryBudgetValue":{"$ref":"#/components/schemas/DSPMonetaryBudgetValue"}},"required":["monetaryBudgetValue"]}]},"DSPCampaignForecast":{"type":"object","properties":{"campaignForecastDescription":{"$ref":"#/components/schemas/DSPCampaignForecastDescription"},"creationDateTime":{"type":"string","description":"The creation date of the campaign forecast.","format":"date-time"},"flightForecasts":{"type":"array","items":{"$ref":"#/components/schemas/DSPFlightForecast"},"maxItems":5,"minItems":0,"description":"The forecast results of multiple flights of the campaign."},"availableForecastFlights":{"type":"array","items":{"$ref":"#/components/schemas/DSPForecastFlight"},"maxItems":100,"minItems":0,"description":"The combination of existing flight settings and proposed flight settings based on forecasting."}},"required":["campaignForecastDescription","creationDateTime"]},"DSPCampaignForecastDescription":{"type":"object","description":"The description of which campaign and what features are enabled for a forecast.","properties":{"campaignId":{"type":"string","description":"The unique identifier of the campaign the ad group belongs to."},"flightIds":{"type":"array","items":{"type":"string"},"maxItems":5,"minItems":0,"description":"The unique identifier of the flight."},"replanningSettings":{"$ref":"#/components/schemas/DSPReplanningSettings"},"enabledFeatures":{"$ref":"#/components/schemas/DSPEnabledFeaturesInCampaignForecast"}},"required":["campaignId"]},"DSPCampaignForecastMultiStatusResponse":{"type":"object","properties":{"success":{"type":"array","items":{"$ref":"#/components/schemas/DSPCampaignForecastMultiStatusSuccess"},"maxItems":1,"minItems":0},"error":{"type":"array","items":{"$ref":"#/components/schemas/ErrorsIndex"},"maxItems":1,"minItems":0}}},"DSPCampaignForecastMultiStatusSuccess":{"type":"object","properties":{"index":{"type":"integer","maximum":0,"minimum":0,"format":"int32"},"campaignForecast":{"$ref":"#/components/schemas/DSPCampaignForecast"}},"required":["campaignForecast","index"]},"DSPCurrencyCode":{"type":"string","description":"| CurrencyCode | Description |\n| --- | --- |\n| `AED` | |\n| `AUD` | |\n| `BRL` | |\n| `CAD` | |\n| `CHF` | |\n| `CNY` | |\n| `DKK` | |\n| `EGP` | |\n| `EUR` | |\n| `GBP` | |\n| `INR` | |\n| `JPY` | |\n| `MXN` | |\n| `MXP` | |\n| `NGN` | |\n| `NOK` | |\n| `PLN` | |\n| `NZD` | |\n| `SAR` | |\n| `SEK` | |\n| `SGD` | |\n| `TRY` | |\n| `USD` | |\n| `ZAR` | |","enum":["AED","AUD","BRL","CAD","CHF","CNY","DKK","EGP","EUR","GBP","INR","JPY","MXN","MXP","NGN","NOK","PLN","NZD","SAR","SEK","SGD","TRY","USD","ZAR"]},"DSPCurve":{"type":"object","description":"The forecast curve of Bid/Spend vs the metric type based on periodicity.","properties":{"periodicity":{"$ref":"#/components/schemas/DSPForecastPeriodicity"},"points":{"type":"array","items":{"$ref":"#/components/schemas/DSPPoint"},"maxItems":1000,"minItems":0},"focusPoint":{"type":"array","items":{"$ref":"#/components/schemas/DSPPoint"},"maxItems":10,"minItems":0}}},"DSPDeliverInFullConfidence":{"type":"object","description":"Description of how confident we delivery 100% of the ads for the specific metric.","properties":{"value":{"$ref":"#/components/schemas/DSPDeliverInFullConfidenceLevel"}},"required":["value"]},"DSPDeliverInFullConfidenceLevel":{"type":"string","description":"| DeliverInFullConfidenceLevel | Description |\n| --- | --- |\n| `HIGH` | There is a high level of confidence that the campaign or flight will fully deliver its planned budget or impressions. |\n| `MEDIUM` | There is a moderate level of confidence that the campaign or flight will fully deliver its planned budget or impressions. |\n| `LOW` | There is a low level of confidence that the campaign or flight will fully deliver its planned budget or impressions. |\n| `UNAVAILABLE` | Confidence level cannot be determined due to insufficient or missing data. |","enum":["HIGH","MEDIUM","LOW","UNAVAILABLE"]},"DSPEnabledFeaturesInCampaignForecast":{"type":"object","description":"For the user to specify which features to enable in the forecast result.","properties":{"curve":{"type":"boolean","description":"Describe if the user want to see curve or not."},"replanning":{"type":"boolean","description":"Describe if the forecast will show replanning recommendation."},"campaignSettingsCache":{"type":"boolean","description":"Describe if the forecast will use cached settings of a campaign."},"metrics":{"$ref":"#/components/schemas/DSPForecastMetricsDescription"}}},"DSPFlightForecast":{"type":"object","description":"The forecast result of a specific flight.","properties":{"flightId":{"type":"string","description":"The flightId of the flight."},"forecastStartDateTime":{"type":"string","description":"The starttime of the flight for forecasting.","format":"date-time"},"forecastEndDateTime":{"type":"string","description":"The endtime of the flight for forecasting.","format":"date-time"},"totalBudget":{"$ref":"#/components/schemas/DSPMonetaryBudget"},"spend":{"type":"number","description":"The amount of money spend for this flight.","format":"double"},"deliverInFullConfidence":{"$ref":"#/components/schemas/DSPDeliverInFullConfidence"},"metrics":{"type":"array","items":{"$ref":"#/components/schemas/DSPForecastMetric"},"maxItems":20,"minItems":0,"description":"The different metrics to measure the performance of the flight."},"curves":{"type":"array","items":{"$ref":"#/components/schemas/DSPCurve"},"maxItems":4,"minItems":0,"description":"The forecasting curves of a flight based on different periodicities."},"replanning":{"type":"array","items":{"$ref":"#/components/schemas/DSPReplanning"},"maxItems":100,"minItems":0,"description":"The recommendation for replanning."},"warnings":{"type":"array","items":{"$ref":"#/components/schemas/DSPWarning"},"maxItems":10,"minItems":0,"description":"Warnings of the campaign forecast."}},"required":["flightId","forecastEndDateTime","forecastStartDateTime"]},"DSPForecastFlight":{"type":"object","properties":{"flightId":{"type":"string","description":"The ID associated with the flight."},"budget":{"$ref":"#/components/schemas/DSPBudget"},"startDateTime":{"type":"string","description":"The start date of the flight.","format":"date-time"},"endDateTime":{"type":"string","format":"date-time"}},"required":["budget","endDateTime","startDateTime"]},"DSPForecastMetric":{"type":"object","description":"The forecast based on metric and periodicity.","properties":{"metric":{"$ref":"#/components/schemas/DSPSelectedForecastMetric"},"periodicity":{"$ref":"#/components/schemas/DSPForecastPeriodicity"},"value":{"$ref":"#/components/schemas/DSPForecastValue"}},"required":["metric","value"]},"DSPForecastMetricsDescription":{"type":"object","description":"Describe how user select to see all metrics or selected ones.","properties":{"allMetrics":{"type":"boolean","description":"If it is true, all the supported metrics would return."},"selectedMetrics":{"type":"array","items":{"$ref":"#/components/schemas/DSPSelectedForecastMetric"},"maxItems":20,"minItems":0,"description":"The list of selected metrics in order."}},"required":["allMetrics"]},"DSPForecastPeriodicity":{"type":"string","description":"| ForecastPeriodicity | Description |\n| --- | --- |\n| `DAILY` | Forecast results are generated and presented for each individual day. |\n| `LIFETIME` | Forecast results represent the total performance over the remaining entire campaign duration. |\n| `MONTHLY` | Forecast results are aggregated and presented for each calendar month. |\n| `WEEKLY` | Forecast results are aggregated and presented for each calendar week. |","enum":["DAILY","LIFETIME","MONTHLY","WEEKLY"]},"DSPForecastValue":{"type":"object","properties":{"low":{"type":"number","format":"double"},"high":{"type":"number","format":"double"},"mean":{"type":"number","format":"double"}},"required":["high","low","mean"]},"DSPMonetaryBudget":{"type":"object","properties":{"currencyCode":{"$ref":"#/components/schemas/DSPCurrencyCode"},"value":{"type":"number","description":"The monetary amount of the budget cap in the given currency.","format":"double"}},"required":["currencyCode","value"]},"DSPMonetaryBudgetValue":{"type":"object","properties":{"monetaryBudget":{"$ref":"#/components/schemas/DSPMonetaryBudget"}}},"DSPPoint":{"type":"object","properties":{"pointType":{"type":"string"},"x":{"$ref":"#/components/schemas/DSPXPoint"},"y":{"type":"array","items":{"$ref":"#/components/schemas/DSPYPoint"},"maxItems":1000,"minItems":0}},"required":["x"]},"DSPPointLabel":{"type":"string","description":"| PointLabel | Description |\n| --- | --- |\n| `SPEND` | Spend in monetary value. |\n| `BID` | Bid in monetary value. |\n| `DC` | Delivery confidence. |\n| `TAS` | Total available spend. |\n| `AIMP` | Available impressions. |\n| `AREA` | Available reach. |\n| `EIMP` | Expected impressions. |\n| `EREA` | Expected reach. |\n| `CPC` | Cost per click. |\n| `CPA` | Cost per action. |\n| `CPM` | Cost per mille. |\n| `ROAS` | Return on ad spend. |\n| `CAS` | Capped available spend. |","enum":["SPEND","BID","DC","TAS","AIMP","AREA","EIMP","EREA","CPC","CPA","CPM","ROAS","CAS"]},"DSPReplanning":{"type":"object","description":"Recommendation for replanning.","properties":{"scenarioType":{"type":"string"},"title":{"type":"string"},"content":{"type":"string"},"selectedMetrics":{"type":"array","items":{"$ref":"#/components/schemas/DSPSelectedForecastMetric"},"maxItems":20,"minItems":0,"description":"| SelectedForecastMetric | Description |\n| --- | --- |\n| `DC` | Delivery confidence. |\n| `TAS` | Total available spend. |\n| `AIMP` | Available impressions. |\n| `AREA` | Available reach. |\n| `EIMP` | Expected impressions. |\n| `EREA` | Expected reach. |\n| `CPC` | Cost per click. |\n| `CPA` | Cost per action. |\n| `CPM` | Cost per mille. |\n| `ROAS` | Return on ad spend. |\n| `CAS` | Capped available spend. |\n| `IREA` | Incremental reach. |"},"scenarioFlight":{"$ref":"#/components/schemas/DSPForecastFlight"},"metrics":{"type":"array","items":{"$ref":"#/components/schemas/DSPForecastMetric"},"maxItems":20,"minItems":0},"curves":{"type":"array","items":{"$ref":"#/components/schemas/DSPCurve"},"maxItems":4,"minItems":0},"deliverInFullConfidence":{"$ref":"#/components/schemas/DSPDeliverInFullConfidence"}},"required":["content","title"]},"DSPReplanningSettings":{"type":"object","description":"Forecast request of a flight with adjusted settings.","properties":{"flights":{"type":"array","items":{"$ref":"#/components/schemas/DSPForecastFlight"},"maxItems":5,"minItems":0}}},"DSPRetrieveCampaignForecastRequest":{"type":"object","properties":{"campaignForecastDescriptions":{"type":"array","items":{"$ref":"#/components/schemas/DSPCampaignForecastDescription"},"maxItems":1,"minItems":1}}},"DSPSelectedForecastMetric":{"type":"string","description":"| SelectedForecastMetric | Description |\n| --- | --- |\n| `DC` | Delivery confidence. |\n| `TAS` | Total available spend. |\n| `AIMP` | Available impressions. |\n| `AREA` | Available reach. |\n| `EIMP` | Expected impressions. |\n| `EREA` | Expected reach. |\n| `CPC` | Cost per click. |\n| `CPA` | Cost per action. |\n| `CPM` | Cost per mille. |\n| `ROAS` | Return on ad spend. |\n| `CAS` | Capped available spend. |\n| `IREA` | Incremental reach. |","enum":["DC","TAS","AIMP","AREA","EIMP","EREA","CPC","CPA","CPM","ROAS","CAS","IREA"]},"DSPWarning":{"type":"object","description":"The warning message of a forecast.","properties":{"warningLevel":{"type":"integer","format":"int32"},"code":{"type":"string"},"adGroupIds":{"type":"array","items":{"type":"string"},"maxItems":50,"minItems":0},"message":{"type":"string"}},"required":["code","message"]},"DSPXPoint":{"type":"object","description":"The label and value on X axis of the curve.","properties":{"label":{"$ref":"#/components/schemas/DSPPointLabel"},"value":{"type":"number","format":"double"}},"required":["label","value"]},"DSPYPoint":{"type":"object","description":"The label and value on Y axis of the curve.","properties":{"label":{"$ref":"#/components/schemas/DSPPointLabel"},"value":{"$ref":"#/components/schemas/DSPForecastValue"}},"required":["label","value"]},"Error":{"type":"object","properties":{"message":{"type":"string"},"code":{"$ref":"#/components/schemas/ErrorCode"},"fieldLocation":{"type":"string"}},"required":["code","message"]},"ErrorCode":{"type":"string","description":"| ErrorCode | Description |\n| --- | --- |\n| `BAD_REQUEST` | The request is not valid considering the documented schema. |","enum":["BAD_REQUEST"]},"ErrorsIndex":{"type":"object","properties":{"index":{"type":"integer","maximum":0,"minimum":0,"format":"int32"},"errors":{"type":"array","items":{"$ref":"#/components/schemas/Error"},"maxItems":20,"minItems":1}},"required":["errors","index"]},"ForbiddenResponseContent":{"type":"object","properties":{"message":{"type":"string"},"code":{"$ref":"#/components/schemas/ErrorCode"}},"required":["code","message"]},"GatewayTimeoutResponseContent":{"type":"object","properties":{"message":{"type":"string"},"code":{"type":"string"}},"required":["code","message"]},"InternalServerErrorResponseContent":{"type":"object","properties":{"message":{"type":"string"},"code":{"type":"string"}},"required":["code","message"]},"NotFoundResponseContent":{"type":"object","properties":{"message":{"type":"string"},"code":{"$ref":"#/components/schemas/ErrorCode"}},"required":["code","message"]},"ServiceUnavailableErrorResponseContent":{"type":"object","properties":{"message":{"type":"string"},"code":{"type":"string"}},"required":["code","message"]},"TooManyRequestsResponseContent":{"type":"object","properties":{"message":{"type":"string"},"code":{"$ref":"#/components/schemas/ErrorCode"}},"required":["code","message"]},"UnauthorizedResponseContent":{"type":"object","properties":{"message":{"type":"string"},"code":{"$ref":"#/components/schemas/ErrorCode"}},"required":["code","message"]}},"parameters":{"AccountIdHeader":{"name":"Amazon-Ads-AccountId","in":"header","description":"The identifier of an Amazon Ads Advertiser Account.","schema":{"type":"string"}},"ClientIdHeader":{"name":"Amazon-Ads-ClientId","in":"header","description":"The identifier of a client associated with a 'Login with Amazon' account.","schema":{"type":"string"},"required":true},"ManagerAccountIdHeader":{"name":"Amazon-Ads-Manager-AccountId","in":"header","description":"The identifier of an Amazon Ads Manager Account.","schema":{"type":"string"}}}}}