Skip to main content

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 →

Prefer no code?

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-Key header.
  • Each request is authorized against the app_key in 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}:

EndpointUse it for
/summaryHeadline traffic and engagement metrics for a reporting window
/timeseries/{metric}Daily trend of a metric
/events/{event_key}/timeseriesDaily trend of an event
/events/{event_key}/segments/{segment_key}An event broken down by a segment, for example onExperienceChange by experience
/recommendations/effectivenessRecommendation views, product tries, product visits and add-to-cart rates
/activity/hourlyHourly engagement by day of week
/retention/loyaltyReturning users
/retention/slipping-awayUsers becoming inactive
/eventsRaw events, newest first, with the partner analytics ID attached
/diagnosesOne 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/hourly and /recommendations/effectiveness.
  • /events and /diagnoses only cover about the last three months. Follow meta.next_cursor to page through results.
  • Retention endpoints accept an optional as_of_date for reproducible snapshots.

Rate limits​

  • 500 requests per 15 minutes per API key.
  • Every response includes the X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset headers.

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.

Downloads​