Analytics Exports and Reconciliation

Use this guide to query analytics, export data, and understand how metrics are calculated and aggregated.

When to use

• You want to export click or conversion data for reporting.
• You need to understand what a metric means and how it is calculated.
• You want to know why analytics numbers may differ from other sources.

Available dimensions

Metric definitions

Freshness

Analytics are aggregated from CloudFront real-time logs. The target latency is under 60 minutes.

Each response includes a freshness block:

{
  "freshness": {
    "status": "FRESH",
    "lastUpdatedAt": "2026-02-25T12:05:00Z",
    "slaMinutes": 60
  }
}

Confidence score

When ?confidence=true is passed, the response includes a confidence score (0-100) based on:

• Whether any clicks exist
• Whether conversions exceed clicks (anomaly)
• Bot traffic ratio
• Data staleness

Higher scores indicate more reliable data.

UI path

1. Open https://app.{PUBLIC_DOMAIN}.
2. Navigate to your handle and open Analytics.
3. Choose a dimension (slug, country, device, referrer, segment).
4. Optionally filter by date range or campaign.
5. Use the Export button to download CSV or JSON.

Required auth

• CREATOR-level JWT or above to query analytics.
• PAT with analytics.* scope for automation.
• PRO or ENTERPRISE plan required for exports (exports feature gate).

API fallback

Query analytics

GET /v2/handles/{handle}/analytics

Query parameters:

• groupBy (required): day, slug, country, device, referrer, segment
• fromDay, toDay (optional): Date range in yyyymmdd format
• campaignId (optional): Filter to a specific campaign
• slug (optional): Filter to a specific link
• confidence (optional): Include confidence score
• funnel (optional): Include funnel metrics
• sort (optional): asc or desc

Export analytics

GET /v2/handles/{handle}/analytics/export

Query parameters:

• format: json or csv
• groupBy: Same options as above
• fromDay, toDay: Date range
• campaignId: Optional campaign filter

Requires PRO or ENTERPRISE plan.

Submit a conversion

POST /v2/public/conversions

{
  "ctx": "signed_context_token",
  "eventType": "conversion",
  "idempotencyKey": "unique_key",
  "value": 99.99,
  "currency": "USD"
}

The ctx token is minted at redirect time and must be submitted within its TTL (default 15 minutes). Duplicate submissions with the same idempotencyKey are safely deduplicated.

Rate limit: 120 conversions per IP per hour.

Reconciliation notes

• Click counts come from CloudFront logs, not from application-level records. This means analytics reflect actual network-level redirect events.
• Dimension rollups are forward-only. Country, device, and referrer breakdowns are only available from the date dimension tracking was enabled.
• Conversions require a valid ctx token. If the context token has expired, the conversion cannot be attributed. This means total clicks will typically be higher than attributable conversions.
• Duplicate conversions are deduplicated by idempotency key. Replaying the same conversion does not double-count.
• Bot detection filters known user agents but cannot catch all automated traffic. The botClicks metric provides transparency.
• Rollup counts are approximate. The at-least-once delivery model means occasional recounts during retries.

Common errors

Related:

• Smart Link Personalization
• Plans, Quotas, and Feature Gates
• API Endpoint Coverage Map