> ## 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. # Search listings > Searches the listings of your connected Etsy shops, which Etsy's API cannot do: filter by words in the title or tags, state, section, tag, category, USD price, quantity, created and updated dates, listing score and featured, and sort by views, favorites, price, created, updated, listing score or quantity (`-` for descending; default `-created`). Covers every connected shop unless `shop_id` narrows it; a shop, section or category outside the workspace is 404. Every listing carries its `shop_id`; `summary` gives each shop's data time and a `stale_shops` notice for shops not synced for 7 days. Paging stops after 10,000 results. A listing deleted while a page is read may be left out of that page though still counted in its total. A search with `q` or `tag` reads every listing of the shops it covers and can take up to 10 seconds on a shop with tens of thousands of listings; if it cannot finish, it answers 503 and can be retried (narrow it with `shop_id` or `state`). Needs the Listing analytics workspace permission. Costs 1 API credit per page with results; an empty page is free. Cost: 1 API credit per page. ## OpenAPI ````yaml /openapi.json get /v1/workspace/listings 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: get: summary: Search listings description: >- Searches the listings of your connected Etsy shops, which Etsy's API cannot do: filter by words in the title or tags, state, section, tag, category, USD price, quantity, created and updated dates, listing score and featured, and sort by views, favorites, price, created, updated, listing score or quantity (`-` for descending; default `-created`). Covers every connected shop unless `shop_id` narrows it; a shop, section or category outside the workspace is 404. Every listing carries its `shop_id`; `summary` gives each shop's data time and a `stale_shops` notice for shops not synced for 7 days. Paging stops after 10,000 results. A listing deleted while a page is read may be left out of that page though still counted in its total. A search with `q` or `tag` reads every listing of the shops it covers and can take up to 10 seconds on a shop with tens of thousands of listings; if it cannot finish, it answers 503 and can be retried (narrow it with `shop_id` or `state`). Needs the Listing analytics workspace permission. Costs 1 API credit per page with results; an empty page is free. Cost: 1 API credit per page. operationId: workspace.listings.search parameters: - name: q in: query required: false description: >- Text found anywhere in the title or in any one tag, as one phrase (case-insensitive substring; the description is not searched). schema: description: >- Text found anywhere in the title or in any one tag, as one phrase (case-insensitive substring; the description is not searched). type: string example: mug - 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: state in: query required: false description: >- Only listings in these states, comma-separated: `active`, `inactive`, `sold_out`, `draft`, `expired`, `edit`, `deleted`. Default: every state but `deleted`. schema: description: >- Only listings in these states, comma-separated: `active`, `inactive`, `sold_out`, `draft`, `expired`, `edit`, `deleted`. Default: every state but `deleted`. type: array items: type: string example: - active style: form explode: true - name: section_id in: query required: false description: >- Only listings in this shop section. A section outside the workspace is 404. schema: description: >- Only listings in this shop section. A section outside the workspace is 404. type: string pattern: ^[0-9]{1,20}$ - name: tag in: query required: false description: Only listings with this tag (case-insensitive, the whole tag). schema: description: Only listings with this tag (case-insensitive, the whole tag). type: string - name: category_id in: query required: false description: >- Only listings in this Etsy category or a category under it (browse_categories). schema: type: string pattern: ^[1-9][0-9]{0,9}$ description: >- Only listings in this Etsy category or a category under it (browse_categories). - name: price_min in: query required: false description: Lowest price in USD. schema: description: Lowest price in USD. type: string pattern: ^\d{1,9}(\.\d{1,2})?$ - name: price_max in: query required: false description: Highest price in USD. schema: description: Highest price in USD. type: string pattern: ^\d{1,9}(\.\d{1,2})?$ - name: quantity_max in: query required: false description: At most this quantity in stock. schema: description: At most this quantity in stock. type: string pattern: ^\d{1,10}$ - name: created_from in: query required: false description: Created at or after this time (a date is midnight UTC). schema: description: Created at or after this time (a date is midnight UTC). type: string pattern: >- ^\d{4}-\d{2}-\d{2}(T\d{2}:\d{2}(:\d{2}(\.\d{1,3})?)?(Z|[+-]\d{2}:\d{2}))?$ - name: created_to in: query required: false description: Created before this time. schema: description: Created before this time. type: string pattern: >- ^\d{4}-\d{2}-\d{2}(T\d{2}:\d{2}(:\d{2}(\.\d{1,3})?)?(Z|[+-]\d{2}:\d{2}))?$ - name: updated_from in: query required: false description: Last updated at or after this time. schema: description: Last updated at or after this time. type: string pattern: >- ^\d{4}-\d{2}-\d{2}(T\d{2}:\d{2}(:\d{2}(\.\d{1,3})?)?(Z|[+-]\d{2}:\d{2}))?$ - name: updated_to in: query required: false description: Last updated before this time. schema: description: Last updated before this time. type: string pattern: >- ^\d{4}-\d{2}-\d{2}(T\d{2}:\d{2}(:\d{2}(\.\d{1,3})?)?(Z|[+-]\d{2}:\d{2}))?$ - name: listing_score_min in: query required: false description: >- Lowest listing score, 1-100. Listings never scored (score null) match no score filter. schema: description: >- Lowest listing score, 1-100. Listings never scored (score null) match no score filter. type: string pattern: ^\d{1,10}$ - name: listing_score_max in: query required: false description: >- Highest listing score, 1-100. Listings never scored (score null) match no score filter. schema: description: >- Highest listing score, 1-100. Listings never scored (score null) match no score filter. type: string pattern: ^\d{1,10}$ - name: featured in: query required: false description: >- true: only listings with a featured rank (Etsy keeps ranks on inactive listings); false: only listings without one. Listings whose rank is unknown match neither. schema: description: >- true: only listings with a featured rank (Etsy keeps ranks on inactive listings); false: only listings without one. Listings whose rank is unknown match neither. type: string enum: - 'true' - 'false' - name: sort in: query required: false description: >- `views`, `favorites`, `price`, `created`, `updated`, `listing_score`, `quantity`; prefix `-` for descending. Default `-created`. `price` sorts by the USD value. Listings whose value is unknown come last; ties go by listing ID. schema: description: >- `views`, `favorites`, `price`, `created`, `updated`, `listing_score`, `quantity`; prefix `-` for descending. Default `-created`. `price` sorts by the USD value. Listings whose value is unknown come last; ties go by listing ID. type: string enum: - views - favorites - price - created - updated - listing_score - quantity - '-views' - '-favorites' - '-price' - '-created' - '-updated' - '-listing_score' - '-quantity' example: '-views' - 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.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. required: - object - id - shop_id - title - url - state - price - quantity - image_url - section - views - favorites - listing_score - created_at - updated_at - 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 fx_as_of: anyOf: - type: string description: ISO 8601, UTC. - type: 'null' description: >- When the exchange rates that value `price.usd` were last updated; null when none are stored. required: - as_of - freshness - notices - fx_as_of additionalProperties: false required: - object - data - has_more - next_cursor - total - summary additionalProperties: false example: object: list data: - 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' has_more: false next_cursor: null total: value: 1 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. fx_as_of: '2026-10-16T22:00:00.000Z' '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?q=mug&state=active&sort=-views" \ -H "Authorization: Bearer $ALURA_API_KEY" - lang: typescript label: TypeScript source: >- const res = await fetch('https://api.alura.io/v1/workspace/listings?q=mug&state=active&sort=-views', { 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?q=mug&state=active&sort=-views", 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.