curl "https://api.alura.io/v1/workspace/listings/1834720561" \
-H "Authorization: Bearer $ALURA_API_KEY"const res = await fetch('https://api.alura.io/v1/workspace/listings/1834720561', {
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/workspace/listings/1834720561",
headers={
"Authorization": f"Bearer {os.environ['ALURA_API_KEY']}",
},
)
with urllib.request.urlopen(request) as response:
print(json.load(response)){
"object": "workspace.listing",
"id": "1834720561",
"shop_id": "22841907",
"title": "Personalized name mug, custom coffee mug with name, 11oz ceramic gift",
"url": "https://www.etsy.com/listing/1834720561/personalized-name-mug",
"state": "active",
"price": {
"amount": "18.50",
"currency": "USD",
"usd": "18.50"
},
"quantity": 37,
"image_url": "https://i.etsystatic.com/22841907/r/il/a1b2c3/5001/il_570xN.5001_mug1.jpg",
"section": {
"id": "3301",
"title": "Mugs"
},
"views": 10600,
"favorites": 2200,
"listing_score": 86,
"created_at": "2024-03-02T10:15:00.000Z",
"updated_at": "2026-10-02T08:30:00.000Z",
"as_of": "2026-10-08T06:00:00.000Z",
"description": "A personalized name mug printed with the name you choose. 11oz white ceramic, dishwasher and microwave safe. Made to order in 1-3 days and shipped in a protective box, ready to gift for birthdays, holidays and thank-yous.",
"tags": [
"personalized mug",
"name mug",
"custom mug",
"coffee mug",
"gift for her",
"birthday gift",
"ceramic mug",
"teacher gift",
"mom gift",
"custom name",
"christmas gift",
"office mug",
"tea mug"
],
"materials": [
"ceramic"
],
"category": {
"id": "1062",
"path": [
"Home & Living",
"Kitchen & Dining",
"Drink & Barware",
"Drinkware",
"Mugs"
]
},
"skus": [
"MUG-NAME-11"
],
"has_variations": true,
"who_made": "i_did",
"when_made": "made_to_order",
"is_supply": false,
"is_digital": false,
"is_personalizable": true,
"language": "en-US",
"shipping_profile_id": "4401",
"return_policy_id": "4501",
"processing": {
"min_days": 1,
"max_days": 3
},
"should_auto_renew": true,
"dimensions": {
"length": 12,
"width": 9,
"height": 10,
"unit": "cm",
"weight": 350,
"weight_unit": "g"
},
"images": [
{
"id": "5001",
"url": "https://i.etsystatic.com/22841907/r/il/a1b2c3/5001/il_fullxfull.5001_mug1.jpg",
"thumbnail_url": "https://i.etsystatic.com/22841907/r/il/a1b2c3/5001/il_570xN.5001_mug1.jpg",
"alt_text": "White personalized name mug on a desk",
"rank": 1,
"width": 2400,
"height": 2400
},
{
"id": "5002",
"url": "https://i.etsystatic.com/22841907/r/il/a1b2c3/5002/il_fullxfull.5002_mug2.jpg",
"thumbnail_url": "https://i.etsystatic.com/22841907/r/il/a1b2c3/5002/il_570xN.5002_mug2.jpg",
"alt_text": "Black personalized name mug",
"rank": 2,
"width": 2400,
"height": 2400
},
{
"id": "5003",
"url": "https://i.etsystatic.com/22841907/r/il/a1b2c3/5003/il_fullxfull.5003_mug3.jpg",
"thumbnail_url": "https://i.etsystatic.com/22841907/r/il/a1b2c3/5003/il_570xN.5003_mug3.jpg",
"alt_text": null,
"rank": 3,
"width": 2400,
"height": 2400
}
],
"videos": [],
"reviews": {
"count": 214,
"average": 4.91
},
"ends_at": "2027-01-02T08:30:00.000Z",
"notices": []
}{
"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"
}Get a listing
One listing of your connected Etsy shops by its listing ID: everything in the search result plus the description, tags, materials, category, SKUs, maker fields, shipping and return policy IDs, processing time, size, images, videos and review count and average. expand= adds the inventory, attributes, translations, personalization and variation images as Alura last fetched them from Etsy (each with its own as_of; null with {name}_error: not_fetched when Alura has not fetched it), and score_breakdown, the listing score section by section. A listing outside the workspace is 404. Needs the Listing analytics workspace permission. Costs 1 API credit per call, expansions included.
Cost: 1 API credit per call.
curl "https://api.alura.io/v1/workspace/listings/1834720561" \
-H "Authorization: Bearer $ALURA_API_KEY"const res = await fetch('https://api.alura.io/v1/workspace/listings/1834720561', {
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/workspace/listings/1834720561",
headers={
"Authorization": f"Bearer {os.environ['ALURA_API_KEY']}",
},
)
with urllib.request.urlopen(request) as response:
print(json.load(response)){
"object": "workspace.listing",
"id": "1834720561",
"shop_id": "22841907",
"title": "Personalized name mug, custom coffee mug with name, 11oz ceramic gift",
"url": "https://www.etsy.com/listing/1834720561/personalized-name-mug",
"state": "active",
"price": {
"amount": "18.50",
"currency": "USD",
"usd": "18.50"
},
"quantity": 37,
"image_url": "https://i.etsystatic.com/22841907/r/il/a1b2c3/5001/il_570xN.5001_mug1.jpg",
"section": {
"id": "3301",
"title": "Mugs"
},
"views": 10600,
"favorites": 2200,
"listing_score": 86,
"created_at": "2024-03-02T10:15:00.000Z",
"updated_at": "2026-10-02T08:30:00.000Z",
"as_of": "2026-10-08T06:00:00.000Z",
"description": "A personalized name mug printed with the name you choose. 11oz white ceramic, dishwasher and microwave safe. Made to order in 1-3 days and shipped in a protective box, ready to gift for birthdays, holidays and thank-yous.",
"tags": [
"personalized mug",
"name mug",
"custom mug",
"coffee mug",
"gift for her",
"birthday gift",
"ceramic mug",
"teacher gift",
"mom gift",
"custom name",
"christmas gift",
"office mug",
"tea mug"
],
"materials": [
"ceramic"
],
"category": {
"id": "1062",
"path": [
"Home & Living",
"Kitchen & Dining",
"Drink & Barware",
"Drinkware",
"Mugs"
]
},
"skus": [
"MUG-NAME-11"
],
"has_variations": true,
"who_made": "i_did",
"when_made": "made_to_order",
"is_supply": false,
"is_digital": false,
"is_personalizable": true,
"language": "en-US",
"shipping_profile_id": "4401",
"return_policy_id": "4501",
"processing": {
"min_days": 1,
"max_days": 3
},
"should_auto_renew": true,
"dimensions": {
"length": 12,
"width": 9,
"height": 10,
"unit": "cm",
"weight": 350,
"weight_unit": "g"
},
"images": [
{
"id": "5001",
"url": "https://i.etsystatic.com/22841907/r/il/a1b2c3/5001/il_fullxfull.5001_mug1.jpg",
"thumbnail_url": "https://i.etsystatic.com/22841907/r/il/a1b2c3/5001/il_570xN.5001_mug1.jpg",
"alt_text": "White personalized name mug on a desk",
"rank": 1,
"width": 2400,
"height": 2400
},
{
"id": "5002",
"url": "https://i.etsystatic.com/22841907/r/il/a1b2c3/5002/il_fullxfull.5002_mug2.jpg",
"thumbnail_url": "https://i.etsystatic.com/22841907/r/il/a1b2c3/5002/il_570xN.5002_mug2.jpg",
"alt_text": "Black personalized name mug",
"rank": 2,
"width": 2400,
"height": 2400
},
{
"id": "5003",
"url": "https://i.etsystatic.com/22841907/r/il/a1b2c3/5003/il_fullxfull.5003_mug3.jpg",
"thumbnail_url": "https://i.etsystatic.com/22841907/r/il/a1b2c3/5003/il_570xN.5003_mug3.jpg",
"alt_text": null,
"rank": 3,
"width": 2400,
"height": 2400
}
],
"videos": [],
"reviews": {
"count": 214,
"average": 4.91
},
"ends_at": "2027-01-02T08:30:00.000Z",
"notices": []
}{
"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_....
Path Parameters
The Etsy listing ID. A listing outside the workspace is 404.
^[0-9]{1,20}$"1834720561"
Query Parameters
Comma-separated dotted paths to return; id, object and as_of always come back.
Comma-separated related objects to include: inventory, attributes, translations, personalization, variation_images, score_breakdown. Free.
Response
OK
"workspace.listing"Etsy ID, as a string.
The connected shop the listing belongs to.
The listing on Etsy.
Etsy's listing state: active, inactive, sold_out, draft, expired, edit or deleted.
The listing's price.
Show child attributes
Show child attributes
The primary image, 570px wide.
The shop section; null when the listing is in none.
Show child attributes
Show child attributes
Etsy's lifetime view count.
Etsy's lifetime favorites count.
Alura's listing score, 1-100, as stored at the last sync; null when the listing was never scored (it matches no listing score filter).
ISO 8601, UTC.
ISO 8601, UTC.
When the shop's listings were last synced from Etsy; null when never.
The listing's tags (up to 13); null when unknown.
Show child attributes
Show child attributes
Etsy's who_made: i_did, someone_else or collective.
Etsy's when_made, for example made_to_order or 2020_2026.
true when the listing comes with a digital download (Etsy listing type download or both); false for physical.
Etsy ID, as a string.
Etsy ID, as a string.
Show child attributes
Show child attributes
The item size and weight; null when none is stored.
Show child attributes
Show child attributes
Every image, in rank order; null while Alura's copy of the listing's media is being rewritten by a sync (notices says so).
Show child attributes
Show child attributes
The listing's videos in Etsy's order, the featured one first; null like images.
Show child attributes
Show child attributes
null while the shop's reviews were never synced (notices says so), never a count of 0.
Show child attributes
Show child attributes
When the listing expires on Etsy unless renewed.
Why a part of the listing is unknown right now; empty when nothing is.
Show child attributes
Show child attributes
With expand=inventory: the listing's products, their property values and offerings. null with inventory_error when it is not available, never an empty block.
Show child attributes
Show child attributes
With expand=inventory: why inventory is null (not_fetched: Alura has not fetched it from Etsy yet; unreadable: what is stored cannot be read). null when inventory is present.
not_fetched, unreadable With expand=attributes: the listing's attribute values. null with attributes_error when it is not available, never an empty block.
Show child attributes
Show child attributes
With expand=attributes: why attributes is null (not_fetched: Alura has not fetched it from Etsy yet; unreadable: what is stored cannot be read). null when attributes is present.
not_fetched, unreadable With expand=translations: the listing's translations, one per language. null with translations_error when it is not available, never an empty block.
Show child attributes
Show child attributes
With expand=translations: why translations is null (not_fetched: Alura has not fetched it from Etsy yet; unreadable: what is stored cannot be read). null when translations is present.
not_fetched, unreadable With expand=personalization: the listing's personalization questions. null with personalization_error when it is not available, never an empty block.
Show child attributes
Show child attributes
With expand=personalization: why personalization is null (not_fetched: Alura has not fetched it from Etsy yet; unreadable: what is stored cannot be read). null when personalization is present.
not_fetched, unreadable With expand=variation_images: which image shows each variation value. null with variation_images_error when it is not available, never an empty block.
Show child attributes
Show child attributes
With expand=variation_images: why variation_images is null (not_fetched: Alura has not fetched it from Etsy yet; unreadable: what is stored cannot be read). null when variation_images is present.
not_fetched, unreadable With expand=score_breakdown: the listing score computed now from the stored listing, section by section; null with score_breakdown_error when it cannot be computed.
Show child attributes
Show child attributes
With expand=score_breakdown: why score_breakdown is null (media_incomplete: Alura's copy of the images and videos is being rewritten, so a score now would be wrong); null when it is present.
media_incomplete