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

# Saved research

> MCP tools to read, create, change and delete saved folders, lists and items

These tools work with the saved research of the connection's current workspace: the same folders and lists you see in the Alura app. Reading needs **See saved research** (`saved:read`); everything else needs **Save research for you** (`saved:write`). Saving and changing are free. Reading a list's items costs 1 API credit per item with data, with `get_saved_list_items`.

## Try these prompts

Claude and GPT picked the tools shown for these prompts in Alura's evaluation runs.

| Ask your assistant | Tools it uses |
| - | - |
| What saved lists do I have in Alura? | `list_saved` |
| What's in my 'Jewelry ideas' list? | `list_saved`, then `get_saved_list_items` |
| Create a new list called 'Tumbler research' and add Etsy listing \[ID] to it. | `create_saved_list`, then `add_to_saved_list` |
| Save the keyword 'gift for mom' to my 'Jewelry ideas' list. | `list_saved`, then `add_to_saved_list` |
| Rename my 'Tumbler research' list to 'Tumbler competitors'. | `list_saved`, then `update_saved` |
| Remove Etsy listing \[ID] from my 'Jewelry ideas' list. | `list_saved`, then `remove_from_saved_list` |

## Good to know

* **Three tools are destructive.** `delete_saved` deletes a folder or list, and Alura support can restore it within 7 days. `remove_from_saved_list` removes items, and removed items can't be restored. `update_saved` overwrites a name, folder or visibility the whole workspace sees. Most assistants ask you before each.
* **Plans cap saved items** per workspace: Free workspaces can read but not save, Basic saves up to 250 items, Growth 5,000 and Professional 100,000. [Saved research](/features/saved-research) explains how this differs from the app.
* **Private lists** are visible only to the person who created them, and the assistant acts as you. Global and public lists from the app aren't available.
* **Only known items.** `add_to_saved_list` saves products and shops Alura already has, from a search or lookup. It never fetches from Etsy.
* **Mature listings** in a list show as `unavailable` over MCP. See [Mature listings](/mcp/tools#mature-listings).
* **Safe to repeat.** Creating a folder or list that already exists returns it, and adding an item twice keeps one copy.

## Tools

### `list_saved`

**List saved research.** List the workspace's saved research: its lists (the default; each with its folder and how many products, shops and keywords it holds) or its folders, or get one folder or list by `id`. Use it to find a list to read or save into, or to check what the user has saved. Pass folder\_id to see one folder's lists.

* **Cost of `list_saved`:** Free (0 API credits).
* **Behavior:** Read-only: changes nothing. Works on Alura's own data only.
* **Scope:** `saved:read` (see saved research).
* **REST:** [`GET /v1/research/saved/lists`](/api-reference/research/saved/lists/list), [`GET /v1/research/saved/folders`](/api-reference/research/saved/folders/list), [`GET /v1/research/saved/lists/{id}`](/api-reference/research/saved/lists/get), [`GET /v1/research/saved/folders/{id}`](/api-reference/research/saved/folders/get).

| Argument | Type | Required | Description |
| - | - | - | - |
| `kind` | `lists`, `folders` | No | `lists` (default) or `folders`. |
| `id` | string | No | One folder (`fld_...`) or list (`lst_...`) by its ID, instead of a page of them. |
| `folder_id` | string | No | Only the lists in this folder (`fld_...`, from list\_saved with kind folders). |
| `cursor` | string | No | next\_cursor from the previous page. |
| `detail` | `concise`, `detailed` | No | `detailed` (default): every field this tool shows. `concise`: the key fields only, for long lists or a quick check. |

### `get_saved_list_items`

**Read a saved list.** Read the items saved in a list (list\_id from list\_saved): each product, shop or keyword with its current research summary (price, estimated sales and revenue, reviews; for keywords search volume, competition and trend). An item Alura no longer has, or whose shop opted out of Alura, comes back without data, free. Pass type to read one kind, and next\_cursor back as cursor for more. Use it when the user asks about research they saved.

* **Cost of `get_saved_list_items`:** 1 API credit per item returned.
* **Behavior:** Read-only: changes nothing. Works on Alura's own data only.
* **Scope:** `saved:read` (see saved research).
* **REST:** [`GET /v1/research/saved/lists/{id}/items`](/api-reference/research/saved/items/list).

| Argument | Type | Required | Description |
| - | - | - | - |
| `list_id` | string | Yes | The list ID (`lst_...`), from list\_saved. |
| `type` | `product`, `shop`, `keyword` | No | Only items of this type: `product`, `shop` or `keyword`. |
| `cursor` | string | No | next\_cursor from the previous page of the same list. |
| `limit` | integer | No | Items per page, 1-25 (default 20). |
| `detail` | `concise`, `detailed` | No | `detailed` (default): every field this tool shows. `concise`: the key fields only, for long lists or a quick check. |

**Example arguments**

```json theme={null}
{
  "list_id": "lst_0000000000000000000000001B"
}
```

### `create_saved_folder`

**Create a saved folder.** Create a folder for saved lists in the workspace (folders hold lists, one level deep). If you can already see a folder with exactly this name, it is returned instead of a second one. It shows up in the Alura app. Use it when the user wants to group lists.

* **Cost of `create_saved_folder`:** Free (0 API credits).
* **Behavior:** Writes data. It only adds; it never changes or removes anything that exists. Safe to repeat. A second call with the same name returns the folder the first one made.
* **Scope:** `saved:write` (save research).
* **REST:** [`POST /v1/research/saved/folders`](/api-reference/research/saved/folders/create).

| Argument | Type | Required | Description |
| - | - | - | - |
| `name` | string | Yes | The folder name, 1-200 characters. |
| `visibility` | `workspace`, `private` | No | `workspace` (the default): every member of the workspace sees it. `private`: only its creator (the person whose key or grant this is) sees it, in the API and in the Alura app. |
| `detail` | `concise`, `detailed` | No | `detailed` (default): every field this tool shows. `concise`: the key fields only, for long lists or a quick check. |

**Example arguments**

```json theme={null}
{
  "name": "Mug ideas"
}
```

### `create_saved_list`

**Create a saved list.** Create a list for saved products, shops and keywords, in a folder (folder\_id from list\_saved) or on its own. If you can already see a list with exactly this name in the same place, it is returned instead of a second one. It shows up in the Alura app. Use it before add\_to\_saved\_list when no list fits.

* **Cost of `create_saved_list`:** Free (0 API credits).
* **Behavior:** Writes data. It only adds; it never changes or removes anything that exists. Safe to repeat. A second call with the same name and folder returns the list the first one made.
* **Scope:** `saved:write` (save research).
* **REST:** [`POST /v1/research/saved/lists`](/api-reference/research/saved/lists/create).

| Argument | Type | Required | Description |
| - | - | - | - |
| `name` | string | Yes | The list name, 1-200 characters. |
| `folder_id` | string | No | The folder to put it in (`fld_...`); leave out for a list on its own. |
| `visibility` | `workspace`, `private` | No | `workspace` (the default): every member of the workspace sees it. `private`: only its creator (the person whose key or grant this is) sees it, in the API and in the Alura app. |
| `detail` | `concise`, `detailed` | No | `detailed` (default): every field this tool shows. `concise`: the key fields only, for long lists or a quick check. |

**Example arguments**

```json theme={null}
{
  "name": "Ceramic mugs under $30"
}
```

### `update_saved`

**Rename or move saved research.** Rename a saved folder or list, change its visibility, or move a list into a folder or out of one (folder\_id "root"). Only its creator, or a workspace owner or admin, can change it. Use it when the user asks to rename, move or share saved research.

* **Cost of `update_saved`:** Free (0 API credits).
* **Behavior:** **Destructive.** It overwrites a folder's or list's name, folder or visibility, which every member of the workspace sees. Safe to repeat. Repeating the same update leaves the folder or list as the first call did.
* **Scope:** `saved:write` (save research).
* **REST:** [`PATCH /v1/research/saved/lists/{id}`](/api-reference/research/saved/lists/update), [`PATCH /v1/research/saved/folders/{id}`](/api-reference/research/saved/folders/update).

| Argument | Type | Required | Description |
| - | - | - | - |
| `id` | string | Yes | The folder (`fld_...`) or list (`lst_...`) ID, from list\_saved. |
| `name` | string | No | A new name. |
| `visibility` | `workspace`, `private` | No | `workspace` (the default): every member of the workspace sees it. `private`: only its creator (the person whose key or grant this is) sees it, in the API and in the Alura app. |
| `folder_id` | string | No | Lists only: the folder to move it into (`fld_...`), or "root" to take it out of its folder. |
| `detail` | `concise`, `detailed` | No | `detailed` (default): every field this tool shows. `concise`: the key fields only, for long lists or a quick check. |

**Example arguments**

```json theme={null}
{
  "id": "lst_0000000000000000000000001B",
  "name": "Mugs under $30"
}
```

### `add_to_saved_list`

**Save to a list.** Save products, shops and keywords into a list (list\_id from list\_saved or create\_saved\_list), up to 100 at once, all or nothing. Items already in the list are left as they are. Only items Alura already has (from a search, lookup or get): an unknown one is refused by name and nothing is added. The workspace plan caps how many items it can save, and some plans cannot save items. Use it when the user asks to save, bookmark or keep track of something.

* **Cost of `add_to_saved_list`:** Free (0 API credits).
* **Behavior:** Writes data. It only adds; it never changes or removes anything that exists. Safe to repeat. Adding an item that is already in the list changes nothing, so repeating a call leaves the list as the first one did.
* **Scope:** `saved:write` (save research).
* **REST:** [`POST /v1/research/saved/lists/{id}/items`](/api-reference/research/saved/items/add).

| Argument | Type | Required | Description |
| - | - | - | - |
| `list_id` | string | Yes | The list ID (`lst_...`), from list\_saved. |
| `items` | object\[] | Yes | The items to save, 1-100; types can be mixed. |
| `detail` | `concise`, `detailed` | No | `detailed` (default): every field this tool shows. `concise`: the key fields only, for long lists or a quick check. |

**Example arguments**

```json theme={null}
{
  "list_id": "lst_0000000000000000000000001B",
  "items": [
    {
      "type": "product",
      "id": "4524717183"
    }
  ]
}
```

### `remove_from_saved_list`

**Remove from a list.** Remove items from a saved list, up to 100 at once: by item\_ids (the `itm_...` ids get\_saved\_list\_items returns), or by items (type and id, or a keyword's text). An item named by type that is not in the list is skipped. Use it when the user asks to remove items. Removed items are not kept and cannot be restored.

* **Cost of `remove_from_saved_list`:** Free (0 API credits).
* **Behavior:** **Destructive.** It removes saved research the whole workspace may use, and removed items are not kept for restoring. Safe to repeat. Removing what is already removed changes nothing more (by item id the second call answers not\_found).
* **Scope:** `saved:write` (save research).
* **REST:** [`DELETE /v1/research/saved/lists/{id}/items`](/api-reference/research/saved/items/remove).

| Argument | Type | Required | Description |
| - | - | - | - |
| `list_id` | string | Yes | The list ID (`lst_...`), from list\_saved. |
| `item_ids` | string\[] | No | Saved item IDs (`itm_...`) from get\_saved\_list\_items. |
| `items` | object\[] | No | Items by type and id (or a keyword's text). |
| `detail` | `concise`, `detailed` | No | `detailed` (default): every field this tool shows. `concise`: the key fields only, for long lists or a quick check. |

**Example arguments**

```json theme={null}
{
  "list_id": "lst_0000000000000000000000001B",
  "item_ids": [
    "itm_00000000000000000004000001"
  ]
}
```

### `delete_saved`

**Delete a saved folder or list.** Delete a saved folder or list. A list goes with its saved items. A folder that holds lists needs lists: "move\_to\_root" (keep them) or "delete" (delete them too). Only its creator, or a workspace owner or admin, can delete it. Use it when the user asks to delete saved research. Alura support can restore a deleted folder or list for 7 days.

* **Cost of `delete_saved`:** Free (0 API credits).
* **Behavior:** **Destructive.** It deletes saved research the whole workspace may use; only Alura support can restore it, within 7 days. Safe to repeat. Deleting what is already deleted changes nothing more (the second call answers not\_found).
* **Scope:** `saved:write` (save research).
* **REST:** [`DELETE /v1/research/saved/lists/{id}`](/api-reference/research/saved/lists/delete), [`DELETE /v1/research/saved/folders/{id}`](/api-reference/research/saved/folders/delete).

| Argument | Type | Required | Description |
| - | - | - | - |
| `id` | string | Yes | The folder (`fld_...`) or list (`lst_...`) ID, from list\_saved. |
| `lists` | `move_to_root`, `delete` | No | Folders that hold lists: `move_to_root` keeps the lists, `delete` deletes them too. |
| `detail` | `concise`, `detailed` | No | `detailed` (default): every field this tool shows. `concise`: the key fields only, for long lists or a quick check. |

**Example arguments**

```json theme={null}
{
  "id": "lst_0000000000000000000000001B"
}
```


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