> ## Documentation Index > Fetch the complete documentation index at: https://promptwatch.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # List Shopping Product Appearances > Paginated list of product appearances captured in AI shopping answers ## OpenAPI ````yaml /v2/openapi.json get /shopping/items openapi: 3.0.0 info: title: Promptwatch API v2 description: >- API v2 for customer integrations with Promptwatch monitoring platform. This version provides improved structure, additional endpoints, and enhanced functionality. version: 2.0.0 contact: name: Promptwatch Support email: team@promptwatch.com url: https://promptwatch.com license: name: Commercial url: https://promptwatch.com/terms-and-conditions servers: - url: https://server.promptwatch.com/api/v2 description: Promptwatch API v2 security: [] tags: - name: Authentication description: API key validation and authentication - name: Content description: >- AI content generation and optimization. Create content asynchronously and poll for results. - name: Content Agent description: >- Content Agent (automated content) lifecycle: project settings, scheduled slots, review (accept/decline), and publish. - name: Content Gap description: Content gap analysis and recommendations - name: Publishing description: >- Publish content to a connected CMS, or record a live URL, and track the published page - name: Models description: Available LLM models - name: Monitors description: Monitor management and CRUD operations - name: Page Tracker description: Track URLs and inspect citation stats, responses, and prompts - name: Prompts description: Prompt management and operations - name: Query Fanouts description: ChatGPT query fanout keywords - name: Responses description: LLM response data and analytics - name: Tags description: Tag management for prompts - name: Topics description: Topic management for prompts - name: Actions description: Action items (GEO suggestions and tasks) - name: Personas description: Persona configuration for monitors - name: Brands description: Brand management for competitive analysis - name: Visibility description: Brand visibility time series and competitor heatmaps - name: Citations description: Citation analytics from AI responses - name: Analytics description: Visitor analytics, AI crawler logs, sentiment, and brand visibility trends - name: Projects description: Project management (organization-level keys only) - name: Sitemap description: Sitemap crawl progress and discovered URLs - name: Site Health description: >- Crawled pages with SEO issues (titles, meta descriptions, H1, thin content) - name: Socials description: >- Social media citations (Reddit posts and YouTube videos) found in LLM responses - name: Ads Radar description: Sponsored ads captured in AI answers - name: Shopping description: Product appearances in AI shopping answers and tracked products paths: /shopping/items: get: tags: - Shopping summary: List Shopping Product Appearances description: Paginated list of product appearances captured in AI shopping answers operationId: listShoppingItems parameters: - schema: type: integer default: 1 minimum: 1 in: query name: page required: false description: Page number (1-based) - schema: type: integer default: 25 minimum: 1 maximum: 100 in: query name: size required: false description: Page size - schema: type: string in: query name: search required: false description: Search within product title or merchants - schema: type: string in: query name: foreignId required: false description: Exact (case-insensitive) product id in the source answer engine - schema: type: string enum: - createdAt - positionInResponse - rating - numReviews default: createdAt in: query name: sortBy required: false description: Field to sort by - schema: type: string enum: - asc - desc default: desc in: query name: sortOrder required: false description: Sort order - schema: type: string format: date-time in: query name: from required: false description: Filter shopping data captured from this date (ISO 8601) - schema: type: string format: date-time in: query name: until required: false description: Filter shopping data captured until this date (ISO 8601) - schema: anyOf: - type: string - type: array items: type: string in: query name: models required: false description: 'Filter by LLM model IDs. Repeat for multiple: models=x&models=y' - schema: anyOf: - type: string enum: - ORGANIC - BRAND_SPECIFIC - COMPETITOR_COMPARISON - type: array items: type: string enum: - ORGANIC - BRAND_SPECIFIC - COMPETITOR_COMPARISON in: query name: promptTypes required: false description: Filter by prompt type. Repeat for multiple values. - schema: anyOf: - type: string enum: - BRANDED - INFORMATIONAL - NAVIGATIONAL - COMMERCIAL - TRANSACTIONAL - type: array items: type: string enum: - BRANDED - INFORMATIONAL - NAVIGATIONAL - COMMERCIAL - TRANSACTIONAL in: query name: intentTypes required: false description: Filter by prompt intent. Repeat for multiple values. responses: '200': description: Default Response content: application/json: schema: type: object properties: items: type: array items: type: object properties: id: type: string format: uuid description: Appearance identifier title: type: string description: Product title as shown in the response description: type: string nullable: true description: Product description as shown in the response priceText: type: string nullable: true description: Displayed price text merchants: type: string nullable: true description: Merchant names shown for the product numReviews: type: integer nullable: true description: Review count shown for the product rating: type: number nullable: true description: Product rating shown in the response featuredTag: type: string nullable: true description: Featured tag label, when highlighted thumbnailUrl: type: string nullable: true description: Product thumbnail URL productUrl: type: string nullable: true description: Product URL normalizedProductUrl: type: string nullable: true description: Normalized product URL productDomain: type: string nullable: true description: Merchant domain of the product URL positionInResponse: type: integer nullable: true description: 0-based position of the product in the response cite: type: string nullable: true description: Citation reference for the product createdAt: type: string format: date-time description: When the appearance was captured priceStats: type: object properties: average: type: string nullable: true description: Average offer price, formatted with currency high: type: string nullable: true description: Highest offer price, formatted with currency low: type: string nullable: true description: Lowest offer price, formatted with currency offerCount: type: integer description: Number of merchant offers with a parseable price required: - average - high - low - offerCount additionalProperties: false shoppingItem: type: object properties: id: type: string format: uuid description: Product identifier source: type: string description: Answer engine the product was extracted from foreignId: type: string description: Product identifier in the source answer engine title: type: string description: Product title required: - id - source - foreignId - title additionalProperties: false response: type: object properties: id: type: string format: uuid description: LLM response identifier model: type: string description: Model that produced the response createdAt: type: string format: date-time description: When the response was captured prompt: type: object properties: id: type: string format: uuid description: Prompt identifier prompt: type: string description: Prompt text type: type: string enum: - ORGANIC - BRAND_SPECIFIC - COMPETITOR_COMPARISON description: Prompt type intent: type: string enum: - BRANDED - INFORMATIONAL - NAVIGATIONAL - COMMERCIAL - TRANSACTIONAL nullable: true description: Prompt intent llmMonitor: type: object properties: id: type: string format: uuid description: Monitor identifier name: type: string description: Monitor name required: - id - name additionalProperties: false required: - id - prompt - type - intent - llmMonitor additionalProperties: false required: - id - model - createdAt - prompt additionalProperties: false required: - id - title - description - priceText - merchants - numReviews - rating - featuredTag - thumbnailUrl - productUrl - normalizedProductUrl - productDomain - positionInResponse - cite - createdAt - priceStats - shoppingItem - response additionalProperties: false description: Product appearances for the current page total: type: integer description: Total items matching the request page: type: integer description: Page number (1-based) size: type: integer description: Page size totalPages: type: integer description: Total pages for this page size required: - items - total - page - size - totalPages additionalProperties: false '400': description: Default Response content: application/json: schema: type: object example: error: Bad Request code: DATE_RANGE_TOO_LARGE message: Date range cannot exceed 90 days properties: error: type: string description: Error label code: type: string description: Optional machine-readable code (e.g. DATE_RANGE_TOO_LARGE) message: type: string description: Reason the request was rejected required: - error - message '401': description: Default Response content: application/json: schema: type: object example: error: Unauthorized message: Missing or invalid X-API-Key header. properties: error: type: string description: Error category (often aligned with HTTP semantics) code: type: string description: Optional machine-readable code message: type: string description: Human-readable explanation details: type: object description: Optional structured detail (e.g. validation) additionalProperties: true required: - error - message additionalProperties: false '402': description: Default Response content: application/json: schema: type: object example: code: SHOPPING_INSIGHTS_PLAN_REQUIRED message: Shopping insights are not available on your current plan properties: code: type: string enum: - SHOPPING_INSIGHTS_PLAN_REQUIRED - SHOPPING_ITEM_NOT_FOUND - SHOPPING_TRACKED_PRODUCT_NOT_FOUND - SHOPPING_TRACKED_PRODUCT_INVALID_INPUT - INTERNAL_ERROR description: Machine-readable error code message: type: string description: Human-readable error message required: - code - message additionalProperties: false '500': description: Default Response content: application/json: schema: type: object example: code: SHOPPING_INSIGHTS_PLAN_REQUIRED message: Shopping insights are not available on your current plan properties: code: type: string enum: - SHOPPING_INSIGHTS_PLAN_REQUIRED - SHOPPING_ITEM_NOT_FOUND - SHOPPING_TRACKED_PRODUCT_NOT_FOUND - SHOPPING_TRACKED_PRODUCT_INVALID_INPUT - INTERNAL_ERROR description: Machine-readable error code message: type: string description: Human-readable error message required: - code - message additionalProperties: false security: - ApiKeyAuth: [] components: securitySchemes: ApiKeyAuth: type: apiKey in: header name: X-API-Key description: >- API key for authentication. Get yours from the Promptwatch dashboard under Settings > API Keys. ````