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

# Listing Analytics

> Query tier-gated analytics for a Hub listing via the REST API

## Overview

The listing analytics endpoint returns engagement and conversion metrics for a Hub listing. The response shape is **gated by listing tier** — Basic listings receive view counts only; Featured and Premium listings receive progressively richer funnel data.

Only the listing owner can access this endpoint. Authentication uses a **session token** (`Authorization: Bearer`), not a Hub API key.

**Base URL:** `https://ezforge.ai`

<Info>
  This page is the dedicated listing analytics API reference. For the consolidated Hub API reference covering both API keys and listing analytics in one place, see [Hub API Reference](/hub/api-reference). For a conceptual overview of all analytics metrics (including dashboard-only metrics), see [Analytics](/hub/analytics).
</Info>

***

## Get listing analytics

```
GET /api/v1/hub/analytics/listings/:id
```

Returns analytics for a Hub listing for the specified reporting period. The response fields available depend on the listing's tier.

**Authentication:** `Authorization: Bearer <user-token>` (session token required).

### Path parameters

| Parameter | Type   | Description                       |
| --------- | ------ | --------------------------------- |
| `id`      | string | 26-character ULID of the listing. |

### Query parameters

| Parameter | Type   | Default | Description                              |
| --------- | ------ | ------- | ---------------------------------------- |
| `period`  | string | `30d`   | Reporting window: `7d`, `30d`, or `90d`. |

### Responses by tier

**`200` — Basic tier:**

```json theme={null}
{
  "data": {
    "tier": "basic",
    "period": "30d",
    "view_count": 312
  }
}
```

**`200` — Featured tier:**

```json theme={null}
{
  "data": {
    "tier": "featured",
    "period": "30d",
    "view_count": 312,
    "click_count": 87,
    "click_through_rate": 27.88
  }
}
```

**`200` — Premium tier:**

```json theme={null}
{
  "data": {
    "tier": "premium",
    "period": "30d",
    "view_count": 312,
    "click_count": 87,
    "click_through_rate": 27.88,
    "search_impressions": 1540,
    "referral_clicks": 34,
    "conversion_rate": 3.21
  }
}
```

### Response fields

| Field                | Type    | Tiers             | Description                                                                                    |
| -------------------- | ------- | ----------------- | ---------------------------------------------------------------------------------------------- |
| `tier`               | string  | all               | Listing tier used to gate this response: `basic`, `featured`, or `premium`.                    |
| `period`             | string  | all               | Reporting window echoed back: `7d`, `30d`, or `90d`.                                           |
| `view_count`         | integer | all               | Total listing views in the period.                                                             |
| `click_count`        | integer | Featured, Premium | Total click-throughs from search results to the listing detail page.                           |
| `click_through_rate` | number  | Featured, Premium | `click_count / view_count × 100`, rounded to 2 decimal places. `0` when `view_count` is zero.  |
| `search_impressions` | integer | Premium           | Times the listing appeared in search results during the period.                                |
| `referral_clicks`    | integer | Premium           | Referral-link interactions originating from Hub discovery (`interaction` events).              |
| `conversion_rate`    | number  | Premium           | `transactions / view_count × 100`, rounded to 2 decimal places. `0` when `view_count` is zero. |

<Info>
  `referral_clicks` counts `interaction` events — the Hub event taxonomy uses `interaction` as the referral-link click signal. See [Analytics Events](/hub/analytics-events) for the full event type reference.
</Info>

### Metric definitions

| Metric                 | Formula                           | Notes                                                         |
| ---------------------- | --------------------------------- | ------------------------------------------------------------- |
| **Click-through rate** | `click_count / view_count × 100`  | Percentage of views that resulted in a click-through.         |
| **Conversion rate**    | `transactions / view_count × 100` | Percentage of views that resulted in a completed transaction. |

Both rates are set to `0.00` rather than divided-by-zero when `view_count` is `0`.

### Error responses

| Status | Code                  | Condition                                                                         |
| ------ | --------------------- | --------------------------------------------------------------------------------- |
| 400    | `invalid_input`       | `id` is not a valid 26-character ULID, or `period` is not `7d`, `30d`, or `90d`.  |
| 401    | `unauthorized`        | Missing or invalid session token.                                                 |
| 403    | `forbidden`           | Authenticated user does not own this listing.                                     |
| 404    | `not_found`           | Listing not found.                                                                |
| 429    | `rate_limited`        | IP rate limit exceeded. `Retry-After` reflects seconds until window reset (≤ 60). |
| 503    | `service_unavailable` | Rate-limit service temporarily unavailable.                                       |

***

## Tier comparison

| Metric               | Basic | Featured | Premium |
| -------------------- | ----- | -------- | ------- |
| `view_count`         | ✓     | ✓        | ✓       |
| `click_count`        | —     | ✓        | ✓       |
| `click_through_rate` | —     | ✓        | ✓       |
| `search_impressions` | —     | —        | ✓       |
| `referral_clicks`    | —     | —        | ✓       |
| `conversion_rate`    | —     | —        | ✓       |

To upgrade your listing tier, see [Listings](/hub/listings).