Credits and limits

Two things limit what a workspace can do:

API credits are what calls spend, per month and per day.
Rate and fetch limits are how fast you can call, and how many items Alura has never seen you can ask it to fetch from Etsy. Free calls count toward them too.

Every reference page starts with its cost.

Two prices

Find. Calls that discover things, such as search, similar products and trending, cost 10 API credits per page with results.
Retrieve. Calls about something you named, such as a product, a shop, a keyword or one page of a shop’s reviews, cost 1 API credit per call, page or item.

Account calls are free: GET /v1/me, GET /v1/usage, categories, languages and switching workspace. So is everything about saved folders and lists except reading the items in a list. You are never charged for:

an error of any kind;
a 202 while Alura fetches something new;
an empty page or an empty result. One exception: an empty page of Search orders with a search_incomplete notice costs its credit, because it searched part of the orders;
items in a bulk call that come back pending, unfetched or not found;
a write to your Etsy shop that doesn’t land: a dry_run, a write Etsy refuses, or a removal of something Etsy no longer has;
a sync that every shop refuses, such as 429 sync_cooldown;
expand, which adds related objects at no cost.

Every call is charged on its own. Asking the same thing twice costs twice. A call is charged once its result is complete, even if your client disconnects or times out first, so a retry is a new call.

Allowances

Plan	API credits a month	Daily ceiling	Requests per minute
Free	100	None	30
Basic	2,000	500	60
Growth	20,000	5,000	120
Professional	100,000	25,000	300

The month is the calendar month in UTC. Unused API credits don’t carry over.
The daily ceiling caps what one UTC day can spend, so a runaway script can’t use the whole month at once. Free has none.
An upgrade applies at once. What you used this month counts toward the new allowance.

What typical tasks cost

Task	Calls	API credits
Analyze a shop	`GET /v1/research/shops/{id}` with both expansions, one page of `GET /v1/research/shops/{id}/products` and one page of `GET /v1/research/shops/{id}/reviews`	3
Find best-selling mugs and open 10	One page of `GET /v1/research/products`, then `GET /v1/research/products/{id}` 10 times	20
Open 100 products at once	`GET /v1/research/products?ids=` with 100 IDs Alura knows	100
Check 20 keywords	`GET /v1/research/keywords` with 20 `q` values	20

Seeing what you spend

Every authenticated response carries two headers:

Alura-Credits-Cost: 1
Alura-Credits-Remaining: 16579

Header	Description
`Alura-Credits-Cost`	What this call cost. `0` for free calls and errors.
`Alura-Credits-Remaining`	What is left this month, after this call.

MCP results carry the cost in _meta.credits_charged. GET /v1/usage shows the month so far, by operation and by client. GET /v1/usage/events lists every charge from the last 90 days. See Usage and limits.

Rate limits

Plan	Requests per minute
Free	30
Basic	60
Growth	120
Professional	300

The rate is counted per API key and per workspace, so two keys in one workspace share the workspace’s minute. Every response carries the standard headers:

RateLimit-Policy: "key";q=120;w=60, "workspace";q=120;w=60
RateLimit: "key";r=119;t=60, "workspace";r=112;t=60

Header	Description
`RateLimit-Policy`	Each limit: `q` requests per window of `w` seconds.
`RateLimit`	What is left: `r` requests, and `t` seconds until the window resets.
`Retry-After`	On a `429`, the seconds to wait before you retry.

GET /v1/usage also returns your plan’s rate in rate_limit.requests_per_minute.

Fetch caps

Asking for a product, shop or keyword Alura has never seen starts a fetch from Etsy. Fetches have their own limits per workspace: a daily cap for each type and a rate per minute. Items Alura already knows don’t count.

Plan	New shops a day	New products a day	New keywords a day	Shop name lookups a day	Fetches per minute
Free	6	50	50	3	4
Basic	20	200	200	10	10
Growth	50	500	500	25	20
Professional	200	2,000	2,000	100	60

Days are UTC days. Looking up a shop by a name Alura doesn’t know, with GET /v1/research/lookup?name=, counts as a shop name lookup and a new shop. GET /v1/usage shows today’s caps and what you used:

{
  "fetch_caps": {
    "shops": { "limit": 50, "used": 2 },
    "products": { "limit": 500, "used": 14 },
    "keywords": { "limit": 500, "used": 0 },
    "shop_names": { "limit": 25, "used": 1 }
  }
}

A fetch that starts answers 202 and is free. See Freshness.

Sub-list throttle

Asking for the products or reviews of many different shops or products in a short time looks like copying the catalog. When a workspace does that, it is held to a low request rate for an hour, with 429 throttled. Paging through one shop’s products or reviews never triggers it.

When a call is refused

Type	Status	Meaning	What to do
`credits_exhausted`	`402`	This month’s API credits are used up. The error has `upgrade_url` and `resets_at`.	Upgrade, or wait for the next month
`daily_credit_cap_exceeded`	`429`	Today’s share of the month’s API credits is spent.	Retry after the next UTC midnight
`credits_reserved`	`429`	Calls still running hold the API credits this one needs.	Retry in a few seconds
`rate_limited`	`429`	Over the plan’s requests per minute, per key or per workspace.	Wait for `Retry-After`, then retry
`throttled`	`429`	Sub-lists of many different shops or products in a short time.	Wait for `Retry-After`, then retry more slowly
`fetch_limit_reached`	`429`	A daily fetch cap or the per-minute fetch rate.	Wait for `Retry-After` before asking for new items

Every 429 has retryable: true and a Retry-After header. Handling errors has a retry helper in curl, TypeScript and Python. Before a call runs, Alura holds the most it can cost. When it finishes, Alura charges what it really cost and releases the rest. So a bulk call needs enough API credits for every ID up front, even though you pay only for the items that come back.

Cost of every operation

This table is generated from the API’s own operation list, so it always matches what the API charges. The same prices are in each endpoint’s x-alura-credits in the OpenAPI document, and in costs from GET /v1/usage.

Every operation and its price

Find: 10 API credits per page

Operation	REST	MCP tool	API credits
Search products	`GET /v1/research/products`	`search_products`	10 per page
Get similar products	`GET /v1/research/products/{id}/similar`	`find_similar_products`	10 per page
Search shops	`GET /v1/research/shops`	`search_shops`	10 per page
Get similar shops	`GET /v1/research/shops/{id}/similar`	`find_similar_shops`	10 per page
Get top products	`GET /v1/research/keywords/{id}/products`	`get_keyword_top_results`	10 per page
Get top shops	`GET /v1/research/keywords/{id}/shops`	`get_keyword_top_results`	10 per page
Get trending keywords	`GET /v1/research/keywords/trending`	`get_trending`	10 per page
Get trending products	`GET /v1/research/products/trending`	`get_trending`	10 per page
Get trending shops	`GET /v1/research/shops/trending`	`get_trending`	10 per page

Retrieve: 1 API credit per call, page or item

Operation	REST	MCP tool	API credits
Get product	`GET /v1/research/products/{id}`	`get_products`	1 per call
Get products by ID	`GET /v1/research/products`	`get_products`	1 per item returned
Get shop	`GET /v1/research/shops/{id}`	`get_shop`	1 per call
List shop products	`GET /v1/research/shops/{id}/products`	`list_shop_products`	1 per page
Look up keywords	`GET /v1/research/keywords`	`get_keyword_metrics`, `get_related_keywords`, `get_keyword_top_results`, `get_keyword_history`	1 per item returned
Get keyword	`GET /v1/research/keywords/{id}`	`get_keyword_metrics`	1 per call
Get related keywords	`GET /v1/research/keywords/{id}/related`	`get_related_keywords`	1 per page
Get keyword history	`GET /v1/research/keywords/{id}/history`	`get_keyword_history`	1 per call
List shop reviews	`GET /v1/research/shops/{id}/reviews`	`get_reviews`	1 per page
List product reviews	`GET /v1/research/products/{id}/reviews`	`get_reviews`	1 per page
Get product history	`GET /v1/research/products/{id}/history`	`get_sales_history`	1 per call
Get shop history	`GET /v1/research/shops/{id}/history`	`get_sales_history`	1 per call
Get sales histories	`GET /v1/research/history`	`get_sales_history`	1 per item returned
Look up URL or shop	`GET /v1/research/lookup`	`lookup_etsy_url`	1 per call
List saved items	`GET /v1/research/saved/lists/{id}/items`	`get_saved_list_items`	1 per item returned
List all saved items	`GET /v1/research/saved/items`	`get_saved_list_items`	1 per item returned
List shops	`GET /v1/workspace/shops`	`list_my_shops`	1 per page
Get shop	`GET /v1/workspace/shops/{shop_id}`	`get_my_shop`	1 per call
Update shop	`PATCH /v1/workspace/shops/{shop_id}`	REST only	1 per write
Get shop stats	`GET /v1/workspace/stats`	`get_my_shop_stats`	1 per call
List changes	`GET /v1/workspace/changes`	`list_my_changes`	1 per page
Get change	`GET /v1/workspace/changes/{id}`	`list_my_changes`	1 per call
List sections	`GET /v1/workspace/sections`	REST only	1 per page
List shipping profiles	`GET /v1/workspace/shipping-profiles`	REST only	1 per page
Get shipping profile	`GET /v1/workspace/shipping-profiles/{id}`	REST only	1 per call
List destinations	`GET /v1/workspace/shipping-profiles/{id}/destinations`	REST only	1 per page
List delivery upgrades	`GET /v1/workspace/shipping-profiles/{id}/upgrades`	REST only	1 per page
List return policies	`GET /v1/workspace/return-policies`	REST only	1 per page
Get return policy	`GET /v1/workspace/return-policies/{id}`	REST only	1 per call
List profiles	`GET /v1/workspace/processing-profiles`	REST only	1 per page
Get profile	`GET /v1/workspace/processing-profiles/{id}`	REST only	1 per call
Get holiday settings	`GET /v1/workspace/holiday-settings`	REST only	1 per page
List partners	`GET /v1/workspace/production-partners`	REST only	1 per page
Create shipping profile	`POST /v1/workspace/shipping-profiles`	REST only	1 per write
Update shipping profile	`PATCH /v1/workspace/shipping-profiles/{id}`	REST only	1 per write
Delete shipping profile	`DELETE /v1/workspace/shipping-profiles/{id}`	REST only	1 per write
Create destination	`POST /v1/workspace/shipping-profiles/{id}/destinations`	REST only	1 per write
Update destination	`PATCH /v1/workspace/shipping-profiles/{id}/destinations/{destination_id}`	REST only	1 per write
Delete destination	`DELETE /v1/workspace/shipping-profiles/{id}/destinations/{destination_id}`	REST only	1 per write
Create upgrade	`POST /v1/workspace/shipping-profiles/{id}/upgrades`	REST only	1 per write
Update upgrade	`PATCH /v1/workspace/shipping-profiles/{id}/upgrades/{upgrade_id}`	REST only	1 per write
Delete upgrade	`DELETE /v1/workspace/shipping-profiles/{id}/upgrades/{upgrade_id}`	REST only	1 per write
Create profile	`POST /v1/workspace/processing-profiles`	REST only	1 per write
Update profile	`PATCH /v1/workspace/processing-profiles/{id}`	REST only	1 per write
Delete profile	`DELETE /v1/workspace/processing-profiles/{id}`	REST only	1 per write
Update holiday settings	`PATCH /v1/workspace/holiday-settings`	REST only	1 per write
Create section	`POST /v1/workspace/sections`	REST only	1 per write
Update section	`PATCH /v1/workspace/sections/{id}`	REST only	1 per write
Delete section	`DELETE /v1/workspace/sections/{id}`	REST only	1 per write
Create return policy	`POST /v1/workspace/return-policies`	REST only	1 per write
Update return policy	`PATCH /v1/workspace/return-policies/{id}`	REST only	1 per write
Delete return policy	`DELETE /v1/workspace/return-policies/{id}`	REST only	1 per write
Move policy listings	`POST /v1/workspace/return-policies/{id}/move-listings`	REST only	1 per write
Search listings	`GET /v1/workspace/listings`	`search_my_listings`	1 per page
Get listing	`GET /v1/workspace/listings/{id}`	`get_my_listing`	1 per call
Get listing stats	`GET /v1/workspace/listings/{id}/stats`	REST only	1 per call
Search orders	`GET /v1/workspace/orders`	`search_my_orders`	1 per page
Get order	`GET /v1/workspace/orders/{id}`	`get_my_order`	1 per call
Search reviews	`GET /v1/workspace/reviews`	`search_my_reviews`	1 per page
Start sync	`POST /v1/workspace/syncs`	`start_my_sync`	1 per call
Get sync	`GET /v1/workspace/syncs/{id}`	REST only	1 per call
List syncs	`GET /v1/workspace/syncs`	REST only	1 per page
Search customers	`GET /v1/workspace/customers`	`search_my_customers`	1 per page
Get customer	`GET /v1/workspace/customers/{id}`	`search_my_customers`	1 per call
Update listing	`PATCH /v1/workspace/listings/{id}`	`update_my_listing`	1 per write
Delete listing	`DELETE /v1/workspace/listings/{id}`	`update_my_listing`	1 per write
Create listing	`POST /v1/workspace/listings`	`create_my_listing`	1 per write
Duplicate listing	`POST /v1/workspace/listings/{id}/duplicate`	`create_my_listing`	1 per write
Revert change	`POST /v1/workspace/changes/{id}/revert`	`revert_my_change`	1 per write
Add shipment	`POST /v1/workspace/orders/{id}/shipments`	`add_my_shipment`	1 per write
Add images	`POST /v1/workspace/listings/{id}/images`	REST only	1 per write
Remove image	`DELETE /v1/workspace/listings/{id}/images/{image_id}`	REST only	1 per write
Reorder images	`PUT /v1/workspace/listings/{id}/images/order`	REST only	1 per write
Update alt text	`PATCH /v1/workspace/listings/{id}/images/{image_id}`	REST only	1 per write
Add video	`POST /v1/workspace/listings/{id}/videos`	REST only	1 per write
Remove video	`DELETE /v1/workspace/listings/{id}/videos/{video_id}`	REST only	1 per write
Feature video	`PUT /v1/workspace/listings/{id}/videos/featured`	REST only	1 per write
Add file	`POST /v1/workspace/listings/{id}/files`	REST only	1 per write
Remove file	`DELETE /v1/workspace/listings/{id}/files/{file_id}`	REST only	1 per write
Replace inventory	`PUT /v1/workspace/listings/{id}/inventory`	REST only	1 per write
Patch offerings	`PATCH /v1/workspace/listings/{id}/inventory`	REST only	1 per write
Update attributes	`PATCH /v1/workspace/listings/{id}/attributes`	REST only	1 per write
Set translation	`PUT /v1/workspace/listings/{id}/translations/{language}`	REST only	1 per write
Replace personalization	`PUT /v1/workspace/listings/{id}/personalization`	REST only	1 per write
Set variation images	`PUT /v1/workspace/listings/{id}/variation-images`	REST only	1 per write

Free

Operation	REST	MCP tool	API credits
Search categories	`GET /v1/etsy/categories`	`browse_categories`	Free
Get category	`GET /v1/etsy/categories/{id}`	`browse_categories`	Free
Get category properties	`GET /v1/etsy/categories/{id}/properties`	REST only	Free
List currencies	`GET /v1/etsy/currencies`	REST only	Free
Get currency	`GET /v1/etsy/currencies/{code}`	REST only	Free
List countries	`GET /v1/etsy/countries`	REST only	Free
Get country	`GET /v1/etsy/countries/{code}`	REST only	Free
List languages	`GET /v1/etsy/languages`	REST only	Free
Get fees	`GET /v1/etsy/fees`	`get_etsy_fees`	Free
Get listing rules	`GET /v1/etsy/listing-rules`	`get_listing_rules`	Free
Get shipping carriers	`GET /v1/etsy/shipping-carriers`	REST only	Free
List updates	`GET /v1/etsy/updates`	`get_etsy_updates`	Free
Get update	`GET /v1/etsy/updates/{id}`	`get_etsy_updates`	Free
List news	`GET /v1/etsy/news`	`get_etsy_updates`	Free
Get article	`GET /v1/etsy/news/{slug}`	`get_etsy_updates`	Free
List feed	`GET /v1/etsy/feed`	`get_etsy_updates`	Free
Get current user	`GET /v1/me`	REST only	Free
List workspaces	`GET /v1/me/workspaces`	`list_workspaces`	Free
Switch workspace	`POST /v1/me/workspace`	`switch_workspace`	Free
Get usage	`GET /v1/usage`	`get_usage`	Free
Get usage by day	`GET /v1/usage/by-day`	REST only	Free
List usage events	`GET /v1/usage/events`	REST only	Free
List saved folders	`GET /v1/research/saved/folders`	`list_saved`	Free
Get saved folder	`GET /v1/research/saved/folders/{id}`	`list_saved`	Free
Create saved folder	`POST /v1/research/saved/folders`	`create_saved_folder`	Free
Update saved folder	`PATCH /v1/research/saved/folders/{id}`	`update_saved`	Free
Delete saved folder	`DELETE /v1/research/saved/folders/{id}`	`delete_saved`	Free
List saved lists	`GET /v1/research/saved/lists`	`list_saved`	Free
Get saved list	`GET /v1/research/saved/lists/{id}`	`list_saved`	Free
Create saved list	`POST /v1/research/saved/lists`	`create_saved_list`	Free
Update saved list	`PATCH /v1/research/saved/lists/{id}`	`update_saved`	Free
Delete saved list	`DELETE /v1/research/saved/lists/{id}`	`delete_saved`	Free
Add saved items	`POST /v1/research/saved/lists/{id}/items`	`add_to_saved_list`	Free
Remove saved items	`DELETE /v1/research/saved/lists/{id}/items`	`remove_from_saved_list`	Free
Create webhook	`POST /v1/webhooks`	REST only	Free
List webhooks	`GET /v1/webhooks`	REST only	Free
Get webhook	`GET /v1/webhooks/{id}`	REST only	Free
Update webhook	`PATCH /v1/webhooks/{id}`	REST only	Free
Delete webhook	`DELETE /v1/webhooks/{id}`	REST only	Free
List deliveries	`GET /v1/webhooks/{id}/deliveries`	REST only	Free
Send test event	`POST /v1/webhooks/{id}/test`	REST only	Free
Rotate secret	`POST /v1/webhooks/{id}/rotate-secret`	REST only	Free
List events	`GET /v1/events`	REST only	Free
Get event	`GET /v1/events/{id}`	REST only	Free

Overview

Research

Your shop

Etsy

Webhooks & events

Account

Credits and limits

Two prices

Allowances

What typical tasks cost

Seeing what you spend

Rate limits

Fetch caps

Sub-list throttle

When a call is refused

Cost of every operation

Find: 10 API credits per page

Retrieve: 1 API credit per call, page or item

Free

​Two prices

​Allowances

​What typical tasks cost

​Seeing what you spend

​Rate limits

​Fetch caps

​Sub-list throttle

​When a call is refused

​Cost of every operation

​Find: 10 API credits per page

​Retrieve: 1 API credit per call, page or item

​Free

Two prices

Allowances

What typical tasks cost

Seeing what you spend

Rate limits

Fetch caps

Sub-list throttle

When a call is refused

Cost of every operation

Find: 10 API credits per page

Retrieve: 1 API credit per call, page or item

Free