Skip to content
Pomelo Analytics

Getting Started

1. Create a token

Section titled “1. Create a token”

Mode note: API and tenant examples on this page may rely on data that belongs to explicit Extended configuration. The target default baseline remains a stricter audience-measurement setup.

See also: Strict, Extended & Mixed Reports and the Consumer Migration Guide.

Go to Dashboard > Settings > API Access and create a new token.

  • Choose a scope: metrics:read (read access, still plan-gated) or usage:read (usage only)
  • Optionally restrict to specific sites via the allowlist
  • If the active API policy enables tenant access, you can also restrict access to specific tenants through allowedTenantIds
  • Copy the token secret immediately — it is shown only once

Verification is optional and does not block collection. You can start tracking as soon as the script is installed and the site ID is configured.

When creating a site in the dashboard, enter the real hostname where the script will run. Pomelo then asks you to confirm the tracking scope:

  • This hostname only
  • The domain and its subdomains

If the hostname belongs to a shared platform or private suffix such as tenant.github.io or tenant.wixsite.com, Pomelo keeps the site in exact-hostname mode. Tracking starts as soon as the script is installed; DNS verification is optional and only applies to domain-wide sites.

2. Make your first call

Section titled “2. Make your first call”
Terminal window
curl -sS \
  -H "Authorization: Bearer $POMELO_API_TOKEN" \
  -H "X-Request-Id: my-request-123" \
  "https://api.pomeloanalytics.com/v1/me"

3. Query metrics

Section titled “3. Query metrics”

For a marketplace or any multi-tenant app, add tenant_id when your active API policy enables tenant-scoped access and you want a shop-level view. Use site_id alone for the global marketplace view. See Multi-tenant analytics and the Multi-tenant guide.

When you query dimension=tenant, Pomelo returns the stable tenant_id in the row key. Use tenant_slug and tenant_name as display labels only.

Profile-aware analytics responses also expose an availability object. Use it as the backend authority for route class, partial coverage after collection_profile_effective_at, and non-retroactive Extended history.

  • Strict-safe: standard timeseries, standard breakdown, content
  • Mixed: overview, acquisition, actions
  • Advanced / gated: goals/conversions, tenant-scoped timeseries, tenant breakdowns. These reads depend on the plan, tenant API access, and compatible configuration.

On mixed routes, Strict still returns useful data for the strict-safe slice:

  • overview: audience KPIs, top pages, acquisition-lite preview
  • acquisition: channels, host-only referrers, landing pages
  • actions: simple tagged actions (ui.click, outbound.click, file.download, form.submit)

Read a mixed route as one report with a strict-safe core and clearly marked Extended slices. If you are on Strict, the unflagged sections are the full baseline for that report. Use availability.readModel to identify that baseline, then availability.sections to identify the parts that still belong to enriched acquisition or advanced action reporting.

The same reading model applies in the dashboard:

  • Overview stays useful in Strict through KPIs, top pages, and the acquisition-lite preview
  • Audience stays useful in Strict for device, browser, OS, language, and country
  • Acquisition and Actions stay mixed because only their bounded lite/simple slices belong to the baseline
Terminal window
curl -sS \
-G "https://api.pomeloanalytics.com/v1/metrics/timeseries" \
-H "Authorization: Bearer $POMELO_API_TOKEN" \
--data-urlencode "site_id=site_123" \
--data-urlencode "metric=pageviews" \
--data-urlencode "from=2026-02-01" \
--data-urlencode "to=2026-02-28" \
--data-urlencode "interval=day"

4. Query exact CTA and form events

Section titled “4. Query exact CTA and form events”

Plan note: /v1/reports/actions and goal endpoints depend on the active API policy. /v1/reports/actions is now a mixed route family: the strict-safe slice works in Strict, while advanced families still depend on Extended.

If the selected site or requested period does not contain compatible Extended data for an Extended-only family, Pomelo returns HTTP 409. Mixed routes keep returning 200, expose their baseline through availability.readModel, and expose section-level locks through availability.sections.

Use GET /v1/reports/actions when you need exact counts for tagged UI clicks, outbound clicks, file downloads, and form submissions.

Terminal window
curl -sS \
-G "https://api.pomeloanalytics.com/v1/reports/actions" \
-H "Authorization: Bearer $POMELO_API_TOKEN" \
--data-urlencode "site_id=site_123" \
--data-urlencode "from=2026-02-01" \
--data-urlencode "to=2026-02-28" \
--data-urlencode "action_family=outbound" \
--data-urlencode "action_key=outbound::partner:directory"

Use action_key for exact public action queries. If you add a parent data-analytics-scope, Pomelo derives the combined identifier inside that key, for example instrumentation::hero/primary.

If you need broader retrieval than one exact tagged action, fetch the family only via action_family=outbound. The response includes top_targets, which summarizes outbound destinations.

Richer families such as errors, custom, and goal-derived readings remain outside the default Strict envelope.

In other words, Strict supports a simple aggregate action layer, not a full action intelligence surface. No UTM, no campaigns, no goals, no tenant advanced context, and no richer custom-event payloads move back into the default envelope.

See SDK Integration for the HTML tagging rules that produce these dimensions.

5. Using filters

Section titled “5. Using filters”

Pass a JSON object as the filters query parameter to narrow results:

Terminal window
curl -sS \
  -G "https://api.pomeloanalytics.com/v1/metrics/timeseries" \
  -H "Authorization: Bearer $POMELO_API_TOKEN" \
  --data-urlencode "site_id=site_123" \
  --data-urlencode "metric=pageviews" \
  --data-urlencode "from=2026-02-01" \
  --data-urlencode "to=2026-02-28" \
  --data-urlencode 'filters={"device":"mobile","referrer":"google.com"}'

Available filter keys: device, referrer, page, browser, os.

6. Response headers

Section titled “6. Response headers”

Every response includes these headers:

HeaderDescription
X-Request-IdUnique request identifier — include it in support requests
X-RateLimit-LimitMaximum requests allowed in the current window
X-RateLimit-RemainingRequests remaining before throttling
X-RateLimit-ResetUnix timestamp when the rate limit window resets

Next steps

Section titled “Next steps”