> ## 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. # 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. ## OpenAPI ````yaml /openapi.json get /v1/workspace/listings/{id} openapi: 3.1.0 info: title: Alura API version: 1.0.0 description: Etsy market research for scripts and AI assistants. servers: - url: https://api.alura.io security: - apiKey: [] paths: /v1/workspace/listings/{id}: get: summary: Get a listing description: >- 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. operationId: workspace.listings.get parameters: - name: id in: path required: true schema: description: The Etsy listing ID. A listing outside the workspace is 404. type: string pattern: ^[0-9]{1,20}$ example: '1834720561' - name: fields in: query required: false description: >- Comma-separated dotted paths to return; `id`, `object` and `as_of` always come back. schema: type: string - name: expand in: query required: false description: >- Comma-separated related objects to include: `inventory`, `attributes`, `translations`, `personalization`, `variation_images`, `score_breakdown`. Free. schema: type: string responses: '200': description: OK headers: Request-Id: $ref: '#/components/headers/Request-Id' Alura-Credits-Cost: $ref: '#/components/headers/Alura-Credits-Cost' Alura-Credits-Remaining: $ref: '#/components/headers/Alura-Credits-Remaining' content: application/json: schema: type: object properties: object: type: string const: workspace.listing id: type: string description: Etsy ID, as a string. shop_id: type: string description: The connected shop the listing belongs to. title: type: - string - 'null' url: description: The listing on Etsy. type: - string - 'null' state: description: >- Etsy's listing state: `active`, `inactive`, `sold_out`, `draft`, `expired`, `edit` or `deleted`. type: - string - 'null' price: anyOf: - type: object properties: amount: type: string description: Decimal string in the listing's own currency. currency: type: string description: ISO 4217 code. usd: description: >- The same price in USD at the request's exchange rates, as a decimal string; null when no rate is known. type: - string - 'null' required: - amount - currency - usd additionalProperties: false description: The listing's price. - type: 'null' quantity: anyOf: - type: integer - type: 'null' image_url: description: The primary image, 570px wide. type: - string - 'null' section: anyOf: - type: object properties: id: type: string description: Etsy ID, as a string. title: type: - string - 'null' required: - id - title additionalProperties: false - type: 'null' description: The shop section; null when the listing is in none. views: anyOf: - type: integer - type: 'null' description: Etsy's lifetime view count. favorites: anyOf: - type: integer - type: 'null' description: Etsy's lifetime favorites count. listing_score: anyOf: - type: integer - type: 'null' description: >- 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). created_at: anyOf: - type: string description: ISO 8601, UTC. - type: 'null' updated_at: anyOf: - type: string description: ISO 8601, UTC. - type: 'null' as_of: anyOf: - type: string description: ISO 8601, UTC. - type: 'null' description: >- When the shop's listings were last synced from Etsy; null when never. description: type: - string - 'null' tags: anyOf: - type: array items: type: string - type: 'null' description: The listing's tags (up to 13); null when unknown. materials: anyOf: - type: array items: type: string - type: 'null' category: anyOf: - type: object properties: id: type: string description: Etsy ID, as a string. path: type: array items: type: string description: >- Etsy's category names, top first; empty when the category is not in Etsy's current taxonomy. required: - id - path additionalProperties: false - type: 'null' skus: anyOf: - type: array items: type: string - type: 'null' has_variations: type: - boolean - 'null' who_made: description: >- Etsy's `who_made`: `i_did`, `someone_else` or `collective`. type: - string - 'null' when_made: description: >- Etsy's `when_made`, for example `made_to_order` or `2020_2026`. type: - string - 'null' is_supply: type: - boolean - 'null' is_digital: description: >- true when the listing comes with a digital download (Etsy listing type `download` or `both`); false for `physical`. type: - boolean - 'null' is_personalizable: type: - boolean - 'null' language: type: - string - 'null' shipping_profile_id: anyOf: - type: string description: Etsy ID, as a string. - type: 'null' return_policy_id: anyOf: - type: string description: Etsy ID, as a string. - type: 'null' processing: anyOf: - type: object properties: min_days: anyOf: - type: integer - type: 'null' max_days: anyOf: - type: integer - type: 'null' required: - min_days - max_days additionalProperties: false - type: 'null' should_auto_renew: type: - boolean - 'null' dimensions: anyOf: - type: object properties: length: type: - number - 'null' width: type: - number - 'null' height: type: - number - 'null' unit: type: - string - 'null' weight: type: - number - 'null' weight_unit: type: - string - 'null' required: - length - width - height - unit - weight - weight_unit additionalProperties: false - type: 'null' description: The item size and weight; null when none is stored. images: anyOf: - type: array items: type: object properties: id: type: string description: Etsy ID, as a string. url: description: Full size. type: - string - 'null' thumbnail_url: description: 570px wide. type: - string - 'null' alt_text: type: - string - 'null' rank: anyOf: - type: integer - type: 'null' width: anyOf: - type: integer - type: 'null' height: anyOf: - type: integer - type: 'null' required: - id - url - thumbnail_url - alt_text - rank - width - height additionalProperties: false - type: 'null' description: >- Every image, in rank order; null while Alura's copy of the listing's media is being rewritten by a sync (`notices` says so). videos: anyOf: - type: array items: type: object properties: id: type: string description: Etsy ID, as a string. url: type: - string - 'null' thumbnail_url: type: - string - 'null' width: anyOf: - type: integer - type: 'null' height: anyOf: - type: integer - type: 'null' state: description: Etsy's video state, for example `active`. type: - string - 'null' required: - id - url - thumbnail_url - width - height - state additionalProperties: false - type: 'null' description: >- The listing's videos in Etsy's order, the featured one first; null like `images`. reviews: anyOf: - type: object properties: count: type: integer description: Reviews of this listing Alura has stored. average: description: The average rating, 1-5; null with no reviews. type: - number - 'null' required: - count - average additionalProperties: false - type: 'null' description: >- null while the shop's reviews were never synced (`notices` says so), never a count of 0. ends_at: anyOf: - type: string description: ISO 8601, UTC. - type: 'null' description: When the listing expires on Etsy unless renewed. notices: type: array items: type: object properties: code: type: string description: >- `media_incomplete` or `reviews_not_synced`. New codes may be added. detail: type: string required: - code - detail additionalProperties: false description: >- Why a part of the listing is unknown right now; empty when nothing is. inventory: x-alura-expansion: inventory description: >- 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. anyOf: - type: object properties: as_of: type: string description: When Alura last fetched this from Etsy. products: type: array items: type: object properties: id: type: string description: Etsy ID, as a string. sku: type: - string - 'null' property_values: type: array items: type: object properties: property_id: type: string description: Etsy ID, as a string. property_name: type: - string - 'null' scale_id: anyOf: - type: string description: Etsy ID, as a string. - type: 'null' scale_name: type: - string - 'null' value_ids: type: array items: type: string description: Etsy ID, as a string. values: type: array items: type: string required: - property_id - property_name - scale_id - scale_name - value_ids - values additionalProperties: false offerings: type: array items: type: object properties: id: type: string description: Etsy ID, as a string. price: anyOf: - type: object properties: amount: type: string description: >- Decimal string in the listing's own currency. currency: type: string description: ISO 4217 code. usd: description: >- The same price in USD at the request's exchange rates, as a decimal string; null when no rate is known. type: - string - 'null' required: - amount - currency - usd additionalProperties: false description: The listing's price. - type: 'null' quantity: anyOf: - type: integer - type: 'null' is_enabled: type: - boolean - 'null' required: - id - price - quantity - is_enabled additionalProperties: false required: - id - sku - property_values - offerings additionalProperties: false required: - as_of - products additionalProperties: false - type: 'null' inventory_error: x-alura-expansion: inventory description: >- 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. anyOf: - type: string enum: - not_fetched - unreadable - type: 'null' attributes: x-alura-expansion: attributes description: >- With `expand=attributes`: the listing's attribute values. null with `attributes_error` when it is not available, never an empty block. anyOf: - type: object properties: as_of: type: string description: When Alura last fetched this from Etsy. values: type: array items: type: object properties: property_id: type: string description: Etsy ID, as a string. property_name: type: - string - 'null' scale_id: anyOf: - type: string description: Etsy ID, as a string. - type: 'null' scale_name: type: - string - 'null' value_ids: type: array items: type: string description: Etsy ID, as a string. values: type: array items: type: string required: - property_id - property_name - scale_id - scale_name - value_ids - values additionalProperties: false required: - as_of - values additionalProperties: false - type: 'null' attributes_error: x-alura-expansion: attributes description: >- 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. anyOf: - type: string enum: - not_fetched - unreadable - type: 'null' translations: x-alura-expansion: translations description: >- With `expand=translations`: the listing's translations, one per language. null with `translations_error` when it is not available, never an empty block. anyOf: - type: object properties: as_of: type: string description: When Alura last fetched this from Etsy. languages: type: array items: type: object properties: language: type: string description: The translation language, for example `de`. title: type: - string - 'null' description: type: - string - 'null' tags: anyOf: - type: array items: type: string - type: 'null' required: - language - title - description - tags additionalProperties: false required: - as_of - languages additionalProperties: false - type: 'null' translations_error: x-alura-expansion: translations description: >- 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. anyOf: - type: string enum: - not_fetched - unreadable - type: 'null' personalization: x-alura-expansion: personalization description: >- With `expand=personalization`: the listing's personalization questions. null with `personalization_error` when it is not available, never an empty block. anyOf: - type: object properties: as_of: type: string description: When Alura last fetched this from Etsy. questions: type: array items: type: object properties: id: type: string description: Etsy ID, as a string. type: description: >- Etsy's question type, for example `text_input` or `unlabeled_upload`. type: - string - 'null' text: type: - string - 'null' instructions: type: - string - 'null' required: type: - boolean - 'null' max_characters: anyOf: - type: integer - type: 'null' max_files: anyOf: - type: integer - type: 'null' options: type: array items: type: object properties: id: anyOf: - type: string description: Etsy ID, as a string. - type: 'null' label: type: - string - 'null' required: - id - label additionalProperties: false description: >- A `dropdown` question's choices or a `labeled_upload` question's upload labels, in Etsy's order; empty for the other types. required: - id - type - text - instructions - required - max_characters - max_files - options additionalProperties: false required: - as_of - questions additionalProperties: false - type: 'null' personalization_error: x-alura-expansion: personalization description: >- 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. anyOf: - type: string enum: - not_fetched - unreadable - type: 'null' variation_images: x-alura-expansion: variation_images description: >- With `expand=variation_images`: which image shows each variation value. null with `variation_images_error` when it is not available, never an empty block. anyOf: - type: object properties: as_of: type: string description: When Alura last fetched this from Etsy. images: type: array items: type: object properties: property_id: type: string description: Etsy ID, as a string. value_id: anyOf: - type: string description: Etsy ID, as a string. - type: 'null' value: type: - string - 'null' image_id: type: string description: Etsy ID, as a string. required: - property_id - value_id - value - image_id additionalProperties: false required: - as_of - images additionalProperties: false - type: 'null' variation_images_error: x-alura-expansion: variation_images description: >- 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. anyOf: - type: string enum: - not_fetched - unreadable - type: 'null' score_breakdown: x-alura-expansion: score_breakdown description: >- 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. anyOf: - type: object properties: version: type: string description: >- The listing score rubric version that computed this breakdown. total: type: integer description: >- The score, 0-100; equals `listing_score` when both come from the same rubric version. sections: type: array items: type: object properties: id: type: string description: >- `photos`, `video`, `title`, `description` or `tags`. label: type: string score: type: number max_score: type: number checks: type: array items: type: object properties: id: type: string label: type: string value: type: string score: type: number max_score: type: number status: type: string description: >- `pass`, `partial`, `fail` or `na` (does not apply). advice: type: string description: >- Alura's advice for this check; it can quote the listing's own tags. required: - id - label - value - score - max_score - status - advice additionalProperties: false required: - id - label - score - max_score - checks additionalProperties: false notices: type: array items: type: object properties: code: type: string description: >- `score_version_mismatch`. New codes may be added. detail: type: string required: - code - detail additionalProperties: false required: - version - total - sections - notices additionalProperties: false - type: 'null' score_breakdown_error: x-alura-expansion: score_breakdown description: >- 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. anyOf: - type: string enum: - media_incomplete - type: 'null' required: - object - id - shop_id - title - url - state - price - quantity - image_url - section - views - favorites - listing_score - created_at - updated_at - as_of - description - tags - materials - category - skus - has_variations - who_made - when_made - is_supply - is_digital - is_personalizable - language - shipping_profile_id - return_policy_id - processing - should_auto_renew - dimensions - images - videos - reviews - ends_at - notices additionalProperties: false example: 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: [] '400': $ref: '#/components/responses/Problem400' '401': $ref: '#/components/responses/Problem401' '402': $ref: '#/components/responses/Problem402' '403': $ref: '#/components/responses/Problem403' '404': $ref: '#/components/responses/Problem404' '405': $ref: '#/components/responses/Problem405' '429': $ref: '#/components/responses/Problem429' '500': $ref: '#/components/responses/Problem500' '503': $ref: '#/components/responses/Problem503' x-codeSamples: - lang: bash label: cURL source: |- curl "https://api.alura.io/v1/workspace/listings/1834720561" \ -H "Authorization: Bearer $ALURA_API_KEY" - lang: typescript label: TypeScript source: >- 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()); - lang: python label: Python source: |- 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)) components: headers: Request-Id: description: '`req_` + ULID; quote it when reporting a problem.' schema: type: string Alura-Credits-Cost: description: API credits this call cost. schema: type: integer Alura-Credits-Remaining: description: >- API credits left in the workspace's monthly allowance, counting calls still in flight. Absent when it cannot be read right now. schema: type: integer responses: Problem400: description: Error content: application/problem+json: schema: $ref: '#/components/schemas/Problem' example: 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 Problem401: description: Error content: application/problem+json: schema: $ref: '#/components/schemas/Problem' example: 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 Problem402: description: Error content: application/problem+json: schema: $ref: '#/components/schemas/Problem' example: 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 Problem403: description: Error content: application/problem+json: schema: $ref: '#/components/schemas/Problem' example: 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 Problem404: description: Error content: application/problem+json: schema: $ref: '#/components/schemas/Problem' example: 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 Problem405: description: Error content: application/problem+json: schema: $ref: '#/components/schemas/Problem' example: 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 Problem429: description: Error content: application/problem+json: schema: $ref: '#/components/schemas/Problem' example: 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 Problem500: description: Error content: application/problem+json: schema: $ref: '#/components/schemas/Problem' example: 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 Problem503: description: Error content: application/problem+json: schema: $ref: '#/components/schemas/Problem' example: 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 schemas: Problem: type: object description: RFC 9457 problem details. properties: type: type: string format: uri title: type: string status: type: integer code: type: string description: A code from the error catalog; new codes may be added. x-extensible-enum: - invalid_request - unknown_parameter - invalid_cursor - cursor_window_exceeded - invalid_reference - id_type_mismatch - invalid_keyword - shop_id_required - sales_window_not_covered - unauthorized - credits_exhausted - plan_required - insufficient_scope - workspace_required - workspace_locked - browser_refused - role_required - impersonation_refused - recent_sign_in_required - etsy_scope_required - etsy_partner_required - not_found - not_found_on_etsy - shop_opted_out - method_not_allowed - conflict - key_limit_reached - reconnect_required - listing_busy - shop_create_busy - idempotency_partial_unverifiable - activation_skipped - idempotency_processing - unprocessable - listing_removed_on_etsy - rate_limited - throttled - daily_credit_cap_exceeded - credits_reserved - fetch_limit_reached - shop_write_budget_exhausted - internal_error - write_misconfigured - upstream_unavailable - credits_unavailable - service_unavailable - fetch_unavailable - create_lock_unavailable - etsy_capacity - upstream_timeout detail: type: string suggestion: type: string retryable: type: boolean request_id: type: string upgrade_url: type: string format: uri description: 'credits_exhausted and plan_required: where to upgrade the plan.' credits_needed: type: integer description: 'API credit refusals: what the call needed.' credits_remaining: type: integer description: >- API credit refusals: what is left (of the month, or of the day for daily_credit_cap_exceeded). resets_at: type: string format: date-time description: >- credits_exhausted and daily_credit_cap_exceeded: when the limit resets. required: - type - title - status - code - detail - suggestion - retryable - request_id securitySchemes: apiKey: type: http scheme: bearer description: 'An API key: `Authorization: Bearer alura_sk_...`.' ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.