API Documentation

The Tinylytics API provides programmatic access to your analytics data. Perfect for building custom dashboards, integrations, or automated reporting.

Quick Start

Base URL: https://tinylytics.app/api/v1/

Authentication: Include your API key in the Authorization header:

Authorization: Bearer tly-ro-your-api-key-here

Get an API Key: Account Settings → API Access → Create New API Key

API Endpoints

Quick Navigation

• Account & Sites
  • Test API Key
  • List Sites
  • Site Details
• Analytics
  • Site Hits
  • Leaderboard
  • User Journeys
• Monitoring
  • Uptime Status

Account & Sites

GET /me

Test your API key and get account information.

Example Request

curl -H "Authorization: Bearer tly-ro-your-api-key" \
  https://tinylytics.app/api/v1/me

Example Response

{
  "user": {
    "email": "[email protected]",
    "name": "John Doe",
    "subscription_status": "active",
    "sites_count": 5
  }
}

GET /sites

List all your sites.

Example Request

curl -H "Authorization: Bearer tly-ro-your-api-key" \
  https://tinylytics.app/api/v1/sites

Example Response

{
  "sites": [
    {
      "id": 456,
      "uid": "abc123",
      "url": "https://example.com",
      "label": "My Blog",
      "lifetime_hits": 12345,
      "active": true
    },
    {
      "id": 457,
      "uid": "def456",
      "url": "https://another-site.com",
      "label": "Another Site",
      "lifetime_hits": 6789,
      "active": true
    }
  ],
  "total_count": 2
}

GET /sites/:id

Get details for a specific site.

Example Request

curl -H "Authorization: Bearer tly-ro-your-api-key" \
  https://tinylytics.app/api/v1/sites/456

Example Response

{
  "site": {
    "id": 456,
    "uid": "abc123",
    "url": "https://example.com",
    "label": "My Blog",
    "lifetime_hits": 12345,
    "lifetime_unique_hits": 8901,
    "active": true,
    "is_public": false,
    "created_at": "2023-01-15T10:00:00Z",
    "updated_at": "2023-06-04T14:22:00Z"
  }
}

Analytics

GET /sites/:id/hits

Get analytics data for a site with filtering and grouping options.

Parameters

• start_date / end_date - Date range (YYYY-MM-DD, max 365 days)
• country - Filter by country code (e.g., “US”, “GB”)
• path - Filter by exact path (e.g., “/blog/post”)
• referrer - Filter by referrer (partial match)
• grouped=true - Return aggregated data
• group_by - Group by: path, country, referrer, browsername, platformname
• page / per_page - Pagination (max 1000 per page)

Example Requests

Basic Analytics

# Last 7 days of hits
curl -H "Authorization: Bearer tly-ro-your-api-key" \
  "https://tinylytics.app/api/v1/sites/456/hits?start_date=2023-05-28&end_date=2023-06-04"

# Filter by country and path
curl -H "Authorization: Bearer tly-ro-your-api-key" \
  "https://tinylytics.app/api/v1/sites/456/hits?country=US&path=/blog"

Grouped Analytics

# Most popular pages
curl -H "Authorization: Bearer tly-ro-your-api-key" \
  "https://tinylytics.app/api/v1/sites/456/hits?grouped=true&group_by=path"

# Top traffic sources
curl -H "Authorization: Bearer tly-ro-your-api-key" \
  "https://tinylytics.app/api/v1/sites/456/hits?grouped=true&group_by=referrer"

Example Response (Individual Hits)

{
  "hits": [
    {
      "id": 789012,
      "url": "https://example.com/blog/my-post",
      "path": "/blog/my-post",
      "referrer": "https://twitter.com",
      "country": "US",
      "browser_name": "Chrome",
      "platform_name": "macOS",
      "is_mobile": false,
      "created_at": "2023-06-04T14:22:00Z"
    }
  ],
  "pagination": {
    "current_page": 1,
    "per_page": 100,
    "total_count": 1547,
    "total_pages": 16
  }
}

Example Response (Grouped Data)

{
  "grouped_hits": [
    {
      "path": "/blog/popular-post",
      "hit_count": 247
    },
    {
      "path": "/",
      "hit_count": 156
    }
  ],
  "pagination": {
    "current_page": 1,
    "per_page": 100,
    "total_count": 25,
    "total_pages": 1
  }
}

GET /sites/:id/leaderboard

Get a leaderboard of all paths for a site, ranked by total hits with caching for performance.

Parameters

• path - Filter paths containing this term (case-insensitive, partial match)
• page / per_page - Pagination (max 1000 per page)

Features

• Returns all-time data (no date filtering)
• Includes total hits, unique hits, and percentage of site traffic
• 1-hour caching for optimal performance
• Separate cache for filtered vs unfiltered results

Example Requests

# All-time top pages
curl -H "Authorization: Bearer tly-ro-your-api-key" \
  "https://tinylytics.app/api/v1/sites/456/leaderboard"

# Filter blog posts only
curl -H "Authorization: Bearer tly-ro-your-api-key" \
  "https://tinylytics.app/api/v1/sites/456/leaderboard?path=blog"

Example Response

{
  "leaderboard": [
    {
      "path": "/blog/popular-post",
      "total_hits": 1250,
      "unique_hits": 890,
      "percentage": 15.2
    },
    {
      "path": "/about",
      "total_hits": 800,
      "unique_hits": 650,
      "percentage": 9.7
    }
  ],
  "site": {
    "id": 456,
    "uid": "abc123",
    "url": "https://example.com",
    "label": "My Blog"
  },
  "pagination": {
    "current_page": 1,
    "per_page": 100,
    "total_count": 245,
    "total_pages": 3
  },
  "cache_info": {
    "cached_at": "2024-01-01T12:00:00Z",
    "expires_at": "2024-01-01T13:00:00Z"
  },
  "filters": {
    "path": "blog"
  }
}

GET /sites/:id/user_journeys

Analyze visitor behavior and user journeys through your site. Track how users navigate between pages, identify popular entry/exit points, and measure engagement patterns.

Parameters

• start_date / end_date - Date range (YYYY-MM-DD, max 365 days, defaults to last 30 days)
• page / per_page - Pagination (max 50 per page for journeys)

Features

• Complete visitor journey paths with timestamps
• Session duration calculations
• Bounce rate analysis (single-page vs multi-page visitors)
• Top entry and exit pages identification
• Privacy-preserving visitor identification
• Real-time data (no caching for accurate journey tracking)

Example Requests

# Visitor journeys for last 30 days
curl -H "Authorization: Bearer tly-ro-your-api-key" \
  "https://tinylytics.app/api/v1/sites/456/user_journeys"

# Custom date range
curl -H "Authorization: Bearer tly-ro-your-api-key" \
  "https://tinylytics.app/api/v1/sites/456/user_journeys?start_date=2024-01-01&end_date=2024-01-31"

Example Response

{
  "user_journeys": [
    {
      "visitor_hash": "a1b2c3d4e5f6",
      "page_count": 4,
      "pages": [
        {
          "path": "/",
          "visited_at": "2024-01-15T10:00:00Z"
        },
        {
          "path": "/blog",
          "visited_at": "2024-01-15T10:02:30Z"
        },
        {
          "path": "/blog/user-journeys",
          "visited_at": "2024-01-15T10:05:15Z"
        },
        {
          "path": "/contact",
          "visited_at": "2024-01-15T10:08:45Z"
        }
      ],
      "entry_page": "/",
      "exit_page": "/contact",
      "session_duration": "8m"
    }
  ],
  "summary": {
    "total_visitors": 1247,
    "multi_page_visitors": 456,
    "single_page_visitors": 791,
    "bounce_rate": 63.4
  },
  "insights": {
    "top_entry_pages": [
      {
        "path": "/",
        "visitors": 634
      },
      {
        "path": "/blog",
        "visitors": 289
      },
      {
        "path": "/about",
        "visitors": 156
      }
    ],
    "top_exit_pages": [
      {
        "path": "/contact",
        "visitors": 234
      },
      {
        "path": "/",
        "visitors": 198
      },
      {
        "path": "/blog/popular-post",
        "visitors": 123
      }
    ]
  },
  "pagination": {
    "current_page": 1,
    "per_page": 10,
    "total_count": 456,
    "total_pages": 46
  },
  "filters": {
    "start_date": "2024-01-01",
    "end_date": "2024-01-31"
  }
}

Monitoring

GET /sites/:id/uptime

Monitor website uptime and SSL certificate status. Track downtime incidents, SSL certificate expiration, and others.

Parameters

• page / per_page - Pagination for downtimes (max 50 per page)

Features

• Real-time uptime percentage and monitoring status
• Downtime history with duration and error details
• SSL certificate validation and expiration tracking
• Current check intervals and monitoring configuration
• Automatic pause detection for extended outages
• Human-readable duration formatting

Example Requests

# Get uptime status and recent downtimes
curl -H "Authorization: Bearer tly-ro-your-api-key" \
  "https://tinylytics.app/api/v1/sites/456/uptime"

# Paginated downtime history
curl -H "Authorization: Bearer tly-ro-your-api-key" \
  "https://tinylytics.app/api/v1/sites/456/uptime?page=2&per_page=25"

Example Response

{
  "monitor": {
    "id": 33,
    "url": "https://example.com",
    "enabled": true,
    "is_down": true,
    "uptime": "98.95",
    "last_check_at": "2025-08-02T20:45:47.000Z",
    "next_check_at": "2025-08-02T20:50:44.000Z",
    "last_status_code": 530,
    "last_error_message": "530 Custom Cloudflare Error",
    "status_description": "Server Error (530)",
    "current_check_interval": "5 minutes",
    "period": 300,
    "ssl_expires_at": "2025-09-08T19:29:06.000Z",
    "ssl_valid": true,
    "ssl_expiring_soon": false,
    "ssl_expired": false,
    "ssl_days_until_expiry": 36,
    "auto_paused": false,
    "created_at": "2025-03-29T14:50:30.509Z",
    "updated_at": "2025-08-02T20:47:10.966Z"
  },
  "downtimes": [
    {
      "id": 1,
      "error": "530 Custom Cloudflare Error",
      "started_at": "2025-03-30T18:22:07.000Z",
      "ended_at": "2025-05-22T19:26:19.000Z",
      "duration": 4583052,
      "duration_in_words": "53 days",
      "partial": false,
      "ongoing": false
    }
  ],
  "pagination": {
    "current_page": 1,
    "per_page": 50,
    "total_count": 8,
    "total_pages": 1
  },
  "summary": {
    "total_downtimes": 8,
    "ongoing_downtimes": 0,
    "recent_downtimes_30_days": 0
  }
}

Common Use Cases

Custom Dashboard: Combine /sites and /sites/:id/hits to build analytics dashboards

Traffic Monitoring: Fetch daily hits and compare against historical data for automated alerts

Content Analysis: Use grouped data to identify popular pages, top referrers, and audience demographics

Performance Insights: Group by browser, platform, or country for technical and geographic analytics

Top Content Discovery: Use /sites/:id/leaderboard to find your most popular content across all time

Content Strategy: Filter leaderboard by path segments (e.g., “/blog”, “/product”) to analyze specific content types

User Journey Analysis: Use /sites/:id/user_journeys to understand visitor behavior patterns:

• Identify drop-off points in conversion funnels
• Optimize navigation by analyzing common user paths
• Measure engagement through session duration and bounce rates
• Discover how users discover and consume your content
• A/B test page flows by comparing journey patterns over time

Uptime Monitoring: Use /sites/:id/uptime to monitor site availability and performance:

• Track real-time uptime percentage and current status
• Analyze downtime patterns and error types
• Monitor SSL certificate expiration and validity
• Set up automated alerts based on uptime thresholds
• Review historical downtime incidents for root cause analysis
• Integrate with status pages and incident management systems

Error Handling

Error Response:

{
  "error": "API access requires an active subscription"
}

Rate Limits

API requests are subject to reasonable rate limits. If exceeded, you’ll receive a 429 status code.

Need Help?

Contact us at [email protected] for API questions or implementation assistance. We aim to respond within 24 hours.