{"openapi":"3.0.3","info":{"title":"SkinAI Partner Analytics API","version":"1.0.0","description":"## Overview\n\nThe SkinAI Partner Analytics API provides explicit, product-oriented analytics for authorized SkinAI experiences.\n\nThe public contract is resource-based and built around the actual analytics primitives stored in the analytics database: traffic, event activity, segmentation, recommendation effectiveness, hourly activity, and retention.\n\n## Authentication\n\nAll app-scoped analytics endpoints require the `X-API-Key` header. The event catalog is public.\n\n## Authorization Model\n\nA partner API key can be linked to one or more SkinAI projects. Every app-scoped analytics request must include an `app_key` path parameter, and the request is authorized only when that `app_key` belongs to a project linked to the provided API key.\n\n## Reporting Window\n\nDate-based routes require `start_date` and `end_date` in `YYYY-MM-DD` format.\n\nStandard routes support windows up to 93 days.\n\nHigh-cost exact routes are limited to 31 days: `events` (raw event list), `events/*/segments/*`, `activity/hourly`, and `recommendations/effectiveness`.\n\nRetention routes support an optional `as_of_date` parameter for reproducible reporting snapshots."},"servers":[{"url":"{base_url}/skinai-partner-analytics","description":"API Server","variables":{"base_url":{"default":"https://api.pulpoar.com","description":"Base URL for the API"}}}],"security":[{"ApiKeyAuth":[]}],"tags":[{"name":"Health","description":"Service health endpoints"},{"name":"Catalog","description":"Public event catalog for SkinAI analytics events"},{"name":"Summary","description":"Headline traffic and engagement metrics for a date range"},{"name":"Time Series","description":"Daily traffic metrics and event activity over time"},{"name":"Events","description":"Event-level analytics and segmentation"},{"name":"Recommendations","description":"Recommendation effectiveness metrics for SkinAI journeys"},{"name":"Activity","description":"Hourly activity distribution by day of week and hour"},{"name":"Retention","description":"User loyalty and slipping-away retention reports"}],"paths":{"/v1/health":{"get":{"operationId":"get-skinai-partner-analytics-health","summary":"Health Check","tags":["Health"],"security":[],"responses":{"200":{"description":"Analytics endpoint health status","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HealthResponse"}}}}}}},"/v1/events":{"get":{"operationId":"get-skinai-partner-event-catalog","summary":"Get Event Catalog","description":"Returns the public SkinAI event catalog with event descriptions, categories, and supported segmentation keys.","tags":["Catalog"],"security":[],"responses":{"200":{"description":"SkinAI event catalog","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EventCatalogResponse"}}}}}}},"/v1/apps/{app_key}/summary":{"get":{"operationId":"get-skinai-partner-summary","summary":"Get Summary","description":"Returns headline traffic and engagement metrics for the requested app and date range.","tags":["Summary"],"parameters":[{"$ref":"#/components/parameters/AppKey"},{"$ref":"#/components/parameters/StartDate"},{"$ref":"#/components/parameters/EndDate"}],"responses":{"200":{"description":"Summary analytics payload","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SummaryResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/DataUnavailable"},"429":{"$ref":"#/components/responses/RateLimited"},"502":{"$ref":"#/components/responses/ProviderError"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/apps/{app_key}/timeseries/{metric}":{"get":{"operationId":"get-skinai-partner-metric-time-series","summary":"Get Metric Time Series","description":"Returns daily time-series points for an explicit traffic metric.","tags":["Time Series"],"parameters":[{"$ref":"#/components/parameters/AppKey"},{"$ref":"#/components/parameters/TimeSeriesMetric"},{"$ref":"#/components/parameters/StartDate"},{"$ref":"#/components/parameters/EndDate"}],"responses":{"200":{"description":"Metric time-series analytics","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MetricTimeSeriesResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/DataUnavailable"},"429":{"$ref":"#/components/responses/RateLimited"},"502":{"$ref":"#/components/responses/ProviderError"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/apps/{app_key}/events/{event_key}/timeseries":{"get":{"operationId":"get-skinai-partner-event-time-series","summary":"Get Event Time Series","description":"Returns daily event and user counts for a supported SkinAI event key.","tags":["Events","Time Series"],"parameters":[{"$ref":"#/components/parameters/AppKey"},{"$ref":"#/components/parameters/EventKey"},{"$ref":"#/components/parameters/StartDate"},{"$ref":"#/components/parameters/EndDate"}],"responses":{"200":{"description":"Event activity time-series analytics","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EventTimeSeriesResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/DataUnavailable"},"429":{"$ref":"#/components/responses/RateLimited"},"502":{"$ref":"#/components/responses/ProviderError"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/apps/{app_key}/events/{event_key}/segments/{segment_key}":{"get":{"operationId":"get-skinai-partner-event-segmentation","summary":"Get Event Segmentation","description":"Returns event counts and user counts grouped by a requested event segmentation key. This route is limited to 31 days.","tags":["Events"],"parameters":[{"$ref":"#/components/parameters/AppKey"},{"$ref":"#/components/parameters/EventSegmentationEventKey"},{"$ref":"#/components/parameters/EventSegmentationSegmentKey"},{"$ref":"#/components/parameters/StartDate"},{"$ref":"#/components/parameters/EndDate"},{"$ref":"#/components/parameters/BreakdownLimit"}],"responses":{"200":{"description":"Event segmentation analytics","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EventSegmentationResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/DataUnavailable"},"429":{"$ref":"#/components/responses/RateLimited"},"502":{"$ref":"#/components/responses/ProviderError"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/apps/{app_key}/activity/hourly":{"get":{"operationId":"get-skinai-partner-hourly-activity","summary":"Get Hourly Activity","description":"Returns hourly event and user counts grouped by day of week and hour of day. This route is limited to 31 days.","tags":["Activity"],"parameters":[{"$ref":"#/components/parameters/AppKey"},{"$ref":"#/components/parameters/StartDate"},{"$ref":"#/components/parameters/EndDate"}],"responses":{"200":{"description":"Hourly activity analytics","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HourlyActivityResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/DataUnavailable"},"429":{"$ref":"#/components/responses/RateLimited"},"502":{"$ref":"#/components/responses/ProviderError"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/apps/{app_key}/retention/loyalty":{"get":{"operationId":"get-skinai-partner-user-loyalty","summary":"Get User Loyalty","description":"Returns user loyalty buckets for all-time, last-7-day, and last-30-day windows.","tags":["Retention"],"parameters":[{"$ref":"#/components/parameters/AppKey"},{"$ref":"#/components/parameters/AsOfDate"}],"responses":{"200":{"description":"User loyalty analytics","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserLoyaltyResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/DataUnavailable"},"429":{"$ref":"#/components/responses/RateLimited"},"502":{"$ref":"#/components/responses/ProviderError"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/apps/{app_key}/retention/slipping-away":{"get":{"operationId":"get-skinai-partner-slipping-away","summary":"Get Slipping Away","description":"Returns slipping-away cohorts using the requested as-of date.","tags":["Retention"],"parameters":[{"$ref":"#/components/parameters/AppKey"},{"$ref":"#/components/parameters/AsOfDate"}],"responses":{"200":{"description":"Slipping-away retention analytics","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SlippingAwayResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/DataUnavailable"},"429":{"$ref":"#/components/responses/RateLimited"},"502":{"$ref":"#/components/responses/ProviderError"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/apps/{app_key}/recommendations/effectiveness":{"get":{"operationId":"get-skinai-partner-recommendation-effectiveness","summary":"Get Recommendation Effectiveness","description":"Returns recommendation journey totals and rates for recommendation exposure, engagement, product try, go-to-product, and add-to-cart activity. This route is limited to 31 days.","tags":["Recommendations"],"parameters":[{"$ref":"#/components/parameters/AppKey"},{"$ref":"#/components/parameters/StartDate"},{"$ref":"#/components/parameters/EndDate"}],"responses":{"200":{"description":"Recommendation effectiveness analytics","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RecommendationEffectivenessResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/DataUnavailable"},"429":{"$ref":"#/components/responses/RateLimited"},"502":{"$ref":"#/components/responses/ProviderError"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/apps/{app_key}/events":{"get":{"operationId":"get-skinai-partner-events","summary":"List Events","description":"Returns raw events newest first, one row per event, with the `partner_analytics_id` the plugin attached (or `null`). Filter by `partner_analytics_id` to read back one partner user's events. Follow `meta.next_cursor` with the same filters until it is `null`. Limited to 31 days inside the raw retention window (about 3 complete months plus the current month); older ranges return 422. Events sent before the id was set are not linked. `onQuestionnaireComplete` answers come with the question and answer text from the current Studio quiz (`null` once deleted). `onSkinScoreCalculate` carries the `analysisId` also sent in the SDK event. Product and routine ids are internal and can change; each comes with its slug (your SKU), e.g. `product_id` + `product_slug`, `productIds` + `productSlugs` in the same order. The slug is the one recorded when the event happened, else the current catalog slug, else `null` (no longer in this app's catalog). Match on the slug, case-insensitively.","tags":["Events"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"$ref":"#/components/parameters/AppKey"},{"$ref":"#/components/parameters/StartDate"},{"$ref":"#/components/parameters/EndDate"},{"name":"event_key","in":"query","required":false,"schema":{"type":"string","enum":["onReady","onPathChange","onOnboardingCarouselChange","onPhotoUse","onPhotoRetake","onSkinScoreCalculate","onCameraPermissionDeny","onQuestionnaireComplete","onExperienceChange","onProblemChipClick","onRecommendationsReceive","onProductTryClick","onProductVisit","onAISimulatorAdjust","onAddToCart","onEmailButtonClick","onEmailSend"],"example":"onSkinScoreCalculate"}},{"name":"partner_analytics_id","in":"query","required":false,"description":"Exact match on the id passed via `#partnerAnalyticsId=` or `setPartnerAnalyticsId`.","schema":{"type":"string","pattern":"^[A-Za-z0-9._-]{1,128}$","example":"acct_12345"}},{"name":"cursor","in":"query","required":false,"description":"Opaque value from `meta.next_cursor` of the previous page.","schema":{"type":"string","maxLength":1024}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":1000,"default":100}}],"responses":{"200":{"description":"A page of raw events","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EventListResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/DataUnavailable"},"429":{"$ref":"#/components/responses/RateLimited"},"502":{"$ref":"#/components/responses/ProviderError"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/apps/{app_key}/diagnoses":{"get":{"operationId":"get-skinai-partner-diagnoses","summary":"List Diagnoses","description":"Returns one row per skin analysis (`onSkinScoreCalculate`), newest first, with the quiz answers and recommendations of the same session already attached: the latest quiz at or before the analysis (a retake reuses it) and the recommendations nearest to it. `questionnaire` is `null` when no quiz was taken, and labels come from the current Studio quiz (`null` once deleted). Same filters, paging, 31-day limit and retention window as `GET /v1/apps/{app_key}/events`.","tags":["Events"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"$ref":"#/components/parameters/AppKey"},{"$ref":"#/components/parameters/StartDate"},{"$ref":"#/components/parameters/EndDate"},{"name":"partner_analytics_id","in":"query","required":false,"description":"Exact match on the id passed via `#partnerAnalyticsId=` or `setPartnerAnalyticsId`.","schema":{"type":"string","pattern":"^[A-Za-z0-9._-]{1,128}$","example":"acct_12345"}},{"name":"cursor","in":"query","required":false,"description":"Opaque value from `meta.next_cursor` of the previous page.","schema":{"type":"string","maxLength":1024}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":1000,"default":100}}],"responses":{"200":{"description":"A page of diagnoses","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DiagnosisListResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/DataUnavailable"},"429":{"$ref":"#/components/responses/RateLimited"},"502":{"$ref":"#/components/responses/ProviderError"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}}},"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-Key","description":"Partner API key linked to one or more SkinAI projects."}},"parameters":{"AppKey":{"name":"app_key","in":"path","required":true,"schema":{"type":"string","minLength":48,"maxLength":48,"pattern":"^[a-f0-9]{48}$","example":"0123456789abcdef0123456789abcdef0123456789abcdef"}},"StartDate":{"name":"start_date","in":"query","required":true,"schema":{"type":"string","format":"date","example":"2026-01-01"}},"EndDate":{"name":"end_date","in":"query","required":true,"schema":{"type":"string","format":"date","example":"2026-01-31"}},"AsOfDate":{"name":"as_of_date","in":"query","required":false,"schema":{"type":"string","format":"date","example":"2026-01-31"}},"TimeSeriesMetric":{"name":"metric","in":"path","required":true,"schema":{"type":"string","enum":["sessions","users","new_users","events","avg_session_duration_seconds"],"example":"sessions"}},"EventKey":{"name":"event_key","in":"path","required":true,"schema":{"type":"string","enum":["onReady","onPathChange","onOnboardingCarouselChange","onPhotoUse","onPhotoRetake","onSkinScoreCalculate","onCameraPermissionDeny","onQuestionnaireComplete","onExperienceChange","onProblemChipClick","onRecommendationsReceive","onProductTryClick","onProductVisit","onAISimulatorAdjust","onAddToCart","onEmailButtonClick","onEmailSend"],"example":"onReady"}},"EventSegmentationEventKey":{"name":"event_key","in":"path","required":true,"description":"Supported event keys are listed by `GET /v1/events`. The segmentation example pair here is `onExperienceChange` + `experience`.","schema":{"type":"string","enum":["onReady","onPathChange","onOnboardingCarouselChange","onSkinScoreCalculate","onQuestionnaireComplete","onExperienceChange","onProblemChipClick","onRecommendationsReceive","onProductTryClick","onProductVisit","onAISimulatorAdjust","onAddToCart","onEmailButtonClick","onEmailSend"],"example":"onExperienceChange"}},"EventSegmentationSegmentKey":{"name":"segment_key","in":"path","required":true,"description":"Valid segment keys depend on `event_key`. Use `GET /v1/events` to discover supported combinations for a given event.","schema":{"type":"string","minLength":1,"maxLength":128,"example":"experience"}},"BreakdownLimit":{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":20}}},"responses":{"BadRequest":{"description":"Request validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Unauthorized":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Forbidden":{"description":"The API key is valid but does not have access to the requested app key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"DataUnavailable":{"description":"Raw analytics data is unavailable for part of the requested date range","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"RateLimited":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"ProviderError":{"description":"Analytics ingest provider failed to fulfill the request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"ServiceUnavailable":{"description":"Analytics ingest is not configured","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"schemas":{"PartnerEvent":{"type":"object","required":["event_id","event_key","created_at","session_id","partner_analytics_id","device_type","os","country_code","properties"],"properties":{"event_id":{"type":"string"},"event_key":{"type":"string","example":"onSkinScoreCalculate"},"created_at":{"type":"string","format":"date-time","example":"2026-10-20T14:03:11.482Z"},"session_id":{"type":"string","nullable":true},"partner_analytics_id":{"type":"string","nullable":true,"example":"acct_12345"},"device_type":{"type":"string","nullable":true,"example":"mobile"},"os":{"type":"string","nullable":true,"example":"iOS"},"country_code":{"type":"string","nullable":true,"example":"BR"},"properties":{"type":"object","additionalProperties":true,"description":"Documented segmentation keys of the event, as listed by `GET /v1/events`."}}},"EventListResponse":{"type":"object","required":["meta","data"],"properties":{"meta":{"allOf":[{"$ref":"#/components/schemas/RangeMeta"},{"type":"object","required":["event_key","partner_analytics_id","limit","next_cursor"],"properties":{"event_key":{"type":"string","nullable":true},"partner_analytics_id":{"type":"string","nullable":true},"limit":{"type":"integer"},"next_cursor":{"type":"string","nullable":true}}}]},"data":{"type":"object","required":["events"],"properties":{"events":{"type":"array","items":{"$ref":"#/components/schemas/PartnerEvent"}}}}}},"Diagnosis":{"type":"object","required":["analysis_id","created_at","session_id","partner_analytics_id","device_type","os","country_code","skin_health_score","is_selfie","issues","questionnaire","product_ids","product_slugs","routine_ids","routine_slugs"],"properties":{"analysis_id":{"type":"string","nullable":true,"description":"Same `analysisId` as the SDK event."},"created_at":{"type":"string","format":"date-time","example":"2026-10-20T14:03:11.482Z"},"session_id":{"type":"string","nullable":true},"partner_analytics_id":{"type":"string","nullable":true,"example":"acct_12345"},"device_type":{"type":"string","nullable":true,"example":"mobile"},"os":{"type":"string","nullable":true,"example":"iOS"},"country_code":{"type":"string","nullable":true,"example":"BR"},"skin_health_score":{"type":"number","nullable":true,"example":72},"is_selfie":{"type":"boolean","nullable":true},"issues":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"score":{"type":"number"}}}},"questionnaire":{"type":"array","nullable":true,"items":{"type":"object","properties":{"questionId":{"type":"string"},"question":{"type":"string","nullable":true,"example":"What is your skin type?"},"answerIds":{"type":"array","items":{"type":"string"}},"answers":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"label":{"type":"string","nullable":true,"example":"Oily"}}}}}}},"product_ids":{"type":"array","items":{"type":"string"},"description":"Internal ids; match on `product_slugs`."},"product_slugs":{"type":"array","items":{"type":"string","nullable":true},"description":"Your product slug (SKU) per `product_ids` entry, same order: recorded at analysis time, else the current catalog slug, else `null`."},"routine_ids":{"type":"array","items":{"type":"string"}},"routine_slugs":{"type":"array","items":{"type":"string","nullable":true},"description":"Your routine slug per `routine_ids` entry, same order: recorded at analysis time, else the current catalog slug, else `null`."}}},"DiagnosisListResponse":{"type":"object","required":["meta","data"],"properties":{"meta":{"allOf":[{"$ref":"#/components/schemas/RangeMeta"},{"type":"object","required":["partner_analytics_id","limit","next_cursor"],"properties":{"partner_analytics_id":{"type":"string","nullable":true},"limit":{"type":"integer"},"next_cursor":{"type":"string","nullable":true}}}]},"data":{"type":"object","required":["diagnoses"],"properties":{"diagnoses":{"type":"array","items":{"$ref":"#/components/schemas/Diagnosis"}}}}}},"HealthResponse":{"type":"object","required":["status","timestamp","analytics_backend"],"properties":{"status":{"type":"string","example":"healthy"},"timestamp":{"type":"string","format":"date-time"},"analytics_backend":{"type":"string","enum":["postgres","unconfigured"]}}},"ErrorResponse":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"array","items":{"type":"string"}},"data_available_from":{"type":"string","format":"date","description":"Earliest date for which the required raw analytics data is available"},"parent_table":{"type":"string","description":"Raw analytics source that limits the requested range","example":"analytics.sessions"},"retry_after":{"type":"integer","minimum":0},"valid_values":{"type":"array","items":{"type":"string"}}}}}},"DataState":{"type":"string","enum":["empty","ready"]},"AnalyticsRange":{"type":"object","required":["start_date","end_date"],"properties":{"start_date":{"type":"string","format":"date","example":"2026-01-01"},"end_date":{"type":"string","format":"date","example":"2026-01-31"}}},"RangeMeta":{"type":"object","required":["app_key","generated_at","data_state","range"],"properties":{"app_key":{"type":"string","example":"0123456789abcdef0123456789abcdef0123456789abcdef"},"generated_at":{"type":"string","format":"date-time"},"data_state":{"$ref":"#/components/schemas/DataState"},"range":{"$ref":"#/components/schemas/AnalyticsRange"}}},"AsOfMeta":{"type":"object","required":["app_key","generated_at","data_state","as_of_date"],"properties":{"app_key":{"type":"string","example":"0123456789abcdef0123456789abcdef0123456789abcdef"},"generated_at":{"type":"string","format":"date-time"},"data_state":{"$ref":"#/components/schemas/DataState"},"as_of_date":{"type":"string","format":"date","example":"2026-01-31"}}},"EventCatalogItem":{"type":"object","required":["event_key","category","description","segmentation_keys"],"properties":{"event_key":{"type":"string","enum":["onReady","onPathChange","onOnboardingCarouselChange","onPhotoUse","onPhotoRetake","onSkinScoreCalculate","onCameraPermissionDeny","onQuestionnaireComplete","onExperienceChange","onProblemChipClick","onRecommendationsReceive","onProductTryClick","onProductVisit","onAISimulatorAdjust","onAddToCart","onEmailButtonClick","onEmailSend"]},"category":{"type":"string"},"description":{"type":"string"},"segmentation_keys":{"type":"array","items":{"type":"string"}}}},"EventCategoryItem":{"type":"object","required":["category_key","event_keys"],"properties":{"category_key":{"type":"string"},"event_keys":{"type":"array","items":{"type":"string","enum":["onReady","onPathChange","onOnboardingCarouselChange","onPhotoUse","onPhotoRetake","onSkinScoreCalculate","onCameraPermissionDeny","onQuestionnaireComplete","onExperienceChange","onProblemChipClick","onRecommendationsReceive","onProductTryClick","onProductVisit","onAISimulatorAdjust","onAddToCart","onEmailButtonClick","onEmailSend"]}}}},"SummaryData":{"type":"object","required":["traffic","engagement"],"properties":{"traffic":{"type":"object","required":["sessions","users","new_users"],"properties":{"sessions":{"type":"integer","minimum":0},"users":{"type":"integer","minimum":0},"new_users":{"type":"integer","minimum":0}}},"engagement":{"type":"object","required":["avg_session_duration_seconds"],"properties":{"avg_session_duration_seconds":{"type":"number","minimum":0}}}}},"MetricPoint":{"type":"object","required":["date","value"],"properties":{"date":{"type":"string","format":"date"},"value":{"type":"number","minimum":0}}},"EventMetricPoint":{"type":"object","required":["date","event_count","user_count"],"properties":{"date":{"type":"string","format":"date"},"event_count":{"type":"integer","minimum":0},"user_count":{"type":"integer","minimum":0}}},"EventSegmentationItem":{"type":"object","required":["value","event_count","user_count"],"properties":{"value":{"type":"string"},"event_count":{"type":"integer","minimum":0},"user_count":{"type":"integer","minimum":0}}},"HourlyActivityPoint":{"type":"object","required":["day_of_week","hour_of_day","event_count","user_count"],"properties":{"day_of_week":{"type":"integer","minimum":0,"maximum":6},"hour_of_day":{"type":"integer","minimum":0,"maximum":23},"event_count":{"type":"integer","minimum":0},"user_count":{"type":"integer","minimum":0}}},"UserLoyaltyBucket":{"type":"object","required":["bucket","user_count","index"],"properties":{"bucket":{"type":"string"},"user_count":{"type":"integer","minimum":0},"index":{"type":"integer","minimum":0}}},"SlippingAwayPoint":{"type":"object","required":["period_days","user_count","percentage"],"properties":{"period_days":{"type":"integer","minimum":0},"user_count":{"type":"integer","minimum":0},"percentage":{"type":"number","minimum":0}}},"RecommendationEffectivenessData":{"type":"object","required":["attribution_model","totals","rates"],"properties":{"attribution_model":{"type":"string"},"totals":{"type":"object","required":["recommendation_sessions","recommendation_users","total_recommendation_events","engaged_sessions","engaged_users","product_try_sessions","go_to_product_sessions","add_to_cart_sessions"],"properties":{"recommendation_sessions":{"type":"integer","minimum":0},"recommendation_users":{"type":"integer","minimum":0},"total_recommendation_events":{"type":"integer","minimum":0},"engaged_sessions":{"type":"integer","minimum":0},"engaged_users":{"type":"integer","minimum":0},"product_try_sessions":{"type":"integer","minimum":0},"go_to_product_sessions":{"type":"integer","minimum":0},"add_to_cart_sessions":{"type":"integer","minimum":0}}},"rates":{"type":"object","required":["engaged_session_rate","product_try_session_rate","go_to_product_session_rate","add_to_cart_session_rate"],"properties":{"engaged_session_rate":{"type":"number","minimum":0},"product_try_session_rate":{"type":"number","minimum":0},"go_to_product_session_rate":{"type":"number","minimum":0},"add_to_cart_session_rate":{"type":"number","minimum":0}}}}},"EventCatalogResponse":{"type":"object","required":["meta","data"],"properties":{"meta":{"type":"object","required":["generated_at","total_events"],"properties":{"generated_at":{"type":"string","format":"date-time"},"total_events":{"type":"integer","minimum":0}}},"data":{"type":"object","required":["total_events","events","categories"],"properties":{"total_events":{"type":"integer","minimum":0},"events":{"type":"array","items":{"$ref":"#/components/schemas/EventCatalogItem"}},"categories":{"type":"array","items":{"$ref":"#/components/schemas/EventCategoryItem"}}}}}},"SummaryResponse":{"type":"object","required":["meta","data"],"properties":{"meta":{"$ref":"#/components/schemas/RangeMeta"},"data":{"$ref":"#/components/schemas/SummaryData"}}},"MetricTimeSeriesResponse":{"type":"object","required":["meta","data"],"properties":{"meta":{"allOf":[{"$ref":"#/components/schemas/RangeMeta"},{"type":"object","required":["metric"],"properties":{"metric":{"type":"string","enum":["sessions","users","new_users","events","avg_session_duration_seconds"]}}}]},"data":{"type":"object","required":["points"],"properties":{"points":{"type":"array","items":{"$ref":"#/components/schemas/MetricPoint"}}}}}},"EventTimeSeriesResponse":{"type":"object","required":["meta","data"],"properties":{"meta":{"allOf":[{"$ref":"#/components/schemas/RangeMeta"},{"type":"object","required":["event_key"],"properties":{"event_key":{"type":"string","enum":["onReady","onPathChange","onOnboardingCarouselChange","onPhotoUse","onPhotoRetake","onSkinScoreCalculate","onCameraPermissionDeny","onQuestionnaireComplete","onExperienceChange","onProblemChipClick","onRecommendationsReceive","onProductTryClick","onProductVisit","onAISimulatorAdjust","onAddToCart","onEmailButtonClick","onEmailSend"]}}}]},"data":{"type":"object","required":["points"],"properties":{"points":{"type":"array","items":{"$ref":"#/components/schemas/EventMetricPoint"}}}}}},"EventSegmentationResponse":{"type":"object","required":["meta","data"],"properties":{"meta":{"allOf":[{"$ref":"#/components/schemas/RangeMeta"},{"type":"object","required":["event_key","segment_key","limit"],"properties":{"event_key":{"type":"string","enum":["onReady","onPathChange","onOnboardingCarouselChange","onPhotoUse","onPhotoRetake","onSkinScoreCalculate","onCameraPermissionDeny","onQuestionnaireComplete","onExperienceChange","onProblemChipClick","onRecommendationsReceive","onProductTryClick","onProductVisit","onAISimulatorAdjust","onAddToCart","onEmailButtonClick","onEmailSend"]},"segment_key":{"type":"string"},"limit":{"type":"integer","minimum":1,"maximum":100}}}]},"data":{"type":"object","required":["items"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/EventSegmentationItem"}}}}}},"HourlyActivityResponse":{"type":"object","required":["meta","data"],"properties":{"meta":{"$ref":"#/components/schemas/RangeMeta"},"data":{"type":"object","required":["points"],"properties":{"points":{"type":"array","items":{"$ref":"#/components/schemas/HourlyActivityPoint"}}}}}},"UserLoyaltyResponse":{"type":"object","required":["meta","data"],"properties":{"meta":{"$ref":"#/components/schemas/AsOfMeta"},"data":{"type":"object","required":["all_time","last_7_days","last_30_days"],"properties":{"all_time":{"type":"array","items":{"$ref":"#/components/schemas/UserLoyaltyBucket"}},"last_7_days":{"type":"array","items":{"$ref":"#/components/schemas/UserLoyaltyBucket"}},"last_30_days":{"type":"array","items":{"$ref":"#/components/schemas/UserLoyaltyBucket"}}}}}},"SlippingAwayResponse":{"type":"object","required":["meta","data"],"properties":{"meta":{"$ref":"#/components/schemas/AsOfMeta"},"data":{"type":"object","required":["points"],"properties":{"points":{"type":"array","items":{"$ref":"#/components/schemas/SlippingAwayPoint"}}}}}},"RecommendationEffectivenessResponse":{"type":"object","required":["meta","data"],"properties":{"meta":{"$ref":"#/components/schemas/RangeMeta"},"data":{"$ref":"#/components/schemas/RecommendationEffectivenessData"}}}}}}