> ## 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 listing rules > Get Etsy's listing rules on any day, such as the longest title, the most tags and photos and the allowed file types, each with the Etsy page that states it. **Cost:** Free. ```bash curl -G "https://api.alura.io/v1/etsy/listing-rules" \ -H "Authorization: Bearer $ALURA_API_KEY" \ --data-urlencode "as_of=2026-10-22" ``` The rules cover title length, tags, photos, videos, variations, quantity, price, materials, custom options, digital files and more. Without `as_of`, you get today's rules (UTC). A past day gives the rules then. A future day also includes the changes Etsy has announced for it. ## Read a rule `rules` has one entry per `key`, in key order: the value in effect on `as_of`. A key that's missing wasn't in effect that day. | Field | Meaning | | - | - | | `key` | A stable ID: `[.]._`, such as `title.max_length` or `photos.max_count`. A yes or no ends in `_supported` or `_required`. A list is `allowed_file_types` or `allowed_characters`. | | `value` | A number in `unit`, a yes or no, or a list of allowed values. | | `unit` | `characters`, `count`, `bytes`, `seconds`, `days`, `weeks`, `months`, `years`, `pixels`, `percent` or `currency-amount` (in the listing currency). `null` for a yes or no or a list. | | `applies_to` | Which listings: `all`, `physical`, `digital`, `made_to_order`, `custom_order` or `vintage`. `shop` is a limit on the shop itself. | > [!NOTE] > > A limit Etsy doesn't state is `null` with a `value_unknown` notice on the rule, never `0`. For example, Etsy publishes no minimum price, so `price.min_value` is `null`. > [accordion] Dates and sources > > `valid_from` is the first day the value applies; `null` means it was in effect before the earliest Etsy source. `valid_to` is the first day it no longer applies; `null` while it still does. > > `sources` holds the most authoritative Etsy page for the value (Etsy's Open API documentation when it states it, otherwise the Help Center article that says it most directly), and a second page only for what the first doesn't say, such as the start date. > [accordion] Days before Alura's records > > `recorded_from` is the first day Alura's history of the rules covers. For an earlier `as_of`, a change Etsy made may be missing: you get the rules known to apply, not a record of that day, and `notices` has `before_recorded_history`. For the attributes a listing in one category can have, use [Get category properties](https://docs.alura.io/api-reference/etsy/categories/properties.md). To see when a rule changed, use [List updates](https://docs.alura.io/api-reference/etsy/updates/list.md) with `kind=listing_rules`. ## OpenAPI ````yaml /openapi.json get /v1/etsy/listing-rules 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/etsy/listing-rules: get: summary: Get listing rules description: >- Etsy's listing rules in effect on one day: title length, tags, photos, videos, variations, quantity, price, materials, custom options, digital files and more. Each rule has its value and unit, the listings it covers, the dates it applies, and the Etsy pages that state it. A limit Etsy doesn't state is null with a `value_unknown` notice, never 0. Without `as_of`, today's rules; with a past day, the rules then; with a future day, also the changes Etsy has announced for it. Cost: free. operationId: etsy.listingRules.get parameters: - name: as_of in: query required: false description: >- The day to answer for (YYYY-MM-DD, UTC). Default: today. A future day includes changes Etsy has announced for that day. schema: type: string format: date 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])))$ description: >- The day to answer for (YYYY-MM-DD, UTC). Default: today. A future day includes changes Etsy has announced for that day. example: '2026-10-22' - 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: listing_rules as_of: type: string description: The day the rules apply on (YYYY-MM-DD). recorded_from: type: string description: >- The first day Alura's recorded history of the rules covers (YYYY-MM-DD). Before it, a change Etsy made may be missing: the rules shown are the ones known to apply, not a record of that day. rules: type: array items: type: object properties: key: type: string description: >- Stable id of the rule: `[.]._` (for example `title.max_length`, `photos.max_count`), a yes/no ending in `_supported` or `_required`, or a list (`allowed_file_types`, `allowed_characters`). value: anyOf: - anyOf: - type: number - type: string - type: boolean - type: array items: type: string - type: 'null' description: >- The limit: a number in `unit`, a yes/no, or a list of allowed values. null when Etsy doesn't state it; a notice says so. Never 0 for unknown. unit: anyOf: - type: string enum: - characters - count - bytes - seconds - days - weeks - months - years - pixels - percent - currency-amount - type: 'null' description: >- What a number counts: `characters`, `count`, `bytes`, `seconds`, `days`, `weeks`, `months`, `years`, `pixels`, `percent` or `currency-amount` (in the listing currency). null for a yes/no or a list. applies_to: type: string enum: - all - physical - digital - made_to_order - custom_order - vintage - shop description: >- What the rule covers: `all` listings, `physical`, `digital`, `made_to_order`, `custom_order` (custom orders) or `vintage` listings, or `shop` for a limit on the shop itself. description: type: string description: What the rule limits, in one plain sentence. valid_from: description: >- The first day this value applies (YYYY-MM-DD); null: from the beginning (in effect before the earliest Etsy source). type: - string - 'null' valid_to: description: >- The first day this value no longer applies (YYYY-MM-DD); null while it still applies. type: - string - 'null' sources: type: array items: type: object properties: url: type: string description: >- The page that states the fact: Etsy's Help Center, Seller Handbook, Open API documentation, Etsy News or an Etsy staff post (or ISO 4217 for currency minor units). title: type: string description: The page's title. publisher: type: string enum: - Etsy - ISO 4217 description: >- `Etsy` for Etsy-owned pages; `ISO 4217` for currency minor units, the one source that is not Etsy. published_at: anyOf: - type: string format: date 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])))$ - type: 'null' description: >- When the page was published or last edited (YYYY-MM-DD); null when it does not say. read_at: anyOf: - type: string format: date 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])))$ - type: 'null' description: >- When Alura read the page (YYYY-MM-DD); null when not recorded. required: - url - title - publisher - published_at - read_at additionalProperties: false description: >- The one most authoritative Etsy page that states the value (Etsy's Open API documentation when it does, else the Help Center article that says it most directly), and a second only for what the first doesn't say, such as the start date. notices: type: array items: type: object properties: code: type: string enum: - value_unknown description: >- `value_unknown`: Etsy doesn't state this limit, so `value` is null. detail: type: string description: The notice in one plain sentence. required: - code - detail additionalProperties: false description: >- `value_unknown` when Etsy doesn't state the value; empty otherwise. required: - key - value - unit - applies_to - description - valid_from - valid_to - sources - notices additionalProperties: false description: >- One per key, in key order: the value in effect on `as_of`. A key missing on a day was not in effect that day. notices: type: array items: type: object properties: code: type: string description: >- `before_recorded_history`: `as_of` is before `recorded_from`. New codes may be added. detail: type: string description: The notice in one plain sentence. required: - code - detail additionalProperties: false description: >- `before_recorded_history` when `as_of` is before `recorded_from`: the answer is what Alura knows, which may not be what applied then. Empty otherwise. required: - object - as_of - recorded_from - rules - notices additionalProperties: false example: object: listing_rules as_of: '2026-10-22' recorded_from: '2025-10-22' rules: - key: photos.allowed_file_types value: - jpg - gif - png - svg - heic unit: null applies_to: all description: >- The image file types Etsy accepts; animated GIFs and transparent PNGs are not supported. valid_from: null valid_to: null sources: - url: https://help.etsy.com/hc/en-us/articles/115015663347 title: >- Requirements and Best Practices for Images in Your Etsy Shop publisher: Etsy published_at: '2026-05-04' read_at: '2026-10-22' notices: [] - key: photos.max_count value: 20 unit: count applies_to: all description: The most photos a listing can have. valid_from: '2025-10-09' valid_to: null sources: - url: https://www.etsy.com/openapi/generated/oas/3.0.0.json title: Etsy Open API v3 reference (OpenAPI document) publisher: Etsy published_at: null read_at: '2026-10-22' - url: >- https://community.etsy.com/forum/announcements-290/topic/community-newsletter-october-9-2025-22326/ title: 'Community Newsletter: October 9, 2025' publisher: Etsy published_at: '2025-10-09' read_at: '2026-10-22' notices: [] - key: price.min_value value: null unit: currency-amount applies_to: all description: The lowest price a listing can have, in its currency. valid_from: null valid_to: null sources: - url: https://www.etsy.com/openapi/generated/oas/3.0.0.json title: Etsy Open API v3 reference (OpenAPI document) publisher: Etsy published_at: null read_at: '2026-10-22' notices: - code: value_unknown detail: Etsy doesn't publish a minimum listing price. - key: tags.max_count value: 13 unit: count applies_to: all description: The most tags a listing can have. valid_from: null valid_to: null sources: - url: https://help.etsy.com/hc/en-us/articles/360000336307 title: How to Use Tags to Get Found in Search publisher: Etsy published_at: '2026-04-21' read_at: '2026-10-22' notices: [] - key: tags.max_length value: 20 unit: characters applies_to: all description: The most characters one tag can have. valid_from: null valid_to: null sources: - url: https://help.etsy.com/hc/en-us/articles/360000336307 title: How to Use Tags to Get Found in Search publisher: Etsy published_at: '2026-04-21' read_at: '2026-10-22' notices: [] - key: title.max_length value: 140 unit: characters applies_to: all description: The most characters a listing title can have. valid_from: null valid_to: null sources: - url: https://help.etsy.com/hc/en-us/articles/115015628707 title: How to Create a Listing publisher: Etsy published_at: '2026-06-29' read_at: '2026-10-22' notices: [] - key: variations.digital_supported value: false unit: null applies_to: digital description: Whether digital listings can have variations. valid_from: null valid_to: null sources: - url: https://help.etsy.com/hc/en-us/articles/115015664047 title: How to Add Variations to Your Listings publisher: Etsy published_at: '2026-08-28' read_at: '2026-10-22' notices: [] - key: videos.min_duration value: 5 unit: seconds applies_to: all description: The shortest a listing video can be. valid_from: null valid_to: '2026-10-23' sources: - url: https://help.etsy.com/hc/en-us/articles/115015628707 title: How to Create a Listing publisher: Etsy published_at: '2026-06-29' read_at: '2026-10-22' notices: [] 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/etsy/listing-rules?as_of=2026-10-22" \ -H "Authorization: Bearer $ALURA_API_KEY" - lang: typescript label: TypeScript source: >- const res = await fetch('https://api.alura.io/v1/etsy/listing-rules?as_of=2026-10-22', { 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/etsy/listing-rules?as_of=2026-10-22", 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 - listing_not_publishable - sales_window_not_covered - unauthorized - credits_exhausted - plan_required - insufficient_scope - workspace_required - workspace_locked - your_shop_unavailable - writes_suspended - browser_refused - role_required - impersonation_refused - recent_sign_in_required - etsy_scope_required - etsy_partner_required - not_found - not_collected - not_found_on_etsy - shop_opted_out - method_not_allowed - conflict - key_limit_reached - reconnect_required - settings_not_fetched - listing_busy - settings_busy - shop_create_busy - idempotency_partial_unverifiable - listing_has_variations - changed_since - change_not_revertable - listing_in_ab_test - activation_skipped - idempotency_processing - confirmation_required - test_shop_active_cap - write_outcome_unknown - unprocessable - listing_removed_on_etsy - endpoint_removed - rate_limited - throttled - daily_credit_cap_exceeded - credits_reserved - fetch_limit_reached - write_rate_limited - sync_cooldown - shop_write_budget_exhausted - internal_error - write_misconfigured - upstream_unavailable - credits_unavailable - service_unavailable - fetch_unavailable - create_lock_unavailable - writes_paused - 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.