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":{"description":"enum indicating the category of error. Example `INVALID_HEADER`.","type":"string"},"errorId":{"description":"ID to indicate the granular error.","type":"integer"},"errorMessage":{"description":"human readable error message for each error.","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.","example":"Mattress Mogul","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":{"example":["Categories","Granola & Snack Bars","Snack Food"],"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.","example":"us-home","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.","example":["customerConversionRate","engagedShopperRateLowerBound","newToBrandCustomerRate"],"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 the total unique shoppers with 1+ detail page view in the selected category.\n\n**engagedShopperRateUpperBound** - Upper bound on the percentage of unique shoppers in a category that your brand has driven an engagement with or purchase from in the selected time frame divided by the total unique shoppers with 1+ detail page view in the selected category.\n\n**engagedShopperRateCategoryMedianLowerBound** - Lower bound on the percentage of unique shoppers in a category that your brand has driven an engagement with or purchased from in the selected time frame divided by the total unique shoppers with 1+ detail page view in the selected category for the median peers.\n\n**engagedShopperRateCategoryMedianUpperBound** - Upper bound on the percentage of unique shoppers in a category that your brand has driven an engagement with or purchase from in the selected time frame divided by the total unique shoppers with 1+ detail page view in the selected category for the median peers.\n\n**engagedShopperRateCategoryTopPerformersLowerBound** - Lower bound on the percentage of unique shoppers in a category that your brand has driven an engagement with or purchase from in the selected time frame by the total unique shoppers with 1+ detail page view in the selected category for the top 95th-99th percent of peers.\n\n**engagedShopperRateCategoryTopPerformersUpperBound** - Upper bound on the percentage of unique shoppers in a category that your brand has driven an engagement with or purchase from in the selected time frame divided by the total unique shoppers with 1+ detail page view in the selected category for the top 95th-99th percent of peers.\n\n**customerConversionRate** - percentage of shoppers moving from \"considering\" [Brand Name] in the [categoryPath] to \"purchased\" in the [lookBackPeriod].\n\n**customerConversionRateCategoryMedian** - percentage of shoppers moving from \"considering\" the peer median in the [categoryPath] to \"purchased\" in the [lookBackPeriod].\n\n**customerConversionRateCategoryTopPerformers** - percentage of shoppers moving from \"considering\" the average of the top 95th-99th percent of peers in the [categoryPath] to \"purchased\" in the [lookBackPeriod].\n\n**newToBrandCustomerRate** - share of customers that had not purchased [Brand Name] products in the last 12 months, but did so in the [lookBackPeriod].\n\n**newToBrandCustomerRateCategoryMedian** - share of customers that had not purchased peer median products in the last 12 months, but did so in the [lookBackPeriod].\n\n**newToBrandCustomerRateCategoryTopPerformers** - share of customers that had not purchased average of the top 95th-99th percent of peers products in the last 12 months, but did so in the [lookBackPeriod].\n\n**brandedSearchesOnly** - shoppers that searched for [Brand Name] but did not further engage or purchase from [Brand Name] and [categoryPath] in the [lookBackPeriod].\n\n**brandedSearchesCategoryMedian** - shoppers that searched for the peer median, but did not further engage or purchase from peer median and [categoryPath] in the [lookBackPeriod].\n\n**brandedSearchesCategoryTopPerformers** - shoppers that searched for the avg. of the top 95th - 99th percent of peers, and [categoryPath] but did not further engage or purchase from the Top Performers in the [lookBackPeriod].\n**viewedDetailPageOnly** - shoppers that viewed detail page only of [Brand Name] in [categoryPath] in [lookBackPeriod].\n\n**viewedDetailPageCategoryMedian** - shoppers that viewed the detail page only of peer median in [categoryPath] in [lookBackPeriod].\n\n**viewedDetailPageCategoryTopPerformers** - shoppers that viewed the detail page only of avg. of the top 95th - 99th percent of peers in [categoryPath] in [lookBackPeriod].\n\n**viewedDetailPageOnlyReturnOnEngagement** - The average amount of sales each customer who was in this state 12 months ago drove over 1 year. Calculated by taking the total original population 12 months ago by the total amount of sales this population drove over the last year for your brand in the selected category.\n\n**viewedDetailPageROECategoryMedian** - The average amount of sales each customer who was in this state for the peer median 12 months ago drove over 1 year. Calculated by taking the total original population 12 months ago by the total amount of sales this population drove over the last year for your brand in the selected category.\n\n**viewedDetailPageROECategoryTopPerformers** - The average amount of sales each customer who was in this state for the 95-99 percent peers 12 months ago drove over 1 year. Calculated by taking the total original population 12 months ago by the total amount of sales this population drove over the last year for your brand in the selected category.\n\n**brandedSearchesAndDetailPageViews** - shoppers that searched brand and viewed detail page of [Brand Name] in [categoryPath] in [lookBackPeriod].\n\n**brandedSearchesAndDetailPageViewsCategoryMedian** - shoppers that searched brand and viewed the detail page of peer median in [categoryPath] in [lookBackPeriod].\n\n**brandedSearchesAndDetailPageViewsCategoryTopPerformers** - shoppers that searched brand and viewed the detail page of avg. of the top 95th - 99th percent of peers in [categoryPath] in [lookBackPeriod].\n\n**brandedSearchesAndDetailPageViewsReturnOnEngagement** - The average amount of sales each customer who was in this state 12 months ago drove over 1 year. Calculated by taking the total original population 12 months ago by the total amount of sales this population drove over the last year for your brand in the selected category.\n\n**brandedSearchesAndDetailPageViewsROECategoryMedian** - The average amount of sales each customer who was in this state for the peer median 12 months ago drove over 1 year. Calculated by taking the total original population 12 months ago by the total amount of sales this population drove over the last year for your brand in the selected category.\n\n**brandedSearchesAndDetailPageViewsROECategoryTopPerformers** - The average amount of sales each customer who was in this state for the 95-99 percent peers 12 months ago drove over 1 year. Calculated by taking the total original population 12 months ago by the total amount of sales this population drove over the last year for your brand in the selected category.\n\n**addToCarts** - shoppers that added [Brand Name] to cart in [categoryPath] in [lookBackPeriod].\n\n**addToCartsCategoryMedian** - shoppers that added the peer median to cart in [categoryPath] in [lookBackPeriod].\n\n**addToCartsCategoryTopPerformers** - shoppers that added the avg. of the top 95th - 99th percent of peers to cart in [categoryPath] in [lookBackPeriod].\n\n**addToCartsReturnOnEngagement** - The average amount of sales each customer who was in this state 12 months ago drove over 1 year. Calculated by taking the total original population 12 months ago by the total amount of sales this population drove over the last year for your brand in the selected category.\n\n**addToCartsROECategoryMedian** - The average amount of sales each customer who was in this state for the peer median 12 months ago drove over 1 year. Calculated by taking the total original population 12 months ago by the total amount of sales this population drove over the last year for your brand in the selected category.\n\n**addToCartsROECategoryTopPerformers** - The average amount of sales each customer who was in this state for the 95-99 percent peers 12 months ago drove over 1 year. Calculated by taking the total original population 12 months ago by the total amount of sales this population drove over the last year for your brand in the selected category.\n\n**brandCustomers** - 0%-90% of sales contributing shoppers for [Brand Name] whom purchased in [categoryPath] in [lookBackPeriod].\n\n**brandCustomersCategoryMedian** - 0%-90% of sales contributors for the peer median whom purchased in [categoryPath] in [lookBackPeriod].\n\nbrandCustomersCategoryTopPerformers - 0%-90% of sales contributors for avg. of the top 95th - 99th percent of peers whom purchased in [categoryPath] in [lookBackPeriod].\n\n**brandCustomersReturnOnEngagement** - The average amount of sales each customer who was in this state 12 months ago drove over 1 year. Calculated by taking the total original population 12 months ago by the total amount of sales this population drove over the last year for your brand in the selected category.\n\n**brandCustomersROECategoryMedian** - The average amount of sales each customer who was in this state for the peer median 12 months ago drove over 1 year. Calculated by taking the total original population 12 months ago by the total amount of sales this population drove over the last year for your brand in the selected category.\n\n**brandCustomersROECategoryTopPerformers** - The average amount of sales each customer who was in this state for the 95-99 percent peers 12 months ago drove over 1 year. Calculated by taking the total original population 12 months ago by the total amount of sales this population drove over the last year for your brand in the selected category.\n\n**highValueCustomers** - top 10% of sales contributing shoppers for. \n\n**highValueCustomersCategoryMedian** - top 10% of sales contributing shoppers for peer median in [categoryPath] in [lookBackPeriod].\n\n**highValueCustomersTopPerformers** - top 10% of sales contributing shoppers for the top 95th - 99th percent of peers in [categoryPath] in [lookBackPeriod].\n\n**highValueCustomersReturnOnEngagement** - The average amount of sales each customer who was in this state 12 months ago drove over 1 year. Calculated by taking the total original population 12 months ago by the total amount of sales this population drove over the last year for your brand in the selected category.\n\n**highValueCustomersROECategoryMedian** - The average amount of sales each customer who was in this state for the peer median 12 months ago drove over 1 year. Calculated by taking the total original population 12 months ago by the total amount of sales this population drove over the last year for your brand in the selected category.\n\n**highValueCustomersCategoryTopPerformers** - The average amount of sales each customer who was in this state for the 95-99 percent peers 12 months ago drove over 1 year. Calculated by taking the total original population 12 months ago by the total amount of sales this population drove over the last year for your brand in the selected category.\n\n**awarenessIndex** - Awareness Index measures actual on-Amazon audience signals reflecting awareness for your brand in the short and long term, across the whole on-Amazon audience. The percentile lets you know how the awareness activity for your brand compares to that of your peers.\n\n**considerationIndex** - Consideration Index measures actual on-Amazon audience signals reflecting consideration for your brand in the short and long term, across the whole on-Amazon audience. The percentile lets you know how the consideration activity for your brand compares to that of your peers.\n\n**salesIndex** - Sales Index represents actual on-Amazon sales in the short term and long term, across the whole on-Amazon audience. The percentile lets you know how your sales compare to that of your peers.","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. The date will be in the Coordinated Universal Time (UTC) timezone in YYYY-MM-DD format. If both reportStartDate and reportEndDate are passed and the range is greater than 3 months, the reportStartDate will be adjusted to a date 3 months from the reportEndDate. If no date is passed in reportEndDate, all available metrics till metricsComputationDate of 3 months after the reportStartDate will be provided. If no date is passed for either reportStartDate or reportEndDate, the metrics with the most recent metricsComputationDate will be returned.","example":"2021-01-30","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. The date will be in the Coordinated Universal Time (UTC) timezone in YYYY-MM-DD format. If both reportStartDate and reportEndDate are passed and the range is greater than 3 months, the reportStartDate will be adjusted to a date 3 months from the reportEndDate. If no date is passed in reportStartDate, all available metrics from metricsComputationDate of 3 months before the reportEndDate will be provided. If no date is passed for either reportStartDate or reportEndDate, the metrics with the most recent metricsComputationDate will be returned.","example":"2021-01-01","format":"date","type":"string"}},"type":"object","xml":{"name":"brandMetricsGenerateReportRequest"}},"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.","example":"Mattress Mogul","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":{"example":["Categories","Granola & Snack Bars","Snack Food"],"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.","example":"us-home","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.","example":["customerConversionRate","engagedShopperRateLowerBound","newToBrandCustomerRate","newToBrandSnSCustomersRate","totalSnSCustomers"],"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.\n\n**newToBrandSnSCustomersRate** -The number of shoppers who had one or more Subscribe & Save purchases on any brand ASIN in the chosen retail browse node/category in a given lookback period but did not have any prior SnS purchases on any brand ASIN in the same category in the prior year divided by the total number of shoppers who had one or more Subscribe & Save purchases for a given retail browse node/category in the chosen lookback period divided. \n\n**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 the total unique shoppers with 1+ detail page view in the selected category.\n\n**engagedShopperRateUpperBound** - Upper bound on the percentage of unique shoppers in a category that your brand has driven an engagement with or purchase from in the selected time frame divided by the total unique shoppers with 1+ detail page view in the selected category.\n\n**engagedShopperRateCategoryMedianLowerBound** - Lower bound on the percentage of unique shoppers in a category that your brand has driven an engagement with or purchased from in the selected time frame divided by the total unique shoppers with 1+ detail page view in the selected category for the median peers.\n\n**engagedShopperRateCategoryMedianUpperBound** - Upper bound on the percentage of unique shoppers in a category that your brand has driven an engagement with or purchase from in the selected time frame divided by the total unique shoppers with 1+ detail page view in the selected category for the median peers.\n\n**engagedShopperRateCategoryTopPerformersLowerBound** - Lower bound on the percentage of unique shoppers in a category that your brand has driven an engagement with or purchase from in the selected time frame by the total unique shoppers with 1+ detail page view in the selected category for the top 95th-99th percent of peers.\n\n**engagedShopperRateCategoryTopPerformersUpperBound** - Upper bound on the percentage of unique shoppers in a category that your brand has driven an engagement with or purchase from in the selected time frame divided by the total unique shoppers with 1+ detail page view in the selected category for the top 95th-99th percent of peers.\n\n**customerConversionRate** - percentage of shoppers moving from \"considering\" [Brand Name] in the [categoryPath] to \"purchased\" in the [lookBackPeriod].\n\n**customerConversionRateCategoryMedian** - percentage of shoppers moving from \"considering\" the peer median in the [categoryPath] to \"purchased\" in the [lookBackPeriod].\n\n**customerConversionRateCategoryTopPerformers** - percentage of shoppers moving from \"considering\" the average of the top 95th-99th percent of peers in the [categoryPath] to \"purchased\" in the [lookBackPeriod].\n\n**newToBrandCustomerRate** - share of customers that had not purchased [Brand Name] products in the last 12 months, but did so in the [lookBackPeriod].\n\n**newToBrandCustomerRateCategoryMedian** - share of customers that had not purchased peer median products in the last 12 months, but did so in the [lookBackPeriod].\n\n**newToBrandCustomerRateCategoryTopPerformers** - share of customers that had not purchased average of the top 95th-99th percent of peers products in the last 12 months, but did so in the [lookBackPeriod].\n\n**brandedSearchesOnly** - shoppers that searched for [Brand Name] but did not further engage or purchase from [Brand Name] and [categoryPath] in the [lookBackPeriod].\n\n**brandedSearchesCategoryMedian** - shoppers that searched for the peer median, but did not further engage or purchase from peer median and [categoryPath] in the [lookBackPeriod].\n\n**brandedSearchesCategoryTopPerformers** - shoppers that searched for the avg. of the top 95th - 99th percent of peers, and [categoryPath] but did not further engage or purchase from the Top Performers in the [lookBackPeriod].\n**viewedDetailPageOnly** - shoppers that viewed detail page only of [Brand Name] in [categoryPath] in [lookBackPeriod].\n\n**viewedDetailPageCategoryMedian** - shoppers that viewed the detail page only of peer median in [categoryPath] in [lookBackPeriod].\n\n**viewedDetailPageCategoryTopPerformers** - shoppers that viewed the detail page only of avg. of the top 95th - 99th percent of peers in [categoryPath] in [lookBackPeriod].\n\n**viewedDetailPageOnlyReturnOnEngagement** - The average amount of sales each customer who was in this state 12 months ago drove over 1 year. Calculated by taking the total original population 12 months ago by the total amount of sales this population drove over the last year for your brand in the selected category.\n\n**viewedDetailPageROECategoryMedian** - The average amount of sales each customer who was in this state for the peer median 12 months ago drove over 1 year. Calculated by taking the total original population 12 months ago by the total amount of sales this population drove over the last year for your brand in the selected category.\n\n**viewedDetailPageROECategoryTopPerformers** - The average amount of sales each customer who was in this state for the 95-99 percent peers 12 months ago drove over 1 year. Calculated by taking the total original population 12 months ago by the total amount of sales this population drove over the last year for your brand in the selected category.\n\n**brandedSearchesAndDetailPageViews** - shoppers that searched brand and viewed detail page of [Brand Name] in [categoryPath] in [lookBackPeriod].\n\n**brandedSearchesAndDetailPageViewsCategoryMedian** - shoppers that searched brand and viewed the detail page of peer median in [categoryPath] in [lookBackPeriod].\n\n**brandedSearchesAndDetailPageViewsCategoryTopPerformers** - shoppers that searched brand and viewed the detail page of avg. of the top 95th - 99th percent of peers in [categoryPath] in [lookBackPeriod].\n\n**brandedSearchesAndDetailPageViewsReturnOnEngagement** - The average amount of sales each customer who was in this state 12 months ago drove over 1 year. Calculated by taking the total original population 12 months ago by the total amount of sales this population drove over the last year for your brand in the selected category.\n\n**brandedSearchesAndDetailPageViewsROECategoryMedian** - The average amount of sales each customer who was in this state for the peer median 12 months ago drove over 1 year. Calculated by taking the total original population 12 months ago by the total amount of sales this population drove over the last year for your brand in the selected category.\n\n**brandedSearchesAndDetailPageViewsROECategoryTopPerformers** - The average amount of sales each customer who was in this state for the 95-99 percent peers 12 months ago drove over 1 year. Calculated by taking the total original population 12 months ago by the total amount of sales this population drove over the last year for your brand in the selected category.\n\n**addToCarts** - shoppers that added [Brand Name] to cart in [categoryPath] in [lookBackPeriod].\n\n**addToCartsCategoryMedian** - shoppers that added the peer median to cart in [categoryPath] in [lookBackPeriod].\n\n**addToCartsCategoryTopPerformers** - shoppers that added the avg. of the top 95th - 99th percent of peers to cart in [categoryPath] in [lookBackPeriod].\n\n**addToCartsReturnOnEngagement** - The average amount of sales each customer who was in this state 12 months ago drove over 1 year. Calculated by taking the total original population 12 months ago by the total amount of sales this population drove over the last year for your brand in the selected category.\n\n**addToCartsROECategoryMedian** - The average amount of sales each customer who was in this state for the peer median 12 months ago drove over 1 year. Calculated by taking the total original population 12 months ago by the total amount of sales this population drove over the last year for your brand in the selected category.\n\n**addToCartsROECategoryTopPerformers** - The average amount of sales each customer who was in this state for the 95-99 percent peers 12 months ago drove over 1 year. Calculated by taking the total original population 12 months ago by the total amount of sales this population drove over the last year for your brand in the selected category.\n\n**brandCustomers** - 0%-90% of sales contributing shoppers for [Brand Name] whom purchased in [categoryPath] in [lookBackPeriod].\n\n**brandCustomersCategoryMedian** - 0%-90% of sales contributors for the peer median whom purchased in [categoryPath] in [lookBackPeriod].\n\nbrandCustomersCategoryTopPerformers - 0%-90% of sales contributors for avg. of the top 95th - 99th percent of peers whom purchased in [categoryPath] in [lookBackPeriod].\n\n**brandCustomersReturnOnEngagement** - The average amount of sales each customer who was in this state 12 months ago drove over 1 year. Calculated by taking the total original population 12 months ago by the total amount of sales this population drove over the last year for your brand in the selected category.\n\n**brandCustomersROECategoryMedian** - The average amount of sales each customer who was in this state for the peer median 12 months ago drove over 1 year. Calculated by taking the total original population 12 months ago by the total amount of sales this population drove over the last year for your brand in the selected category.\n\n**brandCustomersROECategoryTopPerformers** - The average amount of sales each customer who was in this state for the 95-99 percent peers 12 months ago drove over 1 year. Calculated by taking the total original population 12 months ago by the total amount of sales this population drove over the last year for your brand in the selected category.\n\n**highValueCustomers** - top 10% of sales contributing shoppers for. \n\n**highValueCustomersCategoryMedian** - top 10% of sales contributing shoppers for peer median in [categoryPath] in [lookBackPeriod].\n\n**highValueCustomersTopPerformers** - top 10% of sales contributing shoppers for the top 95th - 99th percent of peers in [categoryPath] in [lookBackPeriod].\n\n**highValueCustomersReturnOnEngagement** - The average amount of sales each customer who was in this state 12 months ago drove over 1 year. Calculated by taking the total original population 12 months ago by the total amount of sales this population drove over the last year for your brand in the selected category.\n\n**highValueCustomersROECategoryMedian** - The average amount of sales each customer who was in this state for the peer median 12 months ago drove over 1 year. Calculated by taking the total original population 12 months ago by the total amount of sales this population drove over the last year for your brand in the selected category.\n\n**highValueCustomersCategoryTopPerformers** - The average amount of sales each customer who was in this state for the 95-99 percent peers 12 months ago drove over 1 year. Calculated by taking the total original population 12 months ago by the total amount of sales this population drove over the last year for your brand in the selected category.\n\n**awarenessIndex** - Awareness Index measures actual on-Amazon audience signals reflecting awareness for your brand in the short and long term, across the whole on-Amazon audience. The percentile lets you know how the awareness activity for your brand compares to that of your peers.\n\n**considerationIndex** - Consideration Index measures actual on-Amazon audience signals reflecting consideration for your brand in the short and long term, across the whole on-Amazon audience. The percentile lets you know how the consideration activity for your brand compares to that of your peers.\n\n**salesIndex** - Sales Index represents actual on-Amazon sales in the short term and long term, across the whole on-Amazon audience. The percentile lets you know how your sales compare to that of your peers.","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. The date will be in the Coordinated Universal Time (UTC) timezone in YYYY-MM-DD format. If both reportStartDate and reportEndDate are passed and the range is greater than 3 months, the reportStartDate will be adjusted to a date 3 months from the reportEndDate. If no date is passed in reportEndDate, all available metrics till metricsComputationDate of 3 months after the reportStartDate will be provided. If no date is passed for either reportStartDate or reportEndDate, the metrics with the most recent metricsComputationDate will be returned.","example":"2021-01-30","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. The date will be in the Coordinated Universal Time (UTC) timezone in YYYY-MM-DD format. If both reportStartDate and reportEndDate are passed and the range is greater than 3 months, the reportStartDate will be adjusted to a date 3 months from the reportEndDate. If no date is passed in reportStartDate, all available metrics from metricsComputationDate of 3 months before the reportEndDate will be provided. If no date is passed for either reportStartDate or reportEndDate, the metrics with the most recent metricsComputationDate will be returned.","example":"2021-01-01","format":"date","type":"string"}},"type":"object","xml":{"name":"brandMetricsGenerateReportRequestV11"}},"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.","example":"1111123123","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","xml":{"name":"brandMetricsGenerateReportResponse"}},"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.","example":"1111123123","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","xml":{"name":"brandMetricsGenerateReportResponseV11"}},"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":{"description":"GCOR ID from Brand Registry.","example":"762188","type":"string"},"name":{"description":"Brand Name.","example":"Mattress Mogul","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.","example":"1111123123","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","xml":{"name":"brandMetricsGetReportByIdResponse"}}},"securitySchemes":{}},"info":{"description":"Brand Metrics provides a new measurement solution that quantifies opportunities for your brand at each stage of the customer journey on Amazon, and helps brands understand the value of different shopping engagements that impact stages of that journey. You can now access Awareness and Consideration indices that compare your performance to peers using models predictive of consideration and sales. Brand Metrics quantifies the number of customers in the awareness and consideration marketing funnel stages and is built at scale to measure all shopping engagements with your brand on Amazon, not just ad-attributed engagements. Additionally, BM breaks out key shopping engagements at each stage of the shopping journey, along with the Return on Engagement, so you can measure the historical sales following a consideration event or purchase.","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 or a list of metrics from the available metrics in the metrics field. If an empty request body is passed, report for the latest available report date in JSON format will get generated with all the available brands and metrics for an advertiser. The report may or may not contain the Brand Metrics data for one or more brands depending on data availability.\n\n**Requires one of these permissions**:\n[\"advertiser_campaign_edit\",\"nemo_report_edit\"]","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.\n\n**Requires one of these permissions**:\n[\"advertiser_campaign_edit\",\"advertiser_campaign_view\",\"nemo_report_edit\",\"nemo_report_view\"]","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"]}}}}