cURL

curl "https://api.alura.io/v1/workspace/listings?q=mug&state=active&sort=-views" \
  -H "Authorization: Bearer $ALURA_API_KEY"

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());

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))

{
  "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"
  }
}

{
  "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"
}

{
  "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"
}

{
  "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"
}

{
  "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"
}

{
  "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"
}

{
  "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"
}

{
  "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"
}

{
  "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"
}

{
  "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"
}

Listings

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.

cURL

curl "https://api.alura.io/v1/workspace/listings?q=mug&state=active&sort=-views" \
  -H "Authorization: Bearer $ALURA_API_KEY"

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());

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))

{
  "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"
  }
}

{
  "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"
}

{
  "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"
}

{
  "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"
}

{
  "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"
}

{
  "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"
}

{
  "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"
}

{
  "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"
}

{
  "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"
}

{
  "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"
}

Authorizations

Authorization

string

header

required

An API key: Authorization: Bearer alura_sk_....

Query Parameters

string

Text found anywhere in the title or in any one tag, as one phrase (case-insensitive substring; the description is not searched).

Example:

"mug"

shop_id

string[]

Only these connected shops, comma-separated; default every connected shop of the workspace. A shop outside the workspace is 404.

state

string[]

Only listings in these states, comma-separated: active, inactive, sold_out, draft, expired, edit, deleted. Default: every state but deleted.

Example:

["active"]

section_id

string

Only listings in this shop section. A section outside the workspace is 404.

Pattern: ^[0-9]{1,20}$

tag

string

Only listings with this tag (case-insensitive, the whole tag).

category_id

string

Only listings in this Etsy category or a category under it (browse_categories).

Pattern: ^[1-9][0-9]{0,9}$

price_min

string

Lowest price in USD.

Pattern: ^\d{1,9}(\.\d{1,2})?$

price_max

string

Highest price in USD.

Pattern: ^\d{1,9}(\.\d{1,2})?$

quantity_max

string

At most this quantity in stock.

Pattern: ^\d{1,10}$

created_from

string

Created at or after this time (a date is midnight UTC).

Pattern: ^\d{4}-\d{2}-\d{2}(T\d{2}:\d{2}(:\d{2}(\.\d{1,3})?)?(Z|[+-]\d{2}:\d{2}))?$

created_to

string

Created before this time.

Pattern: ^\d{4}-\d{2}-\d{2}(T\d{2}:\d{2}(:\d{2}(\.\d{1,3})?)?(Z|[+-]\d{2}:\d{2}))?$

updated_from

string

Last updated at or after this time.

Pattern: ^\d{4}-\d{2}-\d{2}(T\d{2}:\d{2}(:\d{2}(\.\d{1,3})?)?(Z|[+-]\d{2}:\d{2}))?$

updated_to

string

Last updated before this time.

Pattern: ^\d{4}-\d{2}-\d{2}(T\d{2}:\d{2}(:\d{2}(\.\d{1,3})?)?(Z|[+-]\d{2}:\d{2}))?$

listing_score_min

string

Lowest listing score, 1-100. Listings never scored (score null) match no score filter.

Pattern: ^\d{1,10}$

listing_score_max

string

Highest listing score, 1-100. Listings never scored (score null) match no score filter.

Pattern: ^\d{1,10}$

featured

enum<string>

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.

Available options:

true,

false

sort

enum<string>

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.

Available options:

views,

favorites,

price,

created,

updated,

listing_score,

quantity,

-views,

-favorites,

-price,

-created,

-updated,

-listing_score,

-quantity

Example:

"-views"

limit

integer

Page size: default 25, at most 100.

Required range: 1 <= x <= 100

cursor

string

The next_cursor of the previous page. Bound to the query, the workspace and the key.

fields

string

Comma-separated dotted paths to return; id, object and as_of always come back.

Response

object

string

required

Allowed value: "list"

data

object[]

required

Show child attributes

has_more

boolean

required

next_cursor

string | null

required

total

object

required

Show child attributes

summary

object

required

Show child attributes

Overview

Research

Your shop

Reference data

Account

Search listings

Authorizations

Query Parameters

Response