> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bouncy.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Get Link or Website Analytics

> Retrieve detailed analytics for a short link or bio website

## Request

### Headers

### Path Parameters

<ParamField path="identifier" type="string" required>
  The link or website identifier. For websites, you can use the document ID, custom slug, or custom domain.

  **Examples:** `link_abc123xyz`, `my-bio-page`, `example.com`
</ParamField>

### Query Parameters

<ParamField query="timeframe" type="string">
  Preset date range. Supported values are `last_7_days`, `last_30_days`, `last_90_days`, `this_month`, `last_month`, and `all_time`.

  **Example:** `last_30_days`
</ParamField>

<ParamField query="from" type="string">
  Custom range start date in `YYYY-MM-DD` format. Must be used with `to`.

  **Example:** `2026-01-01`
</ParamField>

<ParamField query="to" type="string">
  Custom range end date in `YYYY-MM-DD` format. Must be used with `from`.

  **Example:** `2026-01-31`
</ParamField>

<Info>
  Bio website button clicks are returned in `clicksByLink`. Each tracked button includes the link ID, title, URL, total clicks, and daily clicks for the selected range.
</Info>

## Response

<ResponseField name="id" type="string">
  Resolved Firestore document ID used for analytics lookup.
</ResponseField>

<ResponseField name="identifier" type="string">
  Identifier from the request path.
</ResponseField>

<ResponseField name="type" type="string">
  Resource type, such as `Website` or `Deeplink`.
</ResponseField>

<ResponseField name="resolvedBy" type="string">
  How the identifier was matched, such as `documentId`, `customSlug`, or `customDomain`.
</ResponseField>

<ResponseField name="totalViews" type="number">
  Total views in the selected range.
</ResponseField>

<ResponseField name="dailyViews" type="array">
  Time-series analytics for the selected range. For short ranges this is hourly; for longer ranges this is daily or monthly.

  <Expandable title="properties">
    <ResponseField name="date" type="string">
      Time bucket identifier.
    </ResponseField>

    <ResponseField name="views" type="number">
      Views in this time bucket.
    </ResponseField>

    <ResponseField name="clicks" type="number">
      Clicks in this time bucket.
    </ResponseField>

    <ResponseField name="adultClicks" type="number">
      Adult confirmation clicks in this time bucket.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="deviceStats" type="object">
  View breakdown by device type.
</ResponseField>

<ResponseField name="countryStats" type="array">
  Countries by view count.

  <Expandable title="properties">
    <ResponseField name="name" type="string">
      Country name.
    </ResponseField>

    <ResponseField name="views" type="number">
      Views from this country.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="topCountry" type="string">
  Highest-view country in the selected range, excluding unknown values.
</ResponseField>

<ResponseField name="topCountryViews" type="number">
  View count for `topCountry`.
</ResponseField>

<ResponseField name="lastViewed" type="string | null">
  Timestamp of the latest view, or `null` when no view has been recorded.
</ResponseField>

<ResponseField name="platformStats" type="object">
  View breakdown by platform or operating system.
</ResponseField>

<ResponseField name="referrerStats" type="array">
  Referrer domains by view count.

  <Expandable title="properties">
    <ResponseField name="domain" type="string">
      Referrer domain.
    </ResponseField>

    <ResponseField name="views" type="number">
      Views from this referrer.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="totalClicks" type="number">
  Total tracked clicks in the selected range. For bio websites, this is the total clicks across tracked buttons.
</ResponseField>

<ResponseField name="clicksByLink" type="array">
  Click breakdown by tracked link or button.

  <Expandable title="properties">
    <ResponseField name="id" type="string">
      Tracked link/button ID. Adult confirmation clicks use `adult-18plus-btn`.
    </ResponseField>

    <ResponseField name="count" type="number">
      Number of clicks for this link/button. This is kept for backwards compatibility.
    </ResponseField>

    <ResponseField name="totalClicks" type="number">
      Total clicks for this link/button in the selected range.
    </ResponseField>

    <ResponseField name="title" type="string">
      Tracked link/button title.
    </ResponseField>

    <ResponseField name="url" type="string">
      Tracked destination URL.
    </ResponseField>

    <ResponseField name="type" type="string">
      Tracked link/button type. Adult confirmation clicks use `adult-confirmation`.
    </ResponseField>

    <ResponseField name="dailyClicks" type="array">
      Daily click counts for this link/button in the selected range.

      <Expandable title="properties">
        <ResponseField name="date" type="string">
          Date in `YYYY-MM-DD` format.
        </ResponseField>

        <ResponseField name="clicks" type="number">
          Click count for this link/button on that date.
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="adultConfirmation" type="object | null">
  Adult confirmation metric for adult-gated links. Returns `null` when no adult confirmation clicks were tracked in the selected range.

  <Expandable title="properties">
    <ResponseField name="clicks" type="number">
      Number of users who clicked the adult confirmation button.
    </ResponseField>

    <ResponseField name="rate" type="number">
      Confirmation rate as a percentage of views in the selected range.
    </ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl https://api.bouncy.ai/v1/analytics/links/link_abc123xyz \
    -H "Authorization: Bearer bcy_live_pk_YOUR_API_KEY"
  ```

  ```bash cURL (With Preset Timeframe) theme={null}
  curl "https://api.bouncy.ai/v1/analytics/links/link_abc123xyz?timeframe=last_30_days" \
    -H "Authorization: Bearer bcy_live_pk_YOUR_API_KEY"
  ```

  ```bash cURL (With Custom Date Range) theme={null}
  curl "https://api.bouncy.ai/v1/analytics/links/link_abc123xyz?from=2026-01-01&to=2026-01-31" \
    -H "Authorization: Bearer bcy_live_pk_YOUR_API_KEY"
  ```

  ```bash cURL (Website Button Clicks) theme={null}
  curl "https://api.bouncy.ai/v1/analytics/links/my-bio-page?timeframe=last_30_days" \
    -H "Authorization: Bearer bcy_live_pk_YOUR_API_KEY"
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(
    'https://api.bouncy.ai/v1/analytics/links/my-bio-page?timeframe=last_30_days',
    {
      headers: {
        'Authorization': 'Bearer bcy_live_pk_YOUR_API_KEY'
      }
    }
  );

  const analytics = await response.json();
  console.log(`Total views: ${analytics.totalViews}`);
  console.log(`Total clicks: ${analytics.totalClicks}`);
  console.log(analytics.clicksByLink.map(button => ({
    id: button.id,
    title: button.title,
    totalClicks: button.totalClicks,
    dailyClicks: button.dailyClicks
  })));
  ```

  ```python Python theme={null}
  import requests

  response = requests.get(
      'https://api.bouncy.ai/v1/analytics/links/link_abc123xyz',
      headers={'Authorization': 'Bearer bcy_live_pk_YOUR_API_KEY'},
      params={
          'from': '2026-01-01',
          'to': '2026-01-31'
      }
  )

  analytics = response.json()
  print(f"Total views: {analytics['totalViews']}")
  print(f"Adult confirmations: {(analytics.get('adultConfirmation') or {}).get('clicks', 0)}")
  ```
</RequestExample>

<ResponseExample>
  ```json 200 Success theme={null}
  {
    "id": "my-bio-page",
    "identifier": "my-bio-page",
    "type": "Website",
    "resolvedBy": "customSlug",
    "totalViews": 190,
    "dailyViews": [
      {
        "date": "2026-01-15",
        "views": 74,
        "clicks": 78,
        "adultClicks": 46,
        "countries": {
          "us": 41,
          "gb": 18
        },
        "devices": {
          "mobile": 69,
          "desktop": 5
        },
        "platforms": {
          "ios": 43,
          "android": 26,
          "windows": 5
        },
        "referrers": {
          "instagram.com": 38,
          "direct": 22
        }
      }
    ],
    "deviceStats": {
      "mobile": 176,
      "desktop": 14
    },
    "countryStats": [
      { "name": "United States", "views": 112 },
      { "name": "United Kingdom", "views": 49 }
    ],
    "topCountry": "United States",
    "topCountryViews": 112,
    "lastViewed": "2026-01-31T19:22:10.000Z",
    "platformStats": {
      "ios": 104,
      "android": 72,
      "windows": 14
    },
    "referrerStats": [
      { "domain": "instagram.com", "views": 89 },
      { "domain": "direct", "views": 54 }
    ],
    "totalClicks": 211,
    "clicksByLink": [
      {
        "id": "shop_0_lx8abc",
        "count": 88,
        "totalClicks": 88,
        "title": "Shop Now",
        "url": "https://example.com/shop",
        "type": "standard",
        "dailyClicks": [
          { "date": "2026-01-15", "clicks": 32 },
          { "date": "2026-01-16", "clicks": 56 }
        ]
      },
      {
        "id": "adult-18plus-btn",
        "count": 123,
        "totalClicks": 123,
        "title": "Yes, I'm 18+",
        "url": "https://example.com/adult-destination",
        "type": "adult-confirmation",
        "dailyClicks": [
          { "date": "2026-01-15", "clicks": 46 },
          { "date": "2026-01-16", "clicks": 77 }
        ]
      }
    ],
    "adultConfirmation": {
      "clicks": 123,
      "rate": 64.74
    }
  }
  ```

  ```json 404 Not Found theme={null}
  {
    "error": "Link or website not found"
  }
  ```
</ResponseExample>