Skip to main content
Alura serves Etsy data from its own copy. as_of and refresh tell you how current an answer is.

​
as_of

Every product, shop and keyword has as_of: the moment its data was last updated from Etsy. In search results it is when Alura’s search copy was last updated, which can differ from the detail’s. It is null when Alura doesn’t know.

​
Stale data and refresh

A product or shop whose as_of is more than 14 days old is stale. When you open one with GET /v1/research/products/{id} or GET /v1/research/shops/{id}, Alura returns the data it has right away, charged as usual, and starts a refresh. The response’s refresh object says how it is going:
refresh is null when nothing is running. Ask again after estimated_ready_at to get the new data. A shop takes a few minutes; a product a few seconds. Search, expansions, reviews, tags and saved items never start a refresh.

​
Items Alura has never seen

Opening a product or shop Alura has never seen, or looking up a keyword it doesn’t know, asks Etsy for it. That is a fetch:
  • If the fetch starts, the answer is 202 Accepted with Retry-After and a Location to poll, and costs nothing. Poll the Location after Retry-After seconds.
  • If Etsy says the item doesn’t exist, the answer is 404 not_found_on_etsy. Alura remembers that for 24 hours.
  • Fetches have their own limits per workspace: a daily cap for shops, products and keywords, and a per-minute rate. Over a limit, the answer is 429 fetch_limit_reached with Retry-After. GET /v1/usage shows the day’s caps in fetch_caps.
Bulk calls split their IDs into four lists instead of failing: data (known items), pending (a fetch started), unfetched (no fetch started, with a code and retry_after seconds) and not_found. Only data is charged. See Bulk lookups.
Fetching items Alura has never seen is switched off for now. Opening one answers 503 fetch_unavailable, bulk calls list them in unfetched with the code fetch_unavailable, and stale data comes back with refresh: null. Everything Alura already knows works as usual. The status page says when this changes.