> ## Documentation Index > Fetch the complete documentation index at: https://docs.depict.ai/llms.txt > Use this file to discover all available pages before exploring further. # One recommendation surface's performance totals > As the totals route, narrowed to one surface by id, with the surface's current name. An unknown or deleted surface answers 200 with its history (zeros if none) and a null name, never 404. Counts come from storefront events attributed to recommendation carousels; money figures use the shared Depict attribution rule. Read-only; answers from Tinybird analytics. ## OpenAPI ````yaml /api-reference/openapi/lite.json get /recommendation-metrics/surfaces/{surface_id} openapi: 3.1.0 info: title: Search & Merchandising API version: 1.0.0 description: >- REST API behind Depict: Search & Merchandising, the native Shopify app: onboarding, collections, boost & bury, dashboards, A/B testing and multi-store management. Endpoints are served under the /api/lite prefix and are authenticated with the Shopify session token that App Bridge issues to the embedded app. servers: - url: /api/lite security: - ShopifySessionToken: [] paths: /recommendation-metrics/surfaces/{surface_id}: get: summary: One recommendation surface's performance totals description: >- As the totals route, narrowed to one surface by id, with the surface's current name. An unknown or deleted surface answers 200 with its history (zeros if none) and a null name, never 404. Counts come from storefront events attributed to recommendation carousels; money figures use the shared Depict attribution rule. Read-only; answers from Tinybird analytics. operationId: recsMetricsSurface parameters: - schema: type: string description: The surface's `id` (a uuid), not its name. required: true description: The surface's `id` (a uuid), not its name. name: surface_id in: path - schema: type: string description: Lite merchant id, e.g. `shopify-`. required: true description: Lite merchant id, e.g. `shopify-`. name: merchant_id in: query - schema: type: string pattern: ^\d{4}-\d{2}-\d{2}$ example: '2026-09-01' description: First day, inclusive (UTC). required: true description: First day, inclusive (UTC). name: from_date in: query - schema: type: string pattern: ^\d{4}-\d{2}-\d{2}$ example: '2026-09-01' description: Last day, inclusive (UTC). required: true description: Last day, inclusive (UTC). name: to_date in: query - schema: type: string description: >- Restricts to one Shopify market (its market group's members); absent or empty = every market. required: false description: >- Restricts to one Shopify market (its market group's members); absent or empty = every market. name: market_id in: query - schema: type: string pattern: ^[A-Z]{3}$ description: >- Converts the money figures into this currency (the shop's base currency); absent = as summed, null when mixed. required: false description: >- Converts the money figures into this currency (the shop's base currency); absent = as summed, null when mixed. name: currency in: query responses: '200': description: The surface's totals. content: application/json: schema: $ref: '#/components/schemas/RecommendationSurfaceMetricsResponse' '400': description: >- The query, path or body failed the schema; `detail` carries zod's messages. content: application/json: schema: $ref: '#/components/schemas/Detail' '401': description: Not authenticated. content: application/json: schema: $ref: '#/components/schemas/Detail' '403': description: Authenticated, but this identity may not call the API. content: application/json: schema: $ref: '#/components/schemas/Detail' '404': description: Merchant not found for this caller. content: application/json: schema: $ref: '#/components/schemas/Detail' '500': description: Internal error. content: application/json: schema: $ref: '#/components/schemas/Detail' components: schemas: RecommendationSurfaceMetricsResponse: type: object properties: impressions: type: - number - 'null' description: >- Carousels shown (distinct request ids); null where the storefront does not track impressions. clicked_impressions: type: - number - 'null' description: Carousels with at least one click; null whenever impressions is. clicks: type: number description: Product clicks in carousels. ctr: type: - number - 'null' description: clicked_impressions / impressions. attributed_add_to_carts: type: number attributed_orders: type: number attributed_revenue: type: - number - 'null' description: >- In `currency`; null when the window mixes currencies and no `currency` was asked for. currency: type: - string - 'null' revenue_currencies: type: array items: type: string description: Every currency the window's orders were placed in. aov: type: - number - 'null' description: attributed_revenue / attributed_orders. atc_rate: type: - number - 'null' description: attributed_add_to_carts / clicks. purchase_rate: type: - number - 'null' description: attributed_orders / clicks. first_data_at: type: - string - 'null' description: >- When the merchant's first day with a recommendation click or impression began (UTC); null before any. Merchant-wide. surface_id: type: string surface_name: type: - string - 'null' description: >- The surface's current name; null for a deleted or unknown surface, whose history still reads. required: - impressions - clicked_impressions - clicks - ctr - attributed_add_to_carts - attributed_orders - attributed_revenue - currency - revenue_currencies - aov - atc_rate - purchase_rate - first_data_at - surface_id - surface_name Detail: type: object properties: detail: type: string required: - detail description: 'Every 4xx/5xx body: `{detail}`.' securitySchemes: ShopifySessionToken: type: http scheme: bearer bearerFormat: JWT description: >- Shopify App Bridge session token of the embedded Depict: Search & Merchandising app. The shop in the token determines the merchant; merchant_id parameters must belong to that shop. ````