Analytics API
The Skin Analysis Analytics API provides read-only reporting endpoints for your Skin Analysis experience: traffic, events, segmentation, recommendation effectiveness, hourly activity, retention and individual analyses.
It's scoped by an analytics app key (app_key), not by project_key.
Open the interactive API reference →
The same dashboards are available in Studio. See Analytics.
Base URL
https://api.pulpoar.com/skinai-partner-analytics/v1
Authentication
- Create an API key in Studio and link it to your Skin Analysis projects.
- Send it in the
X-API-Keyheader. - Each request is authorized against the
app_keyin the URL. Use the analytics app key assigned to the Skin Analysis experience you want to report on. - The event catalog (
/v1/events) is public and doesn't need a key.
curl --request GET \
--url 'https://api.pulpoar.com/skinai-partner-analytics/v1/apps/<app_key>/summary?start_date=2026-01-01&end_date=2026-01-31' \
--header 'X-API-Key: <partner-api-key>'
const response = await fetch(
'https://api.pulpoar.com/skinai-partner-analytics/v1/apps/<app_key>/events/onExperienceChange/segments/experience?start_date=2026-01-01&end_date=2026-01-31&limit=20',
{ headers: { 'X-API-Key': '<partner-api-key>' } }
);
const payload = await response.json();
Endpoints
Start with /v1/events to see the supported event keys and segment keys. All other endpoints are under /v1/apps/{app_key}:
| Endpoint | Use it for |
|---|---|
/summary | Headline traffic and engagement metrics for a reporting window |
/timeseries/{metric} | Daily trend of a metric |
/events/{event_key}/timeseries | Daily trend of an event |
/events/{event_key}/segments/{segment_key} | An event broken down by a segment, for example onExperienceChange by experience |
/recommendations/effectiveness | Recommendation views, product tries, product visits and add-to-cart rates |
/activity/hourly | Hourly engagement by day of week |
/retention/loyalty | Returning users |
/retention/slipping-away | Users becoming inactive |
/events | Raw events, newest first, with the partner analytics ID attached |
/diagnoses | One row per skin analysis, with the questionnaire answers and recommendations from the same session |
Event keys match the SDK event names, for example onSkinScoreCalculate.
Reporting windows
Pass start_date and end_date (YYYY-MM-DD) with each request.
- Most endpoints support windows of up to 93 days.
- These endpoints are limited to 31 days:
/events,/diagnoses,/events/{event_key}/segments/{segment_key},/activity/hourlyand/recommendations/effectiveness. /eventsand/diagnosesonly cover about the last three months. Followmeta.next_cursorto page through results.- Retention endpoints accept an optional
as_of_datefor reproducible snapshots.
Rate limits
- 500 requests per 15 minutes per API key.
- Every response includes the
X-RateLimit-Limit,X-RateLimit-RemainingandX-RateLimit-Resetheaders.
Linking events to your users
To read back one user's events or analyses, set a partner analytics ID in the plugin with the #partnerAnalyticsId URL hash or the setPartnerAnalyticsId action. Then filter /events or /diagnoses by partner_analytics_id. Events sent before the ID was set aren't linked.