> ## 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. # List your shops > Lists the Etsy shops connected to your workspace: name, currency, active and digital listings, reviews, the Etsy connection (whether it needs reconnecting, and what it lets Alura do), the latest sync and when the next one is allowed, and when Alura last stored each shop. Covers every connected shop unless `shop_id` narrows it; a shop outside the workspace is 404. `summary` gives each shop's data time, a `stale_shops` notice for shops not synced for 7 days and a `sales_not_covered` notice for shops Alura's sales data does not cover yet. Costs 1 API credit per page with shops; a workspace with none is free. Cost: 1 API credit per page. ## OpenAPI ````yaml /openapi.json get /v1/workspace/shops 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/shops: get: summary: List your shops description: >- Lists the Etsy shops connected to your workspace: name, currency, active and digital listings, reviews, the Etsy connection (whether it needs reconnecting, and what it lets Alura do), the latest sync and when the next one is allowed, and when Alura last stored each shop. Covers every connected shop unless `shop_id` narrows it; a shop outside the workspace is 404. `summary` gives each shop's data time, a `stale_shops` notice for shops not synced for 7 days and a `sales_not_covered` notice for shops Alura's sales data does not cover yet. Costs 1 API credit per page with shops; a workspace with none is free. Cost: 1 API credit per page. operationId: workspace.shops.list parameters: - name: shop_id in: query required: false description: >- Only these connected shops, comma-separated; default every connected shop of the workspace. A shop outside the workspace is 404. schema: description: >- Only these connected shops, comma-separated; default every connected shop of the workspace. A shop outside the workspace is 404. type: array items: type: string style: form explode: true - name: limit in: query required: false description: 'Page size: default 25, at most 100.' schema: type: integer minimum: 1 maximum: 100 - name: cursor in: query required: false description: >- The `next_cursor` of the previous page. Bound to the query, the workspace and the key. schema: type: string - name: fields in: query required: false description: >- Comma-separated dotted paths to return; `id`, `object` and `as_of` always come back. 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: list data: type: array items: type: object properties: object: type: string const: workspace.shop id: type: string description: The Etsy shop ID, as a string. name: description: >- The shop's Etsy name; null until Alura has stored the shop. type: - string - 'null' url: description: The shop on Etsy. type: - string - 'null' icon_url: type: - string - 'null' currency: description: ISO 4217 code of the shop's listing prices. type: - string - 'null' catalog: type: object properties: active_listings: anyOf: - type: integer - type: 'null' digital_listings: anyOf: - type: integer - type: 'null' required: - active_listings - digital_listings additionalProperties: false reviews: type: object properties: count: anyOf: - type: integer - type: 'null' average: description: null when there are no reviews. type: - number - 'null' required: - count - average additionalProperties: false connection: type: object properties: status: type: string enum: - ok - reconnect_required description: >- `reconnect_required`: the shop's Etsy connection has ended; its stored data is still served, but nothing can change it on Etsy until it is reconnected. reconnect_url: description: >- Where the shop is reconnected, when it needs to be; else null. type: - string - 'null' capabilities: type: object properties: delete_listings: type: string description: >- Whether Alura may delete listings: `available` when the connection asked Etsy for listing deletion, `restricted` when it did not (reconnect to add it), `unknown` when Alura holds no record of it. shipments: type: string description: >- Whether Alura may add shipments. `unknown` until Alura has tried (Etsy limits it in some regions). buyer_address: type: string description: >- Whether Etsy gives Alura buyers' addresses. `unknown` until Alura has seen it. required: - delete_listings - shipments - buyer_address additionalProperties: false description: >- What the Etsy connection lets Alura do for this shop. required: - status - reconnect_url - capabilities additionalProperties: false description: The shop's Etsy connection. sync: type: object properties: status: anyOf: - type: string enum: - queued - running - succeeded - failed - skipped - unknown - type: 'null' description: >- The latest full sync's status: `queued`, `running`, `succeeded`, `failed` or `skipped`; `unknown` when the sync has a status Alura does not know yet; null when none is on record (the last 90 days). last_synced_at: anyOf: - type: string description: ISO 8601, UTC. - type: 'null' description: >- When the latest successful full sync finished; null when none is on record. next_allowed_at: anyOf: - type: string description: ISO 8601, UTC. - type: 'null' description: >- The earliest time the workspace's plan allows another sync of this shop (Free 24 h, Basic 6 h, Growth 1 h, Professional 15 min after the last completed sync); a past time means now; null when no completed sync is on record. latest_sync_id: description: >- The latest full sync, for GET /v1/workspace/syncs/{id}; null when none is on record. type: - string - 'null' required: - status - last_synced_at - next_allowed_at - latest_sync_id additionalProperties: false description: The shop's syncs with Etsy. as_of: anyOf: - type: string description: ISO 8601, UTC. - type: 'null' description: >- When Alura last stored the shop's profile from Etsy (its latest successful sync of the shop's details); null when never. required: - object - id - name - url - icon_url - currency - catalog - reviews - connection - sync - as_of additionalProperties: false has_more: type: boolean next_cursor: type: - string - 'null' total: type: object properties: value: type: integer relation: type: string enum: - eq - gte required: - value - relation additionalProperties: false summary: type: object properties: as_of: anyOf: - type: string format: date-time pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$ - type: 'null' description: >- The oldest included shop's data time; null when a shop's is unknown. freshness: type: array items: type: object properties: shop_id: type: string as_of: anyOf: - type: string format: date-time pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$ - type: 'null' required: - shop_id - as_of additionalProperties: false description: Each included shop's data time. notices: type: array items: type: object properties: code: type: string description: >- `stale_shops`, `sales_not_covered` or `partial_range`. New codes may be added. shop_ids: type: array items: type: string description: The shops the notice is about. detail: type: string required: - code - shop_ids - detail additionalProperties: false required: - as_of - freshness - notices additionalProperties: false required: - object - data - has_more - next_cursor - total - summary additionalProperties: false example: object: list data: - object: workspace.shop id: '22841907' name: GiftMugStudio url: https://www.etsy.com/shop/GiftMugStudio icon_url: null currency: USD catalog: active_listings: 134 digital_listings: 0 reviews: count: 3067 average: 4.92 connection: status: ok reconnect_url: null capabilities: delete_listings: available shipments: unknown buyer_address: unknown sync: status: succeeded last_synced_at: '2026-10-08T07:00:00.000Z' next_allowed_at: '2026-10-08T08:00:00.000Z' latest_sync_id: '40107' as_of: '2026-10-08T06:00:00.000Z' - object: workspace.shop id: '30577120' name: ClayAndName url: https://www.etsy.com/shop/ClayAndName icon_url: null currency: USD catalog: active_listings: 134 digital_listings: 0 reviews: count: 3067 average: 4.92 connection: status: ok reconnect_url: null capabilities: delete_listings: available shipments: unknown buyer_address: unknown sync: status: succeeded last_synced_at: '2026-10-17T07:00:00.000Z' next_allowed_at: '2026-10-17T08:00:00.000Z' latest_sync_id: '40120' as_of: '2026-10-17T06:00:00.000Z' - object: workspace.shop id: '48911633' name: MugCo url: https://www.etsy.com/shop/MugCo icon_url: null currency: USD catalog: active_listings: 134 digital_listings: 0 reviews: count: 3067 average: 4.92 connection: status: reconnect_required reconnect_url: https://platform.alura.io/settings/workspace/etsy-shops capabilities: delete_listings: restricted shipments: unknown buyer_address: unknown sync: status: failed last_synced_at: '2026-10-16T06:00:00.000Z' next_allowed_at: '2026-10-16T08:00:00.000Z' latest_sync_id: '40133' as_of: '2026-10-16T06:00:00.000Z' has_more: false next_cursor: null total: value: 3 relation: eq summary: as_of: '2026-10-08T06:00:00.000Z' freshness: - shop_id: '22841907' as_of: '2026-10-08T06:00:00.000Z' - shop_id: '30577120' as_of: '2026-10-17T06:00:00.000Z' - shop_id: '48911633' as_of: '2026-10-16T06:00:00.000Z' notices: - code: stale_shops shop_ids: - '22841907' detail: >- These shops have no data, or no data newer than 7 days, for this area. Start a sync to refresh them. - code: sales_not_covered shop_ids: - '30577120' detail: >- Alura's sales data does not cover these shops yet, so their sales coverage is null (never a made-up window). '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/shops" \ -H "Authorization: Bearer $ALURA_API_KEY" - lang: typescript label: TypeScript source: |- const res = await fetch('https://api.alura.io/v1/workspace/shops', { 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/shops", 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.