cURL
curl "https://api.alura.io/v1/research/lookup?url=https://www.etsy.com/listing/4524717183/personalized-name-mug" \
-H "Authorization: Bearer $ALURA_API_KEY"const res = await fetch('https://api.alura.io/v1/research/lookup?url=https://www.etsy.com/listing/4524717183/personalized-name-mug', {
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/lookup?url=https://www.etsy.com/listing/4524717183/personalized-name-mug",
headers={
"Authorization": f"Bearer {os.environ['ALURA_API_KEY']}",
},
)
with urllib.request.urlopen(request) as response:
print(json.load(response)){
"object": "research.lookup",
"query": {
"url": "https://www.etsy.com/listing/4524717183/personalized-name-mug"
},
"shop": null,
"product": {
"object": "research.product",
"id": "4524717183",
"url": "https://www.etsy.com/listing/4524717183",
"title": "Personalized Name Mug, Custom Coffee Mug",
"state": "active",
"shop": {
"id": "48911633",
"name": "MugCo"
},
"price": {
"amount": "24.99",
"currency": "EUR",
"usd": "27.10"
},
"quantity": 37,
"category": {
"id": "1062",
"path": [
"Home & Living",
"Kitchen & Dining",
"Drink & Barware",
"Drinkware",
"Mugs"
]
},
"tags": [
"personalized mug",
"name mug",
"custom gift"
],
"materials": [
"ceramic"
],
"language": "en-US",
"image_url": "https://i.etsystatic.com/48911633/r/il/0a1b2c/4524717183/il_570xN.4524717183_mug1.jpg",
"images": [
{
"url": "https://i.etsystatic.com/48911633/r/il/0a1b2c/4524717183/il_fullxfull.4524717183_mug1.jpg",
"thumbnail_url": "https://i.etsystatic.com/48911633/r/il/0a1b2c/4524717183/il_570xN.4524717183_mug1.jpg",
"alt_text": "White mug with name",
"rank": 1
}
],
"video": null,
"listed_at": "2023-04-02T10:11:00.000Z",
"attributes": {
"who_made": "i_did",
"when_made": "made_to_order",
"is_digital": false,
"is_personalizable": true,
"is_customizable": false,
"has_variations": true,
"free_shipping": false
},
"favorites": 3120,
"reviews": {
"count": 842,
"average": 4.9
},
"sales": {
"est_lifetime": 6400,
"est_lifetime_revenue_usd": 173440,
"est_monthly_avg": 210,
"est_monthly_avg_revenue_usd": 5691,
"est_last_month": 236,
"est_last_month_revenue_usd": 6396,
"est_trend_3m": 0.12
},
"listing_score": 86,
"as_of": "2026-10-13T09:30:00.000Z",
"refresh": null
}
}{
"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"
}Research
Look up an Etsy URL or shop name
The Etsy shop or product (another seller’s) that an Etsy URL points to, or the shop with a name. url takes https://www.etsy.com/shop/{name}, https://www.etsy.com[/{locale}]/listing/{id}/… and https://{shop}.etsy.com; it is parsed, never opened. Short etsy.me links, bare IDs, other hosts, ports, credentials and http are refused with 400. name matches a shop name exactly, case-insensitively, with no wildcards; when several shops have had the name, 409 conflict lists them as candidates. Send one of url and name. The answer holds the shop or the product as their own detail endpoints return them. A product Alura has not seen, or a shop name it has not seen (Alura looks the name up on Etsy), answers 202 while it is fetched: ask again at Location. A name Etsy does not know is 404 not_found_on_etsy; while fetching is off, a never-seen one is 503 fetch_unavailable. Costs 1 API credit when it returns a shop or product; pending, not found and refused lookups are free. A never-seen shop name counts against the workspace’s daily shop-name lookups and shop fetches.
Cost: 1 API credit per call.
cURL
curl "https://api.alura.io/v1/research/lookup?url=https://www.etsy.com/listing/4524717183/personalized-name-mug" \
-H "Authorization: Bearer $ALURA_API_KEY"const res = await fetch('https://api.alura.io/v1/research/lookup?url=https://www.etsy.com/listing/4524717183/personalized-name-mug', {
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/lookup?url=https://www.etsy.com/listing/4524717183/personalized-name-mug",
headers={
"Authorization": f"Bearer {os.environ['ALURA_API_KEY']}",
},
)
with urllib.request.urlopen(request) as response:
print(json.load(response)){
"object": "research.lookup",
"query": {
"url": "https://www.etsy.com/listing/4524717183/personalized-name-mug"
},
"shop": null,
"product": {
"object": "research.product",
"id": "4524717183",
"url": "https://www.etsy.com/listing/4524717183",
"title": "Personalized Name Mug, Custom Coffee Mug",
"state": "active",
"shop": {
"id": "48911633",
"name": "MugCo"
},
"price": {
"amount": "24.99",
"currency": "EUR",
"usd": "27.10"
},
"quantity": 37,
"category": {
"id": "1062",
"path": [
"Home & Living",
"Kitchen & Dining",
"Drink & Barware",
"Drinkware",
"Mugs"
]
},
"tags": [
"personalized mug",
"name mug",
"custom gift"
],
"materials": [
"ceramic"
],
"language": "en-US",
"image_url": "https://i.etsystatic.com/48911633/r/il/0a1b2c/4524717183/il_570xN.4524717183_mug1.jpg",
"images": [
{
"url": "https://i.etsystatic.com/48911633/r/il/0a1b2c/4524717183/il_fullxfull.4524717183_mug1.jpg",
"thumbnail_url": "https://i.etsystatic.com/48911633/r/il/0a1b2c/4524717183/il_570xN.4524717183_mug1.jpg",
"alt_text": "White mug with name",
"rank": 1
}
],
"video": null,
"listed_at": "2023-04-02T10:11:00.000Z",
"attributes": {
"who_made": "i_did",
"when_made": "made_to_order",
"is_digital": false,
"is_personalizable": true,
"is_customizable": false,
"has_variations": true,
"free_shipping": false
},
"favorites": 3120,
"reviews": {
"count": 842,
"average": 4.9
},
"sales": {
"est_lifetime": 6400,
"est_lifetime_revenue_usd": 173440,
"est_monthly_avg": 210,
"est_monthly_avg_revenue_usd": 5691,
"est_last_month": 236,
"est_last_month_revenue_usd": 6396,
"est_trend_3m": 0.12
},
"listing_score": 86,
"as_of": "2026-10-13T09:30:00.000Z",
"refresh": null
}
}{
"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"
}Authorizations
An API key: Authorization: Bearer alura_sk_....
Query Parameters
An Etsy URL, https only: https://www.etsy.com/shop/{name}, https://www.etsy.com[/{locale}]/listing/{id}/… or https://{shop}.etsy.com. Parsed, never opened.
Example:
"https://www.etsy.com/listing/4524717183/personalized-name-mug"
A shop name, matched exactly and case-insensitively (letters and digits, at most 20).
Pattern:
^[A-Za-z0-9]{1,20}$Comma-separated dotted paths to return; id, object and as_of always come back.
Response
OK
Allowed value:
"research.lookup"The lookup as asked: its url or its name, as sent.
- Option 1
- Option 2
Show child attributes
Show child attributes
The shop the URL or name names, as GET /v1/research/shops/{id} returns it; null when the URL names a product.
Show child attributes
Show child attributes
The product a /listing/ URL names, as GET /v1/research/products/{id} returns it; null when the query names a shop.
Show child attributes
Show child attributes