Amazon Ads API MCP

{"components":{"callbacks":{},"examples":{},"headers":{},"links":{},"parameters":{},"requestBodies":{},"responses":{},"schemas":{"brandMetricsError":{"description":"The error response object.","properties":{"code":{"description":"http status code.","type":"string"},"details":{"description":"high level human readable message.","type":"string"},"errors":{"description":"A list of the errors encountered.","items":{"properties":{"errorCode":{"type":"string"},"errorId":{"type":"integer"},"errorMessage":{"type":"string"}},"type":"object"},"maxItems":3,"minItems":1,"type":"array"},"requestId":{"type":"string"}},"type":"object"},"brandMetricsGenerateReportRequest":{"description":"Request object to generate the Brand Metrics Report.","properties":{"brandName":{"description":"Optional. Brand Name. If no Brand Name is passed, then all data available for all brands belonging to the entity are retrieved.","type":"string"},"categoryPath":{"description":"Optional. The hierarchical path that leads to a node starting with the root node. If no Category Node Name is passed, then all data available for all brands belonging to the entity are retrieved.","items":{"type":"string"},"maxItems":20,"minItems":0,"type":"array"},"categoryTreeName":{"description":"Optional. The node at the top of a browse tree. It is the start node of a tree.","type":"string"},"format":{"default":"JSON","description":"Format of the report.","enum":["CSV","JSON"],"type":"string"},"lookBackPeriod":{"default":"1W","description":"Currently supported values: \"1w\" (one week), \"1m\" (one month) and \"1cm\" (one calendar month). This defines the period of time used to determine the number of shoppers in the metrics computation.","enum":["1CM","1M","1W"],"type":"string"},"metrics":{"description":"Optional. Specify an array of string of metrics field names to include in the report. If no metric field names are specified, all metrics are returned.","items":{"description":"**engagedShopperRateLowerBound** - Lower bound on the percentage of unique shoppers in a category that your brand has driven an engagement with or purchase from int the selected time frame divided by...","type":"string"},"maxItems":20,"minItems":0,"type":"array"},"reportEndDate":{"description":"Optional. Retrieves metrics with metricsComputationDate between reportStartDate and reportEndDate (inclusive). The maximum allowed date range for report generation is 3 months.","format":"date","type":"string"},"reportStartDate":{"description":"Optional. Retrieves metrics with metricsComputationDate between reportStartDate and reportEndDate (inclusive). The maximum allowed date range for report generation is 3 months.","format":"date","type":"string"}},"type":"object"},"brandMetricsGenerateReportRequestV11":{"description":"Request object to generate the Brand Metrics Report.","properties":{"brandName":{"description":"Optional. Brand Name. If no Brand Name is passed, then all data available for all brands belonging to the entity are retrieved.","type":"string"},"categoryPath":{"description":"Optional. The hierarchical path that leads to a node starting with the root node. If no Category Node Name is passed, then all data available for all brands belonging to the entity are retrieved.","items":{"type":"string"},"maxItems":20,"minItems":0,"type":"array"},"categoryTreeName":{"description":"Optional. The node at the top of a browse tree. It is the start node of a tree.","type":"string"},"format":{"default":"JSON","description":"Format of the report.","enum":["CSV","JSON"],"type":"string"},"lookBackPeriod":{"default":"1w","description":"Currently supported values: \"1w\" (one week), \"1m\" (one month) and \"1cm\" (one calendar month). This defines the period of time used to determine the number of shoppers in the metrics computation.","enum":["1cm","1m","1w"],"type":"string"},"metrics":{"description":"Optional. Specify an array of string of metrics field names to include in the report. If no metric field names are specified, all metrics are returned.","items":{"description":"**totalSnSCustomers** - The total number of customers who had one or more Subscribe & Save purchases on any brand ASIN in the chosen retail browse node/category in a given lookback period.","type":"string"},"maxItems":500,"minItems":0,"type":"array"},"reportEndDate":{"description":"Optional. Retrieves metrics with metricsComputationDate between reportStartDate and reportEndDate (inclusive). The maximum allowed date range for report generation is 3 months.","format":"date","type":"string"},"reportStartDate":{"description":"Optional. Retrieves metrics with metricsComputationDate between reportStartDate and reportEndDate (inclusive). The maximum allowed date range for report generation is 3 months.","format":"date","type":"string"}},"type":"object"},"brandMetricsGenerateReportResponse":{"description":"Response object containing Brand Metrics Report metadata.","properties":{"expiration":{"description":"The expiration time of the URI in the location property in milliseconds. The expiration time is the interval between the time the response was generated and the time the URI expires.","format":"int64","type":"integer"},"format":{"default":"JSON","description":"Format of the report.","enum":["CSV","JSON"],"type":"string"},"location":{"description":"The URI address of the report.","type":"string"},"reportId":{"description":"The identifier of the report.","type":"string"},"status":{"description":"The build status of the report.","enum":["FAILED","IN_PROGRESS","SUCCESSFUL"],"type":"string"},"statusDetails":{"description":"A human-readable description of the current status.","type":"string"}},"required":["expiration","format","reportId","status","statusDetails"],"type":"object"},"brandMetricsGenerateReportResponseV11":{"description":"Response object containing Brand Metrics Report metadata.","properties":{"expiration":{"description":"The expiration time of the URI in the location property in milliseconds. The expiration time is the interval between the time the response was generated and the time the URI expires.","format":"int64","type":"integer"},"format":{"default":"JSON","description":"Format of the report.","enum":["CSV","JSON"],"type":"string"},"location":{"description":"The URI address of the report.","type":"string"},"reportId":{"description":"The identifier of the report.","type":"string"},"status":{"description":"The build status of the report.","enum":["FAILED","IN_PROGRESS","SUCCESSFUL"],"type":"string"},"statusDetails":{"description":"A human-readable description of the current status.","type":"string"}},"required":["expiration","format","reportId","status","statusDetails"],"type":"object"},"brandMetricsGetReportByIdResponse":{"description":"Response object containing Brand Metrics Report status metadata.","properties":{"brandsInfo":{"description":"List of first 200 brands for which the Brand Metrics report is generated. The report may contain more than 200 brands. This list is only populated with brands if the Brand Metrics are available for the brands that an advertiser has access to.","items":{"properties":{"id":{"type":"string"},"name":{"type":"string"}},"type":"object"},"maxItems":200,"minItems":0,"type":"array"},"expiration":{"description":"The expiration time of the URI in the location property in milliseconds. The expiration time is the interval between the time the response was generated and the time the URI expires.","format":"int64","type":"integer"},"format":{"default":"JSON","description":"Format of the report.","enum":["CSV","JSON"],"type":"string"},"location":{"description":"The URI address of the report. Only available if the report is generated successfully. The location is empty if the Brand Metrics are not available or if the report is not generated successfully.","type":"string"},"reportId":{"description":"The identifier of the report.","type":"string"},"status":{"description":"The build status of the report.","enum":["FAILED","IN_PROGRESS","SUCCESSFUL"],"type":"string"},"statusDetails":{"description":"A human-readable description of the current status.","type":"string"}},"required":["expiration","format","reportId","status","statusDetails"],"type":"object"}},"securitySchemes":{}},"info":{"title":"Brand Metrics","version":"3.0"},"openapi":"3.0.1","paths":{"/insights/brandMetrics/report":{"post":{"description":"Generates the Brand Metrics report in CSV or JSON format. Customize the report by passing a specific categoryTreeName, categoryPath, brandName, reportStartDate, reportEndDate, lookbackPeriod, format o...","operationId":"generateBrandMetricsReport","parameters":[{"description":"The identifier of a profile associated with the advertiser account. Use `GET` method on Profiles resource to list profiles associated with the access token passed in the HTTP Authorization header and choose profile id `profileId` from the response to pass it as input.","example":"195213312458027","in":"header","name":"Amazon-Advertising-API-Scope","required":true,"schema":{"type":"string"}},{"description":"The identifier of a client associated with a \"Login with Amazon\" account.","example":"amzn1.application-oa2-client.8baa9caa3eac48eab89780e73ce03b19.","in":"header","name":"Amazon-Advertising-API-ClientId","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/vnd.insightsbrandmetrics.v1+json":{"schema":{"$ref":"#/components/schemas/brandMetricsGenerateReportRequest"}},"application/vnd.insightsbrandmetrics.v1.1+json":{"schema":{"$ref":"#/components/schemas/brandMetricsGenerateReportRequestV11"}}},"description":"Create request body to generate the Brand Metrics Report."},"responses":{"200":{"content":{"application/vnd.insightsbrandmetrics.v1+json":{"schema":{"$ref":"#/components/schemas/brandMetricsGenerateReportResponse"}},"application/vnd.insightsbrandmetrics.v1.1+json":{"schema":{"$ref":"#/components/schemas/brandMetricsGenerateReportResponseV11"}}},"description":"Successful operation."},"400":{"content":{"application/vnd.insightsbrandmetricserror.v1+json":{"schema":{"$ref":"#/components/schemas/brandMetricsError"}}},"description":"Bad Request."},"401":{"content":{"application/vnd.insightsbrandmetricserror.v1+json":{"schema":{"$ref":"#/components/schemas/brandMetricsError"}}},"description":"Unauthorized. Request failed because user is not authenticated or is not allowed to invoke the operation."},"403":{"content":{"application/vnd.insightsbrandmetricserror.v1+json":{"schema":{"$ref":"#/components/schemas/brandMetricsError"}}},"description":"Forbidden. Request failed because user does not have access to a specified resource."},"422":{"content":{"application/vnd.insightsbrandmetricserror.v1+json":{"schema":{"$ref":"#/components/schemas/brandMetricsError"}}},"description":"Unprocessable Entity - Request was understood, but contained invalid parameters."},"424":{"content":{"application/vnd.insightsbrandmetricserror.v1+json":{"schema":{"$ref":"#/components/schemas/brandMetricsError"}}},"description":"Dependency Failure - Please retry the request."},"429":{"content":{"application/vnd.insightsbrandmetricserror.v1+json":{"schema":{"$ref":"#/components/schemas/brandMetricsError"}}},"description":"Too many requests. The request was rate-limited. Retry later."},"500":{"content":{"application/vnd.insightsbrandmetricserror.v1+json":{"schema":{"$ref":"#/components/schemas/brandMetricsError"}}},"description":"Internal server error. Retry later. Contact support if this response persists."}},"summary":"Generate Brand Metrics Report. Each response record will include the following dimensional fields (in addition to the requested metrics) brand Namecategory, TreeNamecategory, HierarchylookbackPeriod, metricsComputationDate\n","tags":["Report"]}},"/insights/brandMetrics/report/{reportId}":{"get":{"description":"Fetch the location and status of the report for the brands for which the metrics are available. The URL to the report is only available when the status of the report is SUCCESSFUL.","operationId":"getBrandMetricsReport","parameters":[{"description":"The report Id to be fetched.","in":"path","name":"reportId","required":true,"schema":{"type":"string"}},{"description":"The identifier of a profile associated with the advertiser account. Use `GET` method on Profiles resource to list profiles associated with the access token passed in the HTTP Authorization header and choose profile id `profileId` from the response to pass it as input.","example":"195213312458027","in":"header","name":"Amazon-Advertising-API-Scope","required":true,"schema":{"type":"string"}},{"description":"The identifier of a client associated with a \"Login with Amazon\" account.","example":"amzn1.application-oa2-client.8baa9caa3eac48eab89780e73ce03b19.","in":"header","name":"Amazon-Advertising-API-ClientId","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/vnd.insightsbrandmetrics.v1+json":{"schema":{"$ref":"#/components/schemas/brandMetricsGetReportByIdResponse"}},"application/vnd.insightsbrandmetrics.v1.1+json":{"schema":{"$ref":"#/components/schemas/brandMetricsGetReportByIdResponse"}}},"description":"Successful operation."},"400":{"content":{"application/vnd.insightsbrandmetricserror.v1+json":{"schema":{"$ref":"#/components/schemas/brandMetricsError"}}},"description":"Bad Request."},"401":{"content":{"application/vnd.insightsbrandmetricserror.v1+json":{"schema":{"$ref":"#/components/schemas/brandMetricsError"}}},"description":"Unauthorized. Request failed because user is not authenticated or is not allowed to invoke the operation."},"403":{"content":{"application/vnd.insightsbrandmetricserror.v1+json":{"schema":{"$ref":"#/components/schemas/brandMetricsError"}}},"description":"Forbidden. Request failed because user does not have access to a specified resource."},"422":{"content":{"application/vnd.insightsbrandmetricserror.v1+json":{"schema":{"$ref":"#/components/schemas/brandMetricsError"}}},"description":"Unprocessable Entity - Request was understood, but contained invalid. parameters."},"424":{"content":{"application/vnd.insightsbrandmetricserror.v1+json":{"schema":{"$ref":"#/components/schemas/brandMetricsError"}}},"description":"Dependency Failure - Please retry the request."},"429":{"content":{"application/vnd.insightsbrandmetricserror.v1+json":{"schema":{"$ref":"#/components/schemas/brandMetricsError"}}},"description":"Too many requests. The request was rate-limited. Retry later."},"500":{"content":{"application/vnd.insightsbrandmetricserror.v1+json":{"schema":{"$ref":"#/components/schemas/brandMetricsError"}}},"description":"Internal server error. Retry later. Contact support if this response persists."}},"summary":"Retrieve the status and the URL of the Brand Metrics Report being generated","tags":["Report"]}}}}