> ## 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 trending shops > Rising and new Etsy shops (other sellers). `type=rising` (default): ranked by `sales.est_trend_3m`, the change in estimated sales over the last 3 completed months against the 3 before; shops qualify with a trend for the last completed month and at least 30 estimated sales a month on average. `type=new`: shops opened in the last 90 days with at least 10 estimated sales a month, most estimated monthly sales first. Filter by main `category` (by name), Etsy's sales count and estimated monthly sales. Shop summaries, as search returns them, plus `sales.est_trend_3m` and `sales.est_last_month`; `summary.trend_window` names the six months compared. Only items Alura has refreshed recently can qualify, so coverage grows as Alura refreshes more of Etsy: an item missing from trending is not proof that it is not rising. Shops that opted out of Alura never appear. Nothing is fetched from Etsy. The totals stop counting at 10,000. Costs 10 API credits per page with results; an empty page is free. Cost: 10 API credits per page. ## OpenAPI ````yaml /openapi.json get /v1/research/shops/trending 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/research/shops/trending: get: summary: Get trending shops description: >- Rising and new Etsy shops (other sellers). `type=rising` (default): ranked by `sales.est_trend_3m`, the change in estimated sales over the last 3 completed months against the 3 before; shops qualify with a trend for the last completed month and at least 30 estimated sales a month on average. `type=new`: shops opened in the last 90 days with at least 10 estimated sales a month, most estimated monthly sales first. Filter by main `category` (by name), Etsy's sales count and estimated monthly sales. Shop summaries, as search returns them, plus `sales.est_trend_3m` and `sales.est_last_month`; `summary.trend_window` names the six months compared. Only items Alura has refreshed recently can qualify, so coverage grows as Alura refreshes more of Etsy: an item missing from trending is not proof that it is not rising. Shops that opted out of Alura never appear. Nothing is fetched from Etsy. The totals stop counting at 10,000. Costs 10 API credits per page with results; an empty page is free. Cost: 10 API credits per page. operationId: research.shops.trending parameters: - name: type in: query required: false description: >- `rising` (default): the shops whose estimated sales grew the most, last 3 completed months against the 3 before. `new`: shops opened in the last 90 days that already sell, most estimated monthly sales first. schema: default: rising description: >- `rising` (default): the shops whose estimated sales grew the most, last 3 completed months against the 3 before. `new`: shops opened in the last 90 days that already sell, most estimated monthly sales first. type: string enum: - rising - new example: rising - name: category in: query required: false description: >- The shop's main category by name, for example `Home & Living` (any letter case). schema: description: >- The shop's main category by name, for example `Home & Living` (any letter case). type: string example: Home & Living - name: sales_min in: query required: false description: Fewest sales (Etsy's count). schema: description: Fewest sales (Etsy's count). type: string pattern: ^\d{1,10}$ - name: sales_max in: query required: false description: Most sales (Etsy's count). schema: description: Most sales (Etsy's count). type: string pattern: ^\d{1,10}$ - name: est_monthly_sales_min in: query required: false description: >- Fewest estimated sales per month (average). Estimate: see the methodology (version 2026-10) at https://docs.alura.io/methodology/sales-estimates. schema: description: Fewest estimated sales per month (average). type: string pattern: ^\d{1,10}$ - name: est_monthly_sales_max in: query required: false description: >- Most estimated sales per month (average). Estimate: see the methodology (version 2026-10) at https://docs.alura.io/methodology/sales-estimates. schema: description: Most estimated sales per month (average). type: string pattern: ^\d{1,10}$ - 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: research.shop id: type: string description: Etsy ID, as a string. name: type: - string - 'null' url: description: The shop on Etsy; null when its name is unknown. type: - string - 'null' icon_url: type: - string - 'null' country: description: ISO 3166-1 alpha-2. type: - string - 'null' category: anyOf: - type: object properties: name: type: - string - 'null' sub_category: type: - string - 'null' required: - name - sub_category additionalProperties: false - type: 'null' description: >- The shop's main category and sub-category, by name (shops have no category IDs). sales: type: object properties: lifetime: anyOf: - type: integer - type: 'null' description: Etsy's own count of the shop's sales. est_monthly_avg: type: - number - 'null' description: >- Estimate: see the methodology (version 2026-10) at https://docs.alura.io/methodology/sales-estimates. est_lifetime_revenue_usd: type: - number - 'null' description: >- Estimate: see the methodology (version 2026-10) at https://docs.alura.io/methodology/sales-estimates. est_last_month: description: >- Estimated sales in the last completed UTC month. Estimate: see the methodology (version 2026-10) at https://docs.alura.io/methodology/sales-estimates. type: - number - 'null' est_trend_3m: description: >- The last 3 completed months against the 3 before (0.12 = +12%); null when the history does not cover them or the base is 0. Estimate: see the methodology (version 2026-10) at https://docs.alura.io/methodology/sales-trend. type: - number - 'null' required: - lifetime - est_monthly_avg - est_lifetime_revenue_usd - est_last_month - est_trend_3m additionalProperties: false description: >- `lifetime` is Etsy's count; the rest are estimates (methodology: https://docs.alura.io/methodology/sales-estimates). 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 catalog: type: object properties: active_listings: anyOf: - type: integer - type: 'null' required: - active_listings additionalProperties: false as_of: description: >- ISO 8601, UTC. When Alura's search copy of this shop was last synced (an approximation for older copies); null when unknown. It can differ from the shop detail's `as_of`. type: - string - 'null' required: - object - id - name - url - icon_url - country - category - sales - reviews - catalog - 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: trend_window: type: object properties: from: type: string description: A calendar month (UTC), YYYY-MM. to: type: string description: A calendar month (UTC), YYYY-MM. required: - from - to additionalProperties: false description: >- The six completed months the trend compares: `to` is the last completed UTC month, `from` five months before it. `est_trend_3m` is the last three against the first three. required: - trend_window additionalProperties: false description: The same on every page. required: - object - data - has_more - next_cursor - total - summary additionalProperties: false example: object: list data: - object: research.shop id: '48911633' name: MugCo url: https://www.etsy.com/shop/MugCo icon_url: >- https://i.etsystatic.com/iusa/0a1b2c/48911633/iusa_fullxfull.48911633_mugco.jpg country: US category: name: Home & Living sub_category: Kitchen & Dining sales: lifetime: 48210 est_monthly_avg: 1150 est_lifetime_revenue_usd: 1272700 est_last_month: 1240 est_trend_3m: 0.08 reviews: count: 9120 average: 4.9 catalog: active_listings: 1661 as_of: '2026-10-13T09:47:00.000Z' has_more: false next_cursor: null total: value: 1 relation: eq summary: trend_window: from: 2026-04 to: 2026-09 '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/research/shops/trending?type=rising&category=Home+%26+Living" \ -H "Authorization: Bearer $ALURA_API_KEY" - lang: typescript label: TypeScript source: >- const res = await fetch('https://api.alura.io/v1/research/shops/trending?type=rising&category=Home+%26+Living', { 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/research/shops/trending?type=rising&category=Home+%26+Living", 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 - id_type_mismatch - invalid_keyword - unauthorized - credits_exhausted - plan_required - insufficient_scope - workspace_required - workspace_locked - browser_refused - role_required - impersonation_refused - recent_sign_in_required - not_found - not_found_on_etsy - shop_opted_out - method_not_allowed - conflict - key_limit_reached - idempotency_processing - unprocessable - rate_limited - throttled - daily_credit_cap_exceeded - credits_reserved - fetch_limit_reached - internal_error - upstream_unavailable - credits_unavailable - service_unavailable - fetch_unavailable - 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.