> ## Documentation Index
> Fetch the complete documentation index at: https://docs.alura.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Credits and limits

> What calls cost, the monthly and daily allowances, requests per minute, fetch caps and what to do on a 402 or 429

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](https://docs.alura.io/api-reference/workspace/orders/search.md) 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:

```http theme={null}
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](https://docs.alura.io/guides/usage-and-limits.md).

## 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:

```http theme={null}
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:

```json theme={null}
{
  "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](https://docs.alura.io/api-reference/introduction.md#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`](https://docs.alura.io/errors/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`](https://docs.alura.io/errors/daily_credit_cap_exceeded) | `429` | Today's share of the month's API credits is spent. | Retry after the next UTC midnight |
| [`credits_reserved`](https://docs.alura.io/errors/credits_reserved) | `429` | Calls still running hold the API credits this one needs. | Retry in a few seconds |
| [`rate_limited`](https://docs.alura.io/errors/rate_limited) | `429` | Over the plan's requests per minute, per key or per workspace. | Wait for `Retry-After`, then retry |
| [`throttled`](https://docs.alura.io/errors/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`](https://docs.alura.io/errors/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](https://docs.alura.io/guides/handling-errors.md) 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`.

> [accordion] 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 |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.