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

# API credits

> The monthly API credit allowance, what each call costs, what is free and what happens when you run out

API credits are what API and MCP calls spend. Each workspace gets a monthly allowance from its plan. API credits 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.

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;
* items in a bulk call that come back pending, unfetched or not found;
* `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](/guides/usage-and-limits).

## Running out

| Type | Meaning | What to do |
| - | - | - |
| [`credits_exhausted`](/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`](/errors/daily_credit_cap_exceeded) | `429`. Today's ceiling is reached. | Retry after midnight UTC |
| [`credits_reserved`](/errors/credits_reserved) | `429`. Calls still running hold the API credits this one needs. | Retry in a few seconds |

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`.

### 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 |
| Get the 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 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 |


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