Tracker Analytics

The Tracker Analytics API helps you monitor and analyze user interaction patterns through comprehensive tracking data and performance metrics for your marketing campaigns.

What is the Tracker Analytics API? Copied

The Tracker Analytics API is like having a detailed activity monitor for your website interactions. It gives you deep insights into how users engage with your tracked elements, from button clicks to page scrolls, helping you understand user behavior patterns and optimize your conversion funnels.

Why is Tracker Analytics useful? Copied

Tracker analytics bridges raw interaction data with actionable insights, helping businesses optimize user experience and improve conversion rates through data-driven decisions.

• Marketing Teams: Track campaign performance across different user touchpoints and identify high-converting interaction patterns.

• Product Teams: Understand user behavior flows and optimize UI elements based on actual usage data.

• Analytics Teams: Access granular event data for deep-dive analysis and custom reporting dashboards.

The API works continuously in the background, capturing every tracked interaction and providing both real-time event data and aggregated performance metrics.

How does it work? Copied

The API provides comprehensive tracking insights through two main capabilities: detailed instance tracking for granular event analysis and aggregated analytics for performance monitoring. You can track everything from individual user interactions to campaign-wide performance trends.

• What It Tracks: User interactions, campaign performance, engagement rates, and behavior patterns across all your tracked elements including page views, clicks, scrolling, and time spent.

• Example: See that your product page had 347 interactions from 208 unique users this week, with average scroll depth of 75% and 3.2 minutes average session time.

• Access Patterns: Raw instance data for detailed analysis, aggregated analytics for trend monitoring, and filtered views for specific campaigns or time periods.

Error Responses Copied

All endpoints can return the following HTTP status codes and error responses:

Authentication & Authorization Errors Copied

401 Unauthorized

{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Authentication required. Please provide a valid API key.",
    "details": "string"
  },
  "meta": {}
}

403 Forbidden

{
  "success": false,
  "error": {
    "code": "FORBIDDEN",
    "message": "Insufficient permissions to access this tracker.",
    "details": "string"
  },
  "meta": {}
}

Client Errors Copied

400 Bad Request

{
  "success": false,
  "error": {
    "code": "BAD_REQUEST",
    "message": "Invalid request parameters.",
    "details": "string",
    "validation_errors": [
      {
        "field": "string",
        "message": "string"
      }
    ]
  },
  "meta": {}
}

404 Not Found

{
  "success": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "Tracker not found or does not exist.",
    "details": "string"
  },
  "meta": {}
}

409 Conflict

{
  "success": false,
  "error": {
    "code": "CONFLICT",
    "message": "Request conflicts with current tracker state.",
    "details": "string"
  },
  "meta": {}
}

422 Unprocessable Entity

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed.",
    "details": "string",
    "validation_errors": [
      {
        "field": "string",
        "message": "string",
        "code": "string"
      }
    ]
  },
  "meta": {}
}

429 Too Many Requests

{
  "success": false,
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Rate limit exceeded. Please retry after some time.",
    "details": "string",
    "retry_after": "number (seconds)"
  },
  "meta": {}
}

Server Errors Copied

500 Internal Server Error

{
  "success": false,
  "error": {
    "code": "INTERNAL_SERVER_ERROR",
    "message": "An unexpected error occurred. Please try again later.",
    "details": "string",
    "request_id": "string"
  },
  "meta": {}
}

502 Bad Gateway

{
  "success": false,
  "error": {
    "code": "BAD_GATEWAY",
    "message": "Upstream service unavailable.",
    "details": "string"
  },
  "meta": {}
}

503 Service Unavailable

{
  "success": false,
  "error": {
    "code": "SERVICE_UNAVAILABLE",
    "message": "Service temporarily unavailable. Please retry later.",
    "details": "string",
    "retry_after": "number (seconds)"
  },
  "meta": {}
}

504 Gateway Timeout

{
  "success": false,
  "error": {
    "code": "GATEWAY_TIMEOUT",
    "message": "Request timeout. Please try again.",
    "details": "string"
  },
  "meta": {}
}

API Endpoints Copied

Tracker Instance Details Copied

Get Tracker Instances

GET /api/partner/v1/trackers/{tracker_id}/instances
GET /api/partner/v1/trackers/{tracker_id}/instances?page=1&limit=50&is_purchase=all&since=2024-07-15T00:00:00.000Z

Retrieve detailed individual interaction events for a specific tracker, showing raw user engagement data for granular analysis.

Parameters:

• page (optional): Page number for pagination (default: 1)

• limit (optional): Results per page (default: 50, max: 200)

• is_purchase (optional): Filter by purchase status: true, false, all (default: all)

• since (optional): Show instances since timestamp

Success Response (200 OK):

{
  "success": "boolean",
  "message": "string",
  "data": {
    "tracker_id": "UUID",
    "tracker_name": "string",
    "tracker_type": "string",
    "instances": [
      {
        "instance_id": "UUID",
        "insider_id": "UUID",
        "campaign_id": "UUID",
        "is_purchase": "boolean",
        "timestamp": "ISO 8601 timestamp"
      }
    ]
  },
  "pagination": {
    "page": "number",
    "limit": "number",
    "total": "number",
    "totalPages": "number",
    "hasNext": "boolean",
    "hasPrevious": "boolean"
  },
  "meta": {
    "timestamp": "ISO 8601 timestamp",
    "requestId": "UUID"
  }
}

Specific Error Cases:

• 400: Invalid UUID format for tracker_id

• 400: Invalid page number (must be positive integer)

• 400: Invalid limit value (must be 1-200)

• 400: Invalid is_purchase parameter (must be true, false, or all)

• 400: Invalid since timestamp format

• 404: Tracker not found

• 403: Insufficient permissions to view tracker instances

Tracker Analytics Copied

Get Tracker Analytics

GET /api/partner/v1/analytics/tracker/{tracker_id}
GET /api/partner/v1/analytics/tracker/{tracker_id}?time_frame=per_day&start_date=2024-07-25&end_date=2024-07-30

Get aggregated performance metrics and trends for a tracker over specified time periods. The response structure varies based on the tracker type to provide the most relevant metrics for each interaction pattern.

Parameters:

• time_frame (optional): Time aggregation: per_hour, per_day, per_month, custom_range (default: per_day)

• start_date (required for custom_range): Start date in YYYY-MM-DD format

• end_date (required for custom_range): End date in YYYY-MM-DD format

Success Response (200 OK) for page_view tracker:

{
  "success": "boolean",
  "message": "string",
  "data": {
    "tracker_id": "UUID",
    "tracker_name": "string",
    "tracker_type": "page_view",
    "time_frame": "string",
    "date_range": {
      "start_date": "ISO 8601 timestamp",
      "end_date": "ISO 8601 timestamp"
    },
    "analytics": [
      {
        "date": "YYYY-MM-DD string",
        "total_instances": "number",
        "unique_insiders": "number",
        "page_views": "number",
        "unique_page_views": "number",
        "bounce_rate": "number (0.0-1.0)",
        "avg_time_on_page": "number (seconds)",
        "campaigns_used": ["UUID"],
        "campaign_count": "number"
      }
    ],
    "summary": {
      "total_instances": "number",
      "total_unique_insiders": "number",
      "total_page_views": "number",
      "overall_bounce_rate": "number (0.0-1.0)",
      "average_time_on_page": "number (seconds)",
      "average_page_views_per_day": "number",
      "total_campaigns_used": "number",
      "peak_day": "YYYY-MM-DD string",
      "peak_page_views": "number"
    }
  },
  "meta": {
    "timestamp": "ISO 8601 timestamp",
    "requestId": "UUID"
  }
}

Success Response (200 OK) for click_tracking tracker:

{
  "success": "boolean",
  "message": "string",
  "data": {
    "tracker_id": "UUID",
    "tracker_name": "string",
    "tracker_type": "click_tracking",
    "time_frame": "string",
    "date_range": {
      "start_date": "ISO 8601 timestamp",
      "end_date": "ISO 8601 timestamp"
    },
    "analytics": [
      {
        "date": "YYYY-MM-DD string",
        "total_instances": "number",
        "unique_insiders": "number",
        "total_clicks": "number",
        "unique_clicks": "number",
        "click_through_rate": "number (0.0-1.0)",
        "conversion_rate": "number (0.0-1.0)",
        "campaigns_used": ["UUID"],
        "campaign_count": "number"
      }
    ],
    "summary": {
      "total_instances": "number",
      "total_unique_insiders": "number",
      "total_clicks": "number",
      "overall_click_through_rate": "number (0.0-1.0)",
      "overall_conversion_rate": "number (0.0-1.0)",
      "average_clicks_per_day": "number",
      "total_campaigns_used": "number",
      "peak_day": "YYYY-MM-DD string",
      "peak_clicks": "number"
    }
  },
  "meta": {
    "timestamp": "ISO 8601 timestamp",
    "requestId": "UUID"
  }
}

Success Response (200 OK) for scroll_tracking tracker:

{
  "success": "boolean",
  "message": "string",
  "data": {
    "tracker_id": "UUID",
    "tracker_name": "string",
    "tracker_type": "scroll_tracking",
    "time_frame": "string",
    "date_range": {
      "start_date": "ISO 8601 timestamp",
      "end_date": "ISO 8601 timestamp"
    },
    "analytics": [
      {
        "date": "YYYY-MM-DD string",
        "total_instances": "number",
        "unique_insiders": "number",
        "avg_scroll_depth": "number (0.0-1.0)",
        "max_scroll_depth": "number (0.0-1.0)",
        "engagement_rate": "number (0.0-1.0)",
        "deep_scroll_rate": "number (0.0-1.0)",
        "campaigns_used": ["UUID"],
        "campaign_count": "number"
      }
    ],
    "summary": {
      "total_instances": "number",
      "total_unique_insiders": "number",
      "overall_avg_scroll_depth": "number (0.0-1.0)",
      "overall_engagement_rate": "number (0.0-1.0)",
      "overall_deep_scroll_rate": "number (0.0-1.0)",
      "average_sessions_per_day": "number",
      "total_campaigns_used": "number",
      "peak_day": "YYYY-MM-DD string",
      "peak_engagement": "number (0.0-1.0)"
    }
  },
  "meta": {
    "timestamp": "ISO 8601 timestamp",
    "requestId": "UUID"
  }
}

Success Response (200 OK) for time_tracking tracker:

{
  "success": "boolean",
  "message": "string",
  "data": {
    "tracker_id": "UUID",
    "tracker_name": "string",
    "tracker_type": "time_tracking",
    "time_frame": "string",
    "date_range": {
      "start_date": "ISO 8601 timestamp",
      "end_date": "ISO 8601 timestamp"
    },
    "analytics": [
      {
        "date": "YYYY-MM-DD string",
        "total_instances": "number",
        "unique_insiders": "number",
        "avg_session_duration": "number (seconds)",
        "median_session_duration": "number (seconds)",
        "quick_purchaser_rate": "number (0.0-1.0)",
        "slow_purchaser_rate": "number (0.0-1.0)",
        "lost_visitor_rate": "number (0.0-1.0)",
        "campaigns_used": ["UUID"],
        "campaign_count": "number"
      }
    ],
    "summary": {
      "total_instances": "number",
      "total_unique_insiders": "number",
      "overall_avg_session_duration": "number (seconds)",
      "overall_median_session_duration": "number (seconds)",
      "overall_quick_purchaser_rate": "number (0.0-1.0)",
      "overall_slow_purchaser_rate": "number (0.0-1.0)",
      "overall_lost_visitor_rate": "number (0.0-1.0)",
      "average_sessions_per_day": "number",
      "total_campaigns_used": "number",
      "peak_day": "YYYY-MM-DD string",
      "peak_avg_duration": "number (seconds)"
    }
  },
  "meta": {
    "timestamp": "ISO 8601 timestamp",
    "requestId": "UUID"
  }
}

Specific Error Cases:

• 400: Invalid UUID format for tracker_id

• 400: Invalid time_frame parameter

• 400: Missing start_date for custom_range

• 400: Missing end_date for custom_range

• 400: Invalid date format (must be YYYY-MM-DD)

• 400: End date must be after start date

• 400: Date range too large (exceeds maximum allowed period)

• 404: Tracker not found

• 403: Insufficient permissions to view tracker analytics

• 422: No data available for the specified time period

Tracker Types & Metrics Copied

Page View Tracking Copied

Use Case: Track page visits and navigation patterns
Best For: Site analytics, funnel analysis, content performance
Key Metrics: Page views, unique page views, bounce rate, time on page

Click Tracking Copied

Use Case: Monitor button and link clicks
Best For: UX optimization, conversion tracking, A/B testing
Key Metrics: Click-through rate, conversion rate, unique clicks

Scroll Tracking Copied

Use Case: Measure content engagement depth
Best For: Content performance, user engagement analysis
Key Metrics: Scroll depth, engagement rate, deep scroll percentage

Time Tracking Copied

Use Case: Track session duration and user behavior patterns
Best For: Understanding user purchase intent and behavior classification
Key Metrics: Session duration, quick/slow/lost purchaser rates

Key Differences Between Endpoints Copied

Instances Endpoint Copied

Perfect for detailed analysis and debugging. Each response row represents one individual user interaction event, complete with specific insider, campaign, and timing information. Use this when you need to export raw data, troubleshoot tracking issues, or perform custom attribution analysis.

Analytics Endpoint Copied

Ideal for performance monitoring and trend analysis. Each response row represents aggregated metrics for a time period (hour, day, or month), with metrics tailored to the specific tracker type. Use this for dashboards, performance reports, and identifying optimization opportunities based on the type of user interaction you're measuring.How Tracker Authentication Works

Tracker data is automatically associated with your partner account through secure API authentication. When users interact with your tracked elements, our system seamlessly captures and attributes these events to the correct campaigns and insiders, enabling real-time performance monitoring without requiring additional user authentication steps.

• Automatic Event Capture: All tracked interactions are automatically recorded with campaign and user attribution.

• Real-time Processing: Events appear in both instances and analytics endpoints within seconds of occurrence.

• Example: User scrolls 75% down your product page - instantly appears in instances feed and updates daily scroll analytics with engagement depth and campaign attribution.