--- updatedAt: 2026-04-12T09:22:52.000Z --- # Filter for item listing quality metrics This guide explains how to filter item-level listing quality data with the [Item Listing Quality Details](/us-marketplace/reference/itemsdetailsforlisting) API. Use this guide to identify which items need attention and to focus on the specific metrics that affect listing quality, such as content, discoverability, offer quality, ratings, and reviews. It's especially useful when you need to: * Find items with specific listing quality issues * Narrow results by product type or other filterable attributes * Search for a small set of items by SKU, title, condition, or item ID * Limit the number of records returned in each response ## How it works At a high level, filtering listing quality metrics follows this workflow: 1. Call the [Item Listing Quality Details](/us-marketplace/reference/itemsdetailsforlisting) API to retrieve item-level listing quality data. 2. Choose one of these filtering approaches: * **Filters** to narrow results by metric, issue state, category, product type, or score range * **Query fields** to search for specific items by `sku`, `title`, `condition`, or `itemId` 3. Review the returned items and identify which listings need updates. 4. Use the results to prioritize content fixes, discoverability improvements, pricing or offer updates, or review-related follow-up. ## Prerequisites Complete the following before you use the [Item Listing Quality Details](/us-marketplace/reference/itemsdetailsforlisting) API: * Seller or approved Solution Provider access to Walmart Marketplace APIs. * Retrieve API keys (`clientId` and `clientSecret`) from the [Developer Portal ](https://developer.walmart.com/account/generateKey)and use the keys to call Marketplace APIs. * OAuth 2.0 authentication is required to access the Walmart Marketplace APIs. Ensure that you have obtained the necessary credentials and tokens before making API requests. For more information, refer to [OAuth 2.0 authorization](https://developer.walmart.com/us-marketplace/docs/oauth-20-authorization). * Review API throttling guidance for usage limits on this API. # Endpoint ```Text bash POST /v3/insights/items/listingQuality/items ``` # Common scenarios There are two ways to narrow the response: * Use `filters` when you want to return a set of items that match a score range, product type, category, or issue condition. * Use a `query` when you want to inspect an item by either SKU, title, or item ID. ## Option 1: Use `filters` with operators Use the `filters` array in the request body to return the subset of item metrics you want. You can use filters to: * Return items with specific issues * Filter by product type or category * Filter by metric ranges * Return items based on score-related criteria Supported operators in the current guide include: | Operator | Use | | --------- | -------------------------------------------------- | | `equals` | Returns an exact match for the specified value | | `between` | Returns items within a range of two integer values | ### Sample request Use this request body to return items with post-purchase issues for a specific product type: ```curl cURL cURL --request POST \ 'https://marketplace.walmartapis.com/v3/insights/items/listingQuality/items?limit=200' \ --header 'Authorization: Basic ' \ --header 'WM_SEC.ACCESS_TOKEN: ' \ --header 'WM_QOS.CORRELATION_ID: ' \ --header 'WM_SVC.NAME: Walmart Marketplace' \ --header 'Accept: application/json' \ --header 'Content-Type: application/json' \ --data '{ "filters": [ { "field": "viewPostPurchaseItems", "op": "equals", "values": [0] }, { "field": "productType", "op": "equals", "values": ["Music"] } ] }' ``` ```python Python import requests url = "https://marketplace.walmartapis.com/v3/insights/items/listingQuality/items" headers = { "Authorization": "Basic ", "WM_SEC.ACCESS_TOKEN": "", "WM_QOS.CORRELATION_ID": "", "WM_SVC.NAME": "Walmart Marketplace", "Accept": "application/json", "Content-Type": "application/json", } params = { "limit": 200 } payload = { "filters": [ { "field": "viewPostPurchaseItems", "op": "equals", "values": [0] }, { "field": "productType", "op": "equals", "values": ["Music"] } ] } response = requests.post(url, headers=headers, params=params, json=payload, timeout=30) print(response.status_code) print(response.text) ``` ## Modify your code Replace placeholder values with values from your catalog: * Replace `Music` with the product type you want to review. * Update the `field` values only with fields supported by the API schema. * Use `equals` for exact matches. * Use `between` only when the field supports a numeric range. For the complete list of supported filters and field descriptions, see the request body schema in the [Item Listing Quality Details](/us-marketplace/reference/itemsdetailsforlisting) API Reference. ## Option 2: Use a `query` field Use the `query` object when you want to inspect specific items by known identifiers. The current guide supports these query fields: * `sku` * `title` * `condition` * `itemId` ### Sample request: `query` by item ID ```curl cURL cURL --request POST \ 'https://marketplace.walmartapis.com/v3/insights/items/listingQuality/items?limit=200' \ --header 'Authorization: Basic ' \ --header 'WM_SEC.ACCESS_TOKEN: ' \ --header 'WM_QOS.CORRELATION_ID: ' \ --header 'WM_SVC.NAME: Walmart Marketplace' \ --header 'Accept: application/json' \ --header 'Content-Type: application/json' \ --data '{ "query": { "field": "itemId", "value": "916854860" } }' ``` ```python Python import requests url = "https://marketplace.walmartapis.com/v3/insights/items/listingQuality/items" headers = { "Authorization": "Basic ", "WM_SEC.ACCESS_TOKEN": "", "WM_QOS.CORRELATION_ID": "", "WM_SVC.NAME": "Walmart Marketplace", "Accept": "application/json", "Content-Type": "application/json", } params = { "limit": 200 } payload = { "query": { "field": "itemId", "value": "916854860" } } response = requests.post(url, headers=headers, params=params, json=payload, timeout=30) print(response.status_code) print(response.text) ``` ### Sample request: `query` by multiple item IDs ```curl cURL curl --request POST \ 'https://marketplace.walmartapis.com/v3/insights/items/listingQuality/items?limit=200' \ --header 'Authorization: Basic ' \ --header 'WM_SEC.ACCESS_TOKEN: ' \ --header 'WM_QOS.CORRELATION_ID: ' \ --header 'WM_SVC.NAME: Walmart Marketplace' \ --header 'Accept: application/json' \ --header 'Content-Type: application/json' \ --data '{ "query": { "field": "itemId", "value": "916854860,916854862,916854863" } }' ``` ```python Python import requests url = "https://marketplace.walmartapis.com/v3/insights/items/listingQuality/items" headers = { "Authorization": "Basic ", "WM_SEC.ACCESS_TOKEN": "", "WM_QOS.CORRELATION_ID": "", "WM_SVC.NAME": "Walmart Marketplace", "Accept": "application/json", "Content-Type": "application/json", } params = { "limit": 200 } payload = { "query": { "field": "itemId", "value": "916854860,916854862,916854863" } } response = requests.post(url, headers=headers, params=params, json=payload, timeout=30) print(response.status_code) print(response.text) ```
Multiple values are supported for item ID or SKU only, with a maximum of 200 values.
## Modify your code Update the request body with real catalog values: * Set `field` to `sku`, `title`, `condition`, or `itemId`. * Replace `value` with your item identifier or search text. * Use comma-separated values only for supported multi-value fields such as `itemId` or `sku`. ## Limit the number of items returned Use the `limit` query parameter to control how many item records the API returns. The current guide states that if you do not specify a limit, the API returns **200 items per page** by default, and the value cannot be negative. # Rate limits If you submit too many feeds in a short period of time, you may exceed Walmart’s rate limits and receive HTTP 429 (Too Many Requests) responses. For more details on throttling and best practices, refer to the [Rate Limiting Guide](/us-marketplace/docs/rate-limiting). # Next steps After you filter item listing quality metrics, you can continue with these related tasks: * Review the [Insights API overview](/us-marketplace/docs/insights-api-overview) to understand how Listing Quality fits into the broader Insights API set. * Retrieve your overall catalog score with the [Seller Listing Quality Score](/us-marketplace/reference/getlistingqualityscore)API. * Find categories with issues by using the [Get Item Count with Listing Quality Issues](/us-marketplace/reference/getcategorieslist)API. * Review the full endpoint schema and response samples in the [Item Listing Quality Details API reference](/us-marketplace/reference/itemsdetailsforlisting).