cURL
curl "https://api.alura.io/v1/research/saved/items?per_list=3" \
-H "Authorization: Bearer $ALURA_API_KEY"const res = await fetch('https://api.alura.io/v1/research/saved/items?per_list=3', {
headers: {
Authorization: `Bearer ${process.env.ALURA_API_KEY}`,
},
});
console.log(await res.json());import json
import os
import urllib.request
request = urllib.request.Request(
"https://api.alura.io/v1/research/saved/items?per_list=3",
headers={
"Authorization": f"Bearer {os.environ['ALURA_API_KEY']}",
},
)
with urllib.request.urlopen(request) as response:
print(json.load(response)){
"object": "list",
"data": [
{
"object": "research.saved_item",
"id": "itm_00000000000000000004000001",
"list_id": "lst_0000000000000000000000001B",
"type": "product",
"ref_id": "4524717183",
"added_at": "2026-09-02T09:00:00.000Z",
"status": "available",
"data": {
"object": "research.product",
"id": "4524717183",
"title": "Personalized Name Mug, Custom Coffee Mug",
"url": "https://www.etsy.com/listing/4524717183",
"shop": {
"id": "48911633",
"name": "MugCo"
},
"price": {
"amount": "24.99",
"currency": "EUR",
"usd": "27.10"
},
"image_url": "https://i.etsystatic.com/48911633/r/il/0a1b2c/4524717183/il_570xN.4524717183_mug1.jpg",
"category": {
"id": "1062",
"path": [
"Home & Living",
"Kitchen & Dining",
"Drink & Barware",
"Drinkware",
"Mugs"
]
},
"sales": {
"est_lifetime": 6400,
"est_monthly_avg": 210,
"est_lifetime_revenue_usd": 173440,
"est_last_month": 236,
"est_trend_3m": 0.12
},
"reviews": {
"count": 842,
"average": 4.9
},
"favorites": 3120,
"listing_score": 86,
"listed_at": "2023-04-02T10:11:00.000Z",
"as_of": "2026-10-13T08:05:00.000Z"
}
},
{
"object": "research.saved_item",
"id": "itm_00000000000000000008000001",
"list_id": "lst_0000000000000000000000001B",
"type": "shop",
"ref_id": "48911633",
"added_at": "2026-09-02T09:00:00.000Z",
"status": "available",
"data": {
"object": "research.shop",
"id": "48911633",
"name": "MugCo",
"url": "https://www.etsy.com/shop/MugCo",
"icon_url": "https://i.etsystatic.com/iusa/0a1b2c/48911633/iusa_fullxfull.48911633_mugco.jpg",
"country": "US",
"category": {
"name": "Home & Living",
"sub_category": "Kitchen & Dining"
},
"sales": {
"lifetime": 48210,
"est_monthly_avg": 1150,
"est_lifetime_revenue_usd": 1272700,
"est_last_month": 1240,
"est_trend_3m": 0.08
},
"reviews": {
"count": 9120,
"average": 4.9
},
"catalog": {
"active_listings": 1661
},
"as_of": "2026-10-13T09:47:00.000Z"
}
},
{
"object": "research.saved_item",
"id": "itm_0000000000000000000C000001",
"list_id": "lst_0000000000000000000000001B",
"type": "keyword",
"ref_id": "88123",
"added_at": "2026-09-02T09:00:00.000Z",
"status": "available",
"data": {
"object": "research.keyword",
"id": "88123",
"keyword": "personalized mug",
"language": "en",
"volume": {
"etsy_monthly": 12400,
"google_monthly": 40500
},
"competition": {
"level": "high",
"competing_listings": 182000
},
"trend": {
"change_3m": 0.12,
"change_yoy": 0.3
},
"market": {
"avg_price_usd": 24.1,
"est_avg_monthly_sales": null
},
"as_of": "2026-10-12T04:00:00.000Z"
}
}
],
"has_more": false,
"next_cursor": null,
"total": {
"value": 3,
"relation": "eq"
},
"summary": {
"lists": [
{
"list_id": "lst_0000000000000000000000001B",
"item_count": 4,
"truncated": true
}
]
}
}{
"type": "https://docs.alura.io/errors/invalid_request",
"title": "Invalid request",
"status": 400,
"code": "invalid_request",
"detail": "Invalid request",
"suggestion": "Fix the request as the detail says, then send it again.",
"retryable": false,
"request_id": "req_01JQ5W3H8M2N4P6R8T0V2X4Z6B"
}{
"type": "https://docs.alura.io/errors/unauthorized",
"title": "Unauthorized",
"status": 401,
"code": "unauthorized",
"detail": "Unauthorized",
"suggestion": "Send a valid API key as `Authorization: Bearer alura_sk_...`.",
"retryable": false,
"request_id": "req_01JQ5W3H8M2N4P6R8T0V2X4Z6B"
}{
"type": "https://docs.alura.io/errors/credits_exhausted",
"title": "API credits exhausted",
"status": 402,
"code": "credits_exhausted",
"detail": "API credits exhausted",
"suggestion": "Upgrade the plan or wait for the monthly reset.",
"retryable": false,
"request_id": "req_01JQ5W3H8M2N4P6R8T0V2X4Z6B"
}{
"type": "https://docs.alura.io/errors/plan_required",
"title": "Plan required",
"status": 403,
"code": "plan_required",
"detail": "Plan required",
"suggestion": "Upgrade the workspace plan to use this operation.",
"retryable": false,
"request_id": "req_01JQ5W3H8M2N4P6R8T0V2X4Z6B"
}{
"type": "https://docs.alura.io/errors/not_found",
"title": "Not found",
"status": 404,
"code": "not_found",
"detail": "Not found",
"suggestion": "Check the ID, or search for it first.",
"retryable": false,
"request_id": "req_01JQ5W3H8M2N4P6R8T0V2X4Z6B"
}{
"type": "https://docs.alura.io/errors/method_not_allowed",
"title": "Method not allowed",
"status": 405,
"code": "method_not_allowed",
"detail": "Method not allowed",
"suggestion": "Use one of the methods in the Allow header.",
"retryable": false,
"request_id": "req_01JQ5W3H8M2N4P6R8T0V2X4Z6B"
}{
"type": "https://docs.alura.io/errors/rate_limited",
"title": "Rate limited",
"status": 429,
"code": "rate_limited",
"detail": "Rate limited",
"suggestion": "Wait for Retry-After, then retry.",
"retryable": true,
"request_id": "req_01JQ5W3H8M2N4P6R8T0V2X4Z6B"
}{
"type": "https://docs.alura.io/errors/internal_error",
"title": "Internal error",
"status": 500,
"code": "internal_error",
"detail": "Internal error",
"suggestion": "Retry; if it keeps failing, report the request_id.",
"retryable": true,
"request_id": "req_01JQ5W3H8M2N4P6R8T0V2X4Z6B"
}{
"type": "https://docs.alura.io/errors/credits_unavailable",
"title": "API credits unavailable",
"status": 503,
"code": "credits_unavailable",
"detail": "API credits unavailable",
"suggestion": "Retry shortly.",
"retryable": true,
"request_id": "req_01JQ5W3H8M2N4P6R8T0V2X4Z6B"
}Items
List all saved items
Read the items of every saved list you can see in one call, each with its list_id and current summary. Use per_list for an overview of what the workspace has saved.
cURL
curl "https://api.alura.io/v1/research/saved/items?per_list=3" \
-H "Authorization: Bearer $ALURA_API_KEY"const res = await fetch('https://api.alura.io/v1/research/saved/items?per_list=3', {
headers: {
Authorization: `Bearer ${process.env.ALURA_API_KEY}`,
},
});
console.log(await res.json());import json
import os
import urllib.request
request = urllib.request.Request(
"https://api.alura.io/v1/research/saved/items?per_list=3",
headers={
"Authorization": f"Bearer {os.environ['ALURA_API_KEY']}",
},
)
with urllib.request.urlopen(request) as response:
print(json.load(response)){
"object": "list",
"data": [
{
"object": "research.saved_item",
"id": "itm_00000000000000000004000001",
"list_id": "lst_0000000000000000000000001B",
"type": "product",
"ref_id": "4524717183",
"added_at": "2026-09-02T09:00:00.000Z",
"status": "available",
"data": {
"object": "research.product",
"id": "4524717183",
"title": "Personalized Name Mug, Custom Coffee Mug",
"url": "https://www.etsy.com/listing/4524717183",
"shop": {
"id": "48911633",
"name": "MugCo"
},
"price": {
"amount": "24.99",
"currency": "EUR",
"usd": "27.10"
},
"image_url": "https://i.etsystatic.com/48911633/r/il/0a1b2c/4524717183/il_570xN.4524717183_mug1.jpg",
"category": {
"id": "1062",
"path": [
"Home & Living",
"Kitchen & Dining",
"Drink & Barware",
"Drinkware",
"Mugs"
]
},
"sales": {
"est_lifetime": 6400,
"est_monthly_avg": 210,
"est_lifetime_revenue_usd": 173440,
"est_last_month": 236,
"est_trend_3m": 0.12
},
"reviews": {
"count": 842,
"average": 4.9
},
"favorites": 3120,
"listing_score": 86,
"listed_at": "2023-04-02T10:11:00.000Z",
"as_of": "2026-10-13T08:05:00.000Z"
}
},
{
"object": "research.saved_item",
"id": "itm_00000000000000000008000001",
"list_id": "lst_0000000000000000000000001B",
"type": "shop",
"ref_id": "48911633",
"added_at": "2026-09-02T09:00:00.000Z",
"status": "available",
"data": {
"object": "research.shop",
"id": "48911633",
"name": "MugCo",
"url": "https://www.etsy.com/shop/MugCo",
"icon_url": "https://i.etsystatic.com/iusa/0a1b2c/48911633/iusa_fullxfull.48911633_mugco.jpg",
"country": "US",
"category": {
"name": "Home & Living",
"sub_category": "Kitchen & Dining"
},
"sales": {
"lifetime": 48210,
"est_monthly_avg": 1150,
"est_lifetime_revenue_usd": 1272700,
"est_last_month": 1240,
"est_trend_3m": 0.08
},
"reviews": {
"count": 9120,
"average": 4.9
},
"catalog": {
"active_listings": 1661
},
"as_of": "2026-10-13T09:47:00.000Z"
}
},
{
"object": "research.saved_item",
"id": "itm_0000000000000000000C000001",
"list_id": "lst_0000000000000000000000001B",
"type": "keyword",
"ref_id": "88123",
"added_at": "2026-09-02T09:00:00.000Z",
"status": "available",
"data": {
"object": "research.keyword",
"id": "88123",
"keyword": "personalized mug",
"language": "en",
"volume": {
"etsy_monthly": 12400,
"google_monthly": 40500
},
"competition": {
"level": "high",
"competing_listings": 182000
},
"trend": {
"change_3m": 0.12,
"change_yoy": 0.3
},
"market": {
"avg_price_usd": 24.1,
"est_avg_monthly_sales": null
},
"as_of": "2026-10-12T04:00:00.000Z"
}
}
],
"has_more": false,
"next_cursor": null,
"total": {
"value": 3,
"relation": "eq"
},
"summary": {
"lists": [
{
"list_id": "lst_0000000000000000000000001B",
"item_count": 4,
"truncated": true
}
]
}
}{
"type": "https://docs.alura.io/errors/invalid_request",
"title": "Invalid request",
"status": 400,
"code": "invalid_request",
"detail": "Invalid request",
"suggestion": "Fix the request as the detail says, then send it again.",
"retryable": false,
"request_id": "req_01JQ5W3H8M2N4P6R8T0V2X4Z6B"
}{
"type": "https://docs.alura.io/errors/unauthorized",
"title": "Unauthorized",
"status": 401,
"code": "unauthorized",
"detail": "Unauthorized",
"suggestion": "Send a valid API key as `Authorization: Bearer alura_sk_...`.",
"retryable": false,
"request_id": "req_01JQ5W3H8M2N4P6R8T0V2X4Z6B"
}{
"type": "https://docs.alura.io/errors/credits_exhausted",
"title": "API credits exhausted",
"status": 402,
"code": "credits_exhausted",
"detail": "API credits exhausted",
"suggestion": "Upgrade the plan or wait for the monthly reset.",
"retryable": false,
"request_id": "req_01JQ5W3H8M2N4P6R8T0V2X4Z6B"
}{
"type": "https://docs.alura.io/errors/plan_required",
"title": "Plan required",
"status": 403,
"code": "plan_required",
"detail": "Plan required",
"suggestion": "Upgrade the workspace plan to use this operation.",
"retryable": false,
"request_id": "req_01JQ5W3H8M2N4P6R8T0V2X4Z6B"
}{
"type": "https://docs.alura.io/errors/not_found",
"title": "Not found",
"status": 404,
"code": "not_found",
"detail": "Not found",
"suggestion": "Check the ID, or search for it first.",
"retryable": false,
"request_id": "req_01JQ5W3H8M2N4P6R8T0V2X4Z6B"
}{
"type": "https://docs.alura.io/errors/method_not_allowed",
"title": "Method not allowed",
"status": 405,
"code": "method_not_allowed",
"detail": "Method not allowed",
"suggestion": "Use one of the methods in the Allow header.",
"retryable": false,
"request_id": "req_01JQ5W3H8M2N4P6R8T0V2X4Z6B"
}{
"type": "https://docs.alura.io/errors/rate_limited",
"title": "Rate limited",
"status": 429,
"code": "rate_limited",
"detail": "Rate limited",
"suggestion": "Wait for Retry-After, then retry.",
"retryable": true,
"request_id": "req_01JQ5W3H8M2N4P6R8T0V2X4Z6B"
}{
"type": "https://docs.alura.io/errors/internal_error",
"title": "Internal error",
"status": 500,
"code": "internal_error",
"detail": "Internal error",
"suggestion": "Retry; if it keeps failing, report the request_id.",
"retryable": true,
"request_id": "req_01JQ5W3H8M2N4P6R8T0V2X4Z6B"
}{
"type": "https://docs.alura.io/errors/credits_unavailable",
"title": "API credits unavailable",
"status": 503,
"code": "credits_unavailable",
"detail": "API credits unavailable",
"suggestion": "Retry shortly.",
"retryable": true,
"request_id": "req_01JQ5W3H8M2N4P6R8T0V2X4Z6B"
}Cost: 1 API credit per item returned.
Lists come oldest first, as List saved lists orders them. Each list’s items come as List saved items orders them: products, then shops, then keywords. Needs the
curl -G "https://api.alura.io/v1/research/saved/items" \
-H "Authorization: Bearer $ALURA_API_KEY" \
--data-urlencode "per_list=3"
saved:read scope.
Items carry the same summaries and status values as a list’s items, and are charged the same way. Reading never fetches anything from Etsy.
Get an overview with per_list
per_list=3 keeps the first 3 items of each list (1 to 25). Without it, every item comes back. type keeps one kind.
total counts the items this read returns, with each list cut at per_list, not every saved item. For the real sizes, read summary.lists:
| Field | Meaning |
|---|---|
list_id | A list with items on this page |
item_count | All its items (of type, when given), not only those returned |
truncated | true when per_list left some out. Read the list with List saved items for the rest. |
Paging while items change
Paging while items change
Items saved or removed while you page may move the window. Each page reserves a charge for every item it can return, then settles to the items with
data. See Pagination and Credits and limits.Authorizations
An API key: Authorization: Bearer alura_sk_....
Query Parameters
Only items of this type: product, shop or keyword.
Available options:
product, shop, keyword At most this many items of each list, 1-25: its first ones (products, then shops, then keywords). Without it, every item.
Pattern:
^[1-9][0-9]?$Example:
"3"
Page size: default 25, at most 100.
Required range:
1 <= x <= 100The next_cursor of the previous page. Bound to the query, the workspace and the key.
Comma-separated dotted paths to return; id, object and as_of always come back.