API credits

API credits are the workspace’s monthly allowance for the API and MCP. They are separate from the research limits and AI credits in the Alura app.

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.

Some calls are free: GET /v1/me, GET /v1/usage, categories and languages, switching workspace, and the saved folders and lists themselves. Nothing is charged for:

errors, of any kind;
a 202 pending answer while Alura fetches something new;
an empty page or an empty result;
items in a bulk call that come back pending, unfetched or not found;
expand=, which adds related objects to a response at no cost.

A repeated call is charged again. Asking twice costs twice. A call is charged once its result is complete, even if your client disconnects or times out before the answer arrives. Retry with care: the retry is a new call.

Allowances

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

The month is the calendar month in UTC, and unused API credits don’t carry over.
On Basic, Growth and Professional, one UTC day can use at most a quarter of the month. Free can spend all 100 in one day.
An upgrade applies at once, and what you used this month counts toward the new allowance.

Some examples, in API credits: analyzing a shop with its profile, a page of its products and a page of its reviews costs 3. Searching for best-selling mugs under $30 and opening 10 of them costs 20. Looking up 20 keywords costs 20.

Seeing what you spend

Every authenticated response carries two headers:

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

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

Running out

What happened	Answer	What to do
The month’s API credits are used up	`402 credits_exhausted`, with `upgrade_url` and `resets_at`	Upgrade, or wait for the next month
Today’s ceiling is reached	`429 daily_credit_cap_exceeded`, with `Retry-After`	Retry after midnight UTC
The credits left are held by calls still running	`429 credits_reserved`, with `Retry-After`	Retry in a few seconds

Before a call runs, Alura holds the most it can cost, then charges what it really cost and gives back the rest. 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

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

Find: 10 API credits per page

Operation	REST	MCP tool	API credits
Search products	`GET /v1/research/products`	`search_products`	10 per page
Find 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 a keyword’s top products	`GET /v1/research/keywords/{id}/products`	`get_keyword_top_results`	10 per page
Get a keyword’s 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 a 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 a shop	`GET /v1/research/shops/{id}`	`get_shop`	1 per call
List a shop’s 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 a keyword	`GET /v1/research/keywords/{id}`	`get_keyword_metrics`	1 per call
Get a product’s tags	`GET /v1/research/products/{id}/tags`	`get_product_tags`	1 per page
Get related keywords	`GET /v1/research/keywords/{id}/related`	`get_related_keywords`	1 per page
Get a keyword’s search history	`GET /v1/research/keywords/{id}/history`	`get_keyword_history`	1 per call
List a shop’s reviews	`GET /v1/research/shops/{id}/reviews`	`get_reviews`	1 per page
List a product’s reviews	`GET /v1/research/products/{id}/reviews`	`get_reviews`	1 per page
Get a product’s sales history	`GET /v1/research/products/{id}/history`	`get_sales_history`	1 per call
Get a shop’s sales history	`GET /v1/research/shops/{id}/history`	`get_sales_history`	1 per call
Look up an Etsy URL or shop name	`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

Free

Operation	REST	MCP tool	API credits
Search categories	`GET /v1/categories`	`browse_categories`	Free
Get a category	`GET /v1/categories/{id}`	`browse_categories`	Free
List languages	`GET /v1/languages`	REST only	Free
Who am I	`GET /v1/me`	REST only	Free
List workspaces	`GET /v1/me/workspaces`	`list_workspaces`	Free
Switch workspace	`POST /v1/me/workspace`	`switch_workspace`	Free
Usage	`GET /v1/usage`	`get_usage`	Free
Usage by day	`GET /v1/usage/by-day`	REST only	Free
Usage events	`GET /v1/usage/events`	REST only	Free
List saved folders	`GET /v1/research/saved/folders`	`list_saved`	Free
Get a saved folder	`GET /v1/research/saved/folders/{id}`	`list_saved`	Free
Create a saved folder	`POST /v1/research/saved/folders`	`create_saved_folder`	Free
Update a saved folder	`PATCH /v1/research/saved/folders/{id}`	`update_saved`	Free
Delete a saved folder	`DELETE /v1/research/saved/folders/{id}`	`delete_saved`	Free
List saved lists	`GET /v1/research/saved/lists`	`list_saved`	Free
Get a saved list	`GET /v1/research/saved/lists/{id}`	`list_saved`	Free
Create a saved list	`POST /v1/research/saved/lists`	`create_saved_list`	Free
Update a saved list	`PATCH /v1/research/saved/lists/{id}`	`update_saved`	Free
Delete a 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

Get started

Concepts

Guides

Research features

Methodology

Resources

Legal

Two prices

Allowances

Seeing what you spend

Running out

Cost of every operation

Find: 10 API credits per page

Retrieve: 1 API credit per call, page or item

Free

​Two prices

​Allowances

​Seeing what you spend

​Running out

​Cost of every operation

​Find: 10 API credits per page

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

​Free

Two prices

Allowances

Seeing what you spend

Running out

Cost of every operation

Find: 10 API credits per page

Retrieve: 1 API credit per call, page or item

Free