> ## 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's stats > One listing's sales over a range of UTC days, from your shop's synced orders: `totals` (units, orders, revenue, refunds and reviews) and a `series` by `interval` (`day`, `week` from Monday, `month` by default, `quarter` or `year`; at most 366 points), plus Etsy's lifetime views and favorites, the listing's age, reviews per unit sold and its rating average and distribution. `from`/`to` default to the shop's whole sales coverage (`coverage`). Money values are plain numbers in the listing's own currency, or in `currency` converted at current exchange rates (`conversion`). Unknown is never 0: a point Alura's sales data does not wholly cover, or that holds a day Alura does not know yet, is null (`partial_range`), a range with no covered day is `sales_not_covered`, a covered point with no sales is a real 0, and refunds count only through `coverage.refunds_through` (`refunds_partial`). A shop with no sales coverage yet still gets its reviews, rating and lifetime counters. No profit, margin or trend scores: derive trends from `series`. A listing outside the workspace is 404. Needs the Listing analytics workspace permission. Costs 1 API credit per call. Cost: 1 API credit per call. ## OpenAPI ````yaml /openapi.json get /v1/workspace/listings/{id}/stats 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}/stats: get: summary: Get a listing's stats description: >- One listing's sales over a range of UTC days, from your shop's synced orders: `totals` (units, orders, revenue, refunds and reviews) and a `series` by `interval` (`day`, `week` from Monday, `month` by default, `quarter` or `year`; at most 366 points), plus Etsy's lifetime views and favorites, the listing's age, reviews per unit sold and its rating average and distribution. `from`/`to` default to the shop's whole sales coverage (`coverage`). Money values are plain numbers in the listing's own currency, or in `currency` converted at current exchange rates (`conversion`). Unknown is never 0: a point Alura's sales data does not wholly cover, or that holds a day Alura does not know yet, is null (`partial_range`), a range with no covered day is `sales_not_covered`, a covered point with no sales is a real 0, and refunds count only through `coverage.refunds_through` (`refunds_partial`). A shop with no sales coverage yet still gets its reviews, rating and lifetime counters. No profit, margin or trend scores: derive trends from `series`. A listing outside the workspace is 404. Needs the Listing analytics workspace permission. Costs 1 API credit per call. Cost: 1 API credit per call. operationId: workspace.listings.stats 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: from in: query required: false description: >- The first day (UTC, inclusive). Default: the first day of the shop's sales coverage (the listing's creation day for a shop with none), or `to` when that is earlier. schema: type: string pattern: ^\d{4}-\d{2}-\d{2}$ description: >- The first day (UTC, inclusive). Default: the first day of the shop's sales coverage (the listing's creation day for a shop with none), or `to` when that is earlier. - name: to in: query required: false description: >- The last day (UTC, inclusive). Default: the shop's last complete day (yesterday for a shop with no coverage), or `from` when that is later. schema: type: string pattern: ^\d{4}-\d{2}-\d{2}$ description: >- The last day (UTC, inclusive). Default: the shop's last complete day (yesterday for a shop with no coverage), or `from` when that is later. - name: interval in: query required: false description: >- The series interval: `day`, `week` (UTC weeks from Monday), `month` (default), `quarter` or `year`. At most 366 points. schema: description: >- The series interval: `day`, `week` (UTC weeks from Monday), `month` (default), `quarter` or `year`. At most 366 points. type: string enum: - day - week - month - quarter - year example: month - name: currency in: query required: false description: >- Convert every money value into this currency at current exchange rates (`conversion` says so). Default: the listing's own price currency. schema: description: >- Convert every money value into this currency at current exchange rates (`conversion` says so). Default: the listing's own price currency. type: string pattern: ^[A-Z]{3}$ - 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: workspace.listing_stats listing_id: type: string description: Etsy ID, as a string. from: type: string pattern: ^\d{4}-\d{2}-\d{2}$ description: The first day of the range (UTC, inclusive). to: type: string pattern: ^\d{4}-\d{2}-\d{2}$ description: The last day of the range (UTC, inclusive). interval: type: string enum: - day - week - month - quarter - year currency: type: string description: >- ISO 4217 code of every money value: the listing's own price currency unless `currency` was asked for. totals: type: object properties: units: anyOf: - type: integer - type: 'null' description: >- Units sold; null outside the sales coverage, on a day Alura does not know yet, or when an order line has no known quantity (never a partial sum). orders: anyOf: - type: integer - type: 'null' description: >- Orders containing the listing; null outside the sales coverage, on a day Alura does not know yet, or when the sum cannot be read (never 0 for unknown). revenue: description: >- Item revenue (quantity × price, minus item discounts) of non-canceled orders; null like `units`, or when a sale has no known price. A plain number in `currency`. type: - number - 'null' refunds: description: >- Refunded amount, on the refund's own date; null outside the refunds coverage (`coverage.refunds_through`) or when a refund's amount is unknown. A plain number in `currency`. type: - number - 'null' reviews: anyOf: - type: integer - type: 'null' description: >- Reviews created in the range (UTC days of the review); null while the shop's reviews were never synced (`reviews_not_synced`). required: - units - orders - revenue - refunds - reviews additionalProperties: false description: >- The range's totals over the days Alura's sales data covers (`coverage`); a known-gap day is left out and `partial_range` says so. Sales values are null when no day of the range is covered (`sales_not_covered`). series: anyOf: - type: array items: type: object properties: period: type: string description: >- `2026-09-14` (a day, or the week starting that Monday), `2026-09`, `2026-Q3` or `2026`. units: anyOf: - type: integer - type: 'null' description: >- Units sold; null outside the sales coverage, on a day Alura does not know yet, or when an order line has no known quantity (never a partial sum). orders: anyOf: - type: integer - type: 'null' description: >- Orders containing the listing; null outside the sales coverage, on a day Alura does not know yet, or when the sum cannot be read (never 0 for unknown). revenue: description: >- Item revenue (quantity × price, minus item discounts) of non-canceled orders; null like `units`, or when a sale has no known price. A plain number in `currency`. type: - number - 'null' refunds: description: >- Refunded amount, on the refund's own date; null outside the refunds coverage (`coverage.refunds_through`) or when a refund's amount is unknown. A plain number in `currency`. type: - number - 'null' reviews: anyOf: - type: integer - type: 'null' description: >- Reviews created in the range (UTC days of the review); null while the shop's reviews were never synced (`reviews_not_synced`). required: - period - units - orders - revenue - refunds - reviews additionalProperties: false description: >- One interval of the range, cut to the range's days. A point Alura's sales data does not wholly know has null sales values (`partial_range` or `sales_not_covered` say why); a covered point with no sales is a real 0. - type: 'null' description: >- One point per interval, oldest first; null when the shop has no sales coverage at all. lifetime: type: object properties: views: anyOf: - type: integer - type: 'null' description: Etsy's lifetime view count. favorites: anyOf: - type: integer - type: 'null' description: Etsy's lifetime favorites count. required: - views - favorites additionalProperties: false description: Etsy's lifetime counters (no history of them exists). metrics: type: object properties: age_days: anyOf: - type: integer - type: 'null' description: >- Whole UTC days since the listing was first created; null when unknown. review_rate: description: >- Reviews per unit sold over the covered days of the range, to 4 decimals; null with 0 or unknown units, with a known-gap day in the range, or with no coverage. type: - number - 'null' rating: anyOf: - type: object properties: average: description: >- The average rating, 1-5, to 2 decimals; null with no rated reviews. type: - number - 'null' distribution: anyOf: - type: object properties: '1': type: number '2': type: number '3': type: number '4': type: number '5': type: number required: - '1' - '2' - '3' - '4' - '5' additionalProperties: false - type: 'null' description: >- The share of rated reviews per star rating; the shares sum to 1. null with no rated reviews. required: - average - distribution additionalProperties: false - type: 'null' description: >- Over every stored review of the listing (not only the range's); null while the shop's reviews were never synced (`reviews_not_synced`) or when a count cannot be read. required: - age_days - review_rate - rating additionalProperties: false coverage: anyOf: - type: object properties: from: type: string pattern: ^\d{4}-\d{2}-\d{2}$ description: The first day every sale of the shop is counted. through: type: string pattern: ^\d{4}-\d{2}-\d{2}$ description: The last complete day. refunds_through: anyOf: - type: string pattern: ^\d{4}-\d{2}-\d{2}$ description: A UTC day, `YYYY-MM-DD`. - type: 'null' description: >- The last day refunds are counted; null when refunds are not known yet. required: - from - through - refunds_through additionalProperties: false - type: 'null' description: >- The shop's sales coverage; null when Alura has none for the shop yet (`sales_not_covered`). conversion: anyOf: - type: object properties: from: type: array items: type: string description: The currencies converted. to: type: string rate_date: type: string pattern: ^\d{4}-\d{2}-\d{2}$ description: The day of the exchange rates used. method: type: string const: current_rate required: - from - to - rate_date - method additionalProperties: false - type: 'null' description: >- What was converted into `currency`: all history at the exchange rates of `rate_date` (current rates, not each day's). null when nothing was converted. notices: type: array items: type: object properties: code: type: string description: >- `stale_shops`, `sales_not_covered`, `partial_range`, `settings_not_fetched`, `settings_sections_only`, `listings_count_unavailable`, `listings_not_synced`, `shipping_cost_inexact`, `sales_through`, `refunds_partial`, `unknown_sales_inputs`, `sync_daily_cap_reached`, `currency_converted_at_current_rate`, `reviews_not_synced`, `customers_not_computed`, `lifetime_value_ranked_by_stored_total`, `refunds_unknown` or `search_incomplete`. 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 description: >- Why a value is null or partial (`sales_not_covered`, `partial_range`, `refunds_partial`, `reviews_not_synced`), and `currency_converted_at_current_rate`; empty when nothing is. as_of: description: >- When the shop's orders, which the sales come from, were last synced (ISO 8601, UTC); null when never. type: - string - 'null' required: - object - listing_id - from - to - interval - currency - totals - series - lifetime - metrics - coverage - conversion - notices - as_of additionalProperties: false example: object: workspace.listing_stats listing_id: '1834720561' from: '2021-10-01' to: '2026-10-16' interval: month currency: USD totals: units: 11 orders: 10 revenue: 219.89 refunds: 19.99 reviews: 3 series: - period: 2021-10 units: 0 orders: 0 revenue: 0 refunds: 0 reviews: 0 - period: 2021-11 units: 0 orders: 0 revenue: 0 refunds: 0 reviews: 0 - period: 2021-12 units: 0 orders: 0 revenue: 0 refunds: 0 reviews: 0 - period: 2022-01 units: 0 orders: 0 revenue: 0 refunds: 0 reviews: 0 - period: 2022-02 units: 0 orders: 0 revenue: 0 refunds: 0 reviews: 0 - period: 2022-03 units: 0 orders: 0 revenue: 0 refunds: 0 reviews: 0 - period: 2022-04 units: 0 orders: 0 revenue: 0 refunds: 0 reviews: 0 - period: 2022-05 units: 0 orders: 0 revenue: 0 refunds: 0 reviews: 0 - period: 2022-06 units: 0 orders: 0 revenue: 0 refunds: 0 reviews: 0 - period: 2022-07 units: 0 orders: 0 revenue: 0 refunds: 0 reviews: 0 - period: 2022-08 units: 0 orders: 0 revenue: 0 refunds: 0 reviews: 0 - period: 2022-09 units: 0 orders: 0 revenue: 0 refunds: 0 reviews: 0 - period: 2022-10 units: 0 orders: 0 revenue: 0 refunds: 0 reviews: 0 - period: 2022-11 units: 0 orders: 0 revenue: 0 refunds: 0 reviews: 0 - period: 2022-12 units: 0 orders: 0 revenue: 0 refunds: 0 reviews: 0 - period: 2023-01 units: 0 orders: 0 revenue: 0 refunds: 0 reviews: 0 - period: 2023-02 units: 0 orders: 0 revenue: 0 refunds: 0 reviews: 0 - period: 2023-03 units: 0 orders: 0 revenue: 0 refunds: 0 reviews: 0 - period: 2023-04 units: 0 orders: 0 revenue: 0 refunds: 0 reviews: 0 - period: 2023-05 units: 0 orders: 0 revenue: 0 refunds: 0 reviews: 0 - period: 2023-06 units: 0 orders: 0 revenue: 0 refunds: 0 reviews: 0 - period: 2023-07 units: 0 orders: 0 revenue: 0 refunds: 0 reviews: 0 - period: 2023-08 units: 0 orders: 0 revenue: 0 refunds: 0 reviews: 0 - period: 2023-09 units: 0 orders: 0 revenue: 0 refunds: 0 reviews: 0 - period: 2023-10 units: 0 orders: 0 revenue: 0 refunds: 0 reviews: 0 - period: 2023-11 units: 0 orders: 0 revenue: 0 refunds: 0 reviews: 0 - period: 2023-12 units: 0 orders: 0 revenue: 0 refunds: 0 reviews: 0 - period: 2024-01 units: 0 orders: 0 revenue: 0 refunds: 0 reviews: 0 - period: 2024-02 units: 0 orders: 0 revenue: 0 refunds: 0 reviews: 0 - period: 2024-03 units: 0 orders: 0 revenue: 0 refunds: 0 reviews: 0 - period: 2024-04 units: 0 orders: 0 revenue: 0 refunds: 0 reviews: 0 - period: 2024-05 units: 0 orders: 0 revenue: 0 refunds: 0 reviews: 0 - period: 2024-06 units: 0 orders: 0 revenue: 0 refunds: 0 reviews: 0 - period: 2024-07 units: 0 orders: 0 revenue: 0 refunds: 0 reviews: 0 - period: 2024-08 units: 0 orders: 0 revenue: 0 refunds: 0 reviews: 0 - period: 2024-09 units: 0 orders: 0 revenue: 0 refunds: 0 reviews: 0 - period: 2024-10 units: 0 orders: 0 revenue: 0 refunds: 0 reviews: 0 - period: 2024-11 units: 0 orders: 0 revenue: 0 refunds: 0 reviews: 0 - period: 2024-12 units: 0 orders: 0 revenue: 0 refunds: 0 reviews: 0 - period: 2025-01 units: 0 orders: 0 revenue: 0 refunds: 0 reviews: 0 - period: 2025-02 units: 0 orders: 0 revenue: 0 refunds: 0 reviews: 0 - period: 2025-03 units: 0 orders: 0 revenue: 0 refunds: 0 reviews: 0 - period: 2025-04 units: 0 orders: 0 revenue: 0 refunds: 0 reviews: 0 - period: 2025-05 units: 0 orders: 0 revenue: 0 refunds: 0 reviews: 0 - period: 2025-06 units: 0 orders: 0 revenue: 0 refunds: 0 reviews: 0 - period: 2025-07 units: 0 orders: 0 revenue: 0 refunds: 0 reviews: 0 - period: 2025-08 units: 0 orders: 0 revenue: 0 refunds: 0 reviews: 0 - period: 2025-09 units: 0 orders: 0 revenue: 0 refunds: 0 reviews: 0 - period: 2025-10 units: 0 orders: 0 revenue: 0 refunds: 0 reviews: 0 - period: 2025-11 units: 0 orders: 0 revenue: 0 refunds: 0 reviews: 0 - period: 2025-12 units: 0 orders: 0 revenue: 0 refunds: 0 reviews: 0 - period: 2026-01 units: 0 orders: 0 revenue: 0 refunds: 0 reviews: 0 - period: 2026-02 units: 0 orders: 0 revenue: 0 refunds: 0 reviews: 0 - period: 2026-03 units: 0 orders: 0 revenue: 0 refunds: 0 reviews: 0 - period: 2026-04 units: 0 orders: 0 revenue: 0 refunds: 0 reviews: 0 - period: 2026-05 units: 0 orders: 0 revenue: 0 refunds: 0 reviews: 0 - period: 2026-06 units: 0 orders: 0 revenue: 0 refunds: 0 reviews: 0 - period: 2026-07 units: 3 orders: 3 revenue: 59.97 refunds: 0 reviews: 1 - period: 2026-08 units: 2 orders: 1 revenue: 39.98 refunds: 0 reviews: 0 - period: 2026-09 units: 4 orders: 4 revenue: 79.96 refunds: 19.99 reviews: 2 - period: 2026-10 units: 2 orders: 2 revenue: 39.98 refunds: null reviews: 0 lifetime: views: 10600 favorites: 2200 metrics: age_days: 959 review_rate: 0.2727 rating: average: 4.67 distribution: '1': 0 '2': 0 '3': 0 '4': 0.3333333333333333 '5': 0.6666666666666666 coverage: from: '2021-10-01' through: '2026-10-16' refunds_through: '2026-10-12' conversion: null notices: - code: refunds_partial shop_ids: - '22841907' detail: >- Refunds are counted from 2021-10-01 through 2026-10-12; later refunds are not known yet, so a point with a day after 2026-10-12 has null refunds. 2026-10 runs past that day, so its refunds are null. as_of: '2026-10-08T06: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/1834720561/stats?interval=month" \ -H "Authorization: Bearer $ALURA_API_KEY" - lang: typescript label: TypeScript source: >- const res = await fetch('https://api.alura.io/v1/workspace/listings/1834720561/stats?interval=month', { 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/stats?interval=month", 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 - sync_cooldown - 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.