Authoritative clarification needed: Is the Open API views field lifetime or rolling 30 days?

[addtocartseo]

Confirmation

• I confirm this post does NOT contain sensitive data for my account.

Question / discussion

I’m requesting an authoritative clarification about the views field returned for individual listings by Etsy Open API v3.

I am not asking about keyword search volume, Marketplace Insights, or Shop Stats.

I understand that when I call:
GET /v3/application/listings/active?keywords=custom%20sign&limit=100&sort_on=score

the keywords parameter selects matching listings, while results[].views belongs to each individual listing and is not necessarily attributed to that keyword.

The problem is that I have received conflicting information:

1. Etsy Support told me that results[].views represents views from all traffic sources over a rolling 30-day period and is refreshed daily.

2. An Etsy response in Open API Discussion #687 says that listing views are all-time views.

3. The OpenAPI description says views is the number of times a listing has been viewed and is tabulated daily, but it does not mention a rolling 30-day window.

4. Etsy’s listing-renewal documentation indicates that a renewed listing retains its existing view count.

Could someone from the Etsy API team please clarify:

• Is views a cumulative lifetime/all-time total for that listing, or a rolling total covering the previous 30 days?
• Does “tabulated daily” describe only the refresh frequency, or does it indicate a rolling window?
• Does the field have the same meaning when returned by the active-listings, individual-listing, and batch-listings endpoints?
• Are these listing-level views accumulated from all traffic sources and not attributed to the keyword used in the request?
• Does renewing a listing preserve the same cumulative view total?

There is also a contract question: views can appear at runtime in responses from findAllListingsActive, but it does not appear in that endpoint’s declared ShopListing response schema.

Is its presence there officially supported, or should developers retrieve it through getListingsByListingIds?

We need to label this field accurately in a seller research product, so a definitive answer and, ideally, a documentation clarification would be greatly appreciated.

[benjymouse]

+1 It would be nice to get some answers here

[addtocartseo]

+1 again this is crucial

[openapi-support[bot]]

Hi @addtocartseo,

Thank you for consolidating the conflicting information — this is a legitimate documentation gap and we want to address it directly.

---

views: confirmed behavior

The views field represents the number of times a listing has been viewed, tabulated once per day and only for active listings.

Confirmed:

• "Tabulated once per day" describes the refresh cadence, not a measurement window
• The value is preserved across listing renewals (manual and auto-renew)
• The field behaves consistently across findAllListingsActive, getListing, and getListingsByListingIds
• The value reflects traffic from all sources — it is not attributed to any specific keyword or request parameter

---

Schema gap in findAllListingsActive

You correctly identified that views does not appear in the declared schema for findAllListingsActive. This is an omission in our spec. We will correct the spec.

---

On labeling views in your product

views is safe to label as "listing views (updated daily)".
The measurement window semantics will be clarified in the official documentation — we will announce it in this thread when published.

---

Thank you.