Skip to main content

​
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
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. For a conceptual overview of all analytics metrics (including dashboard-only metrics), see Analytics.

​
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

ParameterTypeDescription
idstring26-character ULID of the listing.

​
Query parameters

ParameterTypeDefaultDescription
periodstring30dReporting window: 7d, 30d, or 90d.

​
Responses by tier

200 — Basic tier: 
{
  "data": {
    "tier": "basic",
    "period": "30d",
    "view_count": 312
  }
}
200 — Featured tier: 
{
  "data": {
    "tier": "featured",
    "period": "30d",
    "view_count": 312,
    "click_count": 87,
    "click_through_rate": 27.88
  }
}
200 — Premium tier: 
{
  "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

FieldTypeTiersDescription
tierstringallListing tier used to gate this response: basic, featured, or premium.
periodstringallReporting window echoed back: 7d, 30d, or 90d.
view_countintegerallTotal listing views in the period.
click_countintegerFeatured, PremiumTotal click-throughs from search results to the listing detail page.
click_through_ratenumberFeatured, Premiumclick_count / view_count × 100, rounded to 2 decimal places. 0 when view_count is zero.
search_impressionsintegerPremiumTimes the listing appeared in search results during the period.
referral_clicksintegerPremiumReferral-link interactions originating from Hub discovery (interaction events).
conversion_ratenumberPremiumtransactions / view_count × 100, rounded to 2 decimal places. 0 when view_count is zero.
referral_clicks counts interaction events — the Hub event taxonomy uses interaction as the referral-link click signal. See Analytics Events for the full event type reference.

​
Metric definitions

MetricFormulaNotes
Click-through rateclick_count / view_count × 100Percentage of views that resulted in a click-through.
Conversion ratetransactions / view_count × 100Percentage 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

StatusCodeCondition
400invalid_inputid is not a valid 26-character ULID, or period is not 7d, 30d, or 90d.
401unauthorizedMissing or invalid session token.
403forbiddenAuthenticated user does not own this listing.
404not_foundListing not found.
429rate_limitedIP rate limit exceeded. Retry-After reflects seconds until window reset (≤ 60).
503service_unavailableRate-limit service temporarily unavailable.

​
Tier comparison

MetricBasicFeaturedPremium
view_count✓✓✓
click_count—✓✓
click_through_rate—✓✓
search_impressions——✓
referral_clicks——✓
conversion_rate——✓
To upgrade your listing tier, see Listings.