Alot of questions, please help!

[addtocartseo]

Confirmation

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

Question / discussion

I’m looking for clarification on the data contract for the Etsy Open API v3 active-listings endpoint:

GET /v3/application/listings/active

Example parameters:
keywords=3d business sign custom signs company
limit=100
offset=0
sort_on=score

One returned result was listing ID 1734331116, with:

{
"listing_id": 1734331116,
"views": 394691
}

Etsy Support previously described results[].views as activity from a rolling 30-day period, refreshed daily and aggregated from all traffic sources. However, it is unclear whether that explanation applies to the individual listing’s views field or whether it referred to a separate keyword-level metric.

Could Etsy please clarify the following?

results[].views

1. Is results[].views the listing’s cumulative/lifetime view count, or a rolling-period count?

2. If it is rolling, what is the exact window: 30 calendar days, the previous 720 hours, or something else?

3. When is it refreshed, and what timezone or cutoff is used?

4. Can the value decrease when older activity leaves the measurement window?

5. Does it persist across listing renewals, expiration/reactivation, and quantity renewals?

6. Does the field represent page-view events or unique visitors?

7. Does it include traffic from Etsy search, Etsy Ads, direct visits, external sources, and the seller’s own visits?

8. Are bot traffic, internal Etsy activity, or repeated views filtered?

9. Does views have the same definition across every endpoint that returns a ShopListing?

10. Can the field be delayed, capped, estimated, missing, or null?
    Keyword relationship

11. Does the keywords parameter only determine which listings are returned?

12. Is each returned listing’s views value its overall listing activity, with no attribution to the requested keyword?

13. Does Etsy expose any separate API field or endpoint for:

    • Views attributed to a particular keyword
    • Keyword searches
    • Keyword impressions
    • Keyword clicks
    • Historical or date-filtered keyword analytics
      I am not assuming that listing views represent keyword search volume. I specifically want to confirm whether keyword-attributed activity exists separately.

Result count and matching behavior
14. Does the top-level count represent the complete number of active listings matching the request before pagination?

15. Is count exact, estimated, capped, or cached?

16. Which indexed information can satisfy keywords: title, tags, description, taxonomy, attributes, or other fields?

17. Does a multiword keyword request use exact-phrase matching, all-token matching, any-token matching, or a relevance-based combination?

sort_on=score
18. Does sort_on=score represent Etsy API relevance for the supplied keywords?

19. Is this ordering non-personalized, or can locale, region, account, request history, or other contextual signals affect it?

20. Is the ordering expected to be deterministic for identical requests made close together?

I’m not requesting Etsy’s private ranking formula. I’m only trying to label API-derived metrics accurately and avoid representing listing views as lifetime, recent, keyword-attributed, or search-volume data without confirmation.

It would be very helpful if these semantics could be added to the official API documentation.

Thank you team!

[openapi-support[bot]]

Hi @addtocartseo,

Thank you for the thorough writeup

results[].views

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

Confirmed behavior:

• The value belongs to the listing, not the request — it has no relationship to the keywords parameter you used
• The value is preserved across listing renewals
• It represents page views, not unique visitors
• It can be 0 if the listing was not active at last tabulation, hasn't been tabulated yet, or if there was a fetch error
• The field behaves consistently across findAllListingsActive, getListing, and getListingsByListingIds

---

keywords parameter

keywords is a search filter — it determines which listings are returned, nothing more. The API does not expose per-keyword view attribution, keyword impressions, clicks, search volume, or historical keyword analytics. These are not available through the Open API v3.

---

count field

count represents the total number of matching results before pagination. For search-backed endpoints at scale, this value may be approximate for large result sets. We'll document this explicitly.

---

sort_on=score

Sorts by Etsy's search relevance score for the supplied query. The ranking algorithm is proprietary and not publicly documented. The ordering is not personalized to the requesting user in the Open API context, and is not guaranteed to be strictly deterministic across identical requests.

---

On labeling views in your product

views is safe to label as "listing views (updated daily)". It should not be labeled as keyword-attributed or as a proxy for keyword search volume. Once we confirm the measurement window we will update this thread — at that point the label can be made more precise.

---

We'll address the documentation gaps your questions uncovered. Thank you.