Listing Analytics - ezForge AI

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

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:

{
  "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

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.

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

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.

​Overview

​Get listing analytics

​Path parameters

​Query parameters

​Responses by tier

​Response fields

​Metric definitions

​Error responses

​Tier comparison

Overview

Get listing analytics

Path parameters

Query parameters

Responses by tier

Response fields

Metric definitions

Error responses

Tier comparison