Saved research - Alura API

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 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.
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, GET /v1/research/saved/folders, GET /v1/research/saved/lists/{id}, GET /v1/research/saved/folders/{id}.

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.

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

{
  "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.

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` is not accepted yet.
`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

{
  "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.

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` is not accepted yet.
`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

{
  "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}, PATCH /v1/research/saved/folders/{id}.

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` is not accepted yet.
`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

{
  "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.

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

{
  "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.

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

{
  "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}, DELETE /v1/research/saved/folders/{id}.

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

{
  "id": "lst_0000000000000000000000001B"
}

​Try these prompts

​Good to know

​Tools

​list_saved

​get_saved_list_items

​create_saved_folder

​create_saved_list

​update_saved

​add_to_saved_list

​remove_from_saved_list

​delete_saved

Try these prompts

Good to know

Tools

`list_saved`

`get_saved_list_items`

`create_saved_folder`

`create_saved_list`

`update_saved`

`add_to_saved_list`

`remove_from_saved_list`

`delete_saved`