List dataset items

get/v1/datasets/{datasetId}/items

Returns a page of the dataset's active processed items, newest first. Archived items are never included.

Each item is the full processed record — merchant product data, AI metadata and stored image keys. Embeddings are not returned. Image fields hold object keys, not URLs: build a URL with https://stylor.ai/api/v1/image/{key} and add transform segments as needed (see the image delivery endpoint).

Pagination is page-based. page and limit are validated, not clamped: a limit above 200 is rejected. Both are read with integer parsing, so a decimal is truncated (limit=20.9 is 20), trailing characters are ignored (page=2abc is 2), and a value with no leading digits is rejected. An empty value falls back to the default.

Private keyapi.v1.datasets.items.listNo demo

Path parameters

datasetIdstring (uuid)required

The dataset's id, as returned when it was created.

Query parameters

pageinteger

1-based page number. Non-numeric values are rejected.

default: 1min: 1

limitinteger

Items per page. Values above 200 are rejected with a 422 rather than clamped.

default: 10min: 1max: 200

Response

200A page of active items.

array<DatasetItem>required

Items on this page, newest first.

itemIdstring (uuid)required

Unique item id. It is the same id the queue entry was given at upload time.

e.g. "8b0a1b62-7c2a-4b7f-9e2c-0f3a9b1f0c11"

datasetIdstring (uuid)required

The dataset the item belongs to.

e.g. "c9b3c6c0-9b0f-4f42-bf3f-2b7a6b1b9d31"

organizationIdstring (uuid)required

The organization that owns the dataset.

e.g. "0a2c1f4e-5b6d-7e8f-9012-3456789abcde"

statusstringrequired

Only active items are listed and searchable.

One ofactivearchived

e.g. "active"

versionnumberrequired

Ingest pipeline version the item was processed with.

e.g. 1

DatasetItemMetadatarequired

What Stylor's product labeller read from the item's photos and listing when it was processed. Fields with an enum are closed lists; the taxonomy (slot, family, features) is shared by every catalogue. Items processed before a field existed may lack it.

DatasetItemProductrequired

Merchant-facing product data. Everything here comes from your upload or your dataset configuration, not from AI.

DatasetItemOriginrequired

Where the item came from. Copied from the dataset's store configuration at processing time.

createdAtstring (date-time)required

When the processed item was first written.

e.g. "2025-03-04T18:22:41.913Z"

updatedAtstring (date-time)required

When the item was last rewritten by a sync or reprocess.

e.g. "2025-03-04T18:22:41.913Z"

ItemPaginationrequired

Page metadata returned by the item and queue list endpoints. There is no page count; iterate while hasMore is true.

pageintegerrequired

The page that was returned (1-based).

e.g. 1

limitintegerrequired

The page size that was applied.

e.g. 10

totalintegerrequired

Total number of records matching the listing.

e.g. 1284

hasMorebooleanrequired

Whether page + 1 would return at least one record.

e.g. true

Errors

Every error is JSON with a single error string unless noted. Match on the status code; the message is for humans.

401

Organization not found. Please verify the organizationId.

The organization encoded in the API key no longer exists.

404

Dataset not found for this organization.

No dataset with this datasetId belongs to the key's organization.

422

Page must be an integer greater than or equal to 1.

page is 0, negative, or not a number (for example ?page=abc).

422

Limit must be an integer greater than or equal to 1.

limit is 0, negative, or not a number.

422

Limit cannot exceed 200 items per request.

limit is greater than 200.

curl -X GET "https://stylor.ai/api/v1/datasets/YOUR_DATASET_ID/items" \
  -H "Authorization: Bearer $STYLOR_API_KEY"

Response · 200

{
  "items": [
    {
      "itemId": "8b0a1b62-7c2a-4b7f-9e2c-0f3a9b1f0c11",
      "datasetId": "c9b3c6c0-9b0f-4f42-bf3f-2b7a6b1b9d31",
      "organizationId": "0a2c1f4e-5b6d-7e8f-9012-3456789abcde",
      "status": "active",
      "version": 1,
      "metadata": {
        "description": "classic crew tee mens black relaxed t shirt cotton crew neck short sleeve",
        "gender": "mens",
        "age_group": "adult",
        "color_rgb": [
          28,
          28,
          30
        ],
        "color_family": "black",
        "colors": [
          "black"
        ],
        "pattern": "solid",
        "material": [
          "cotton"
        ],
        "fit": "relaxed",
        "slot": "top",
        "family": "t shirt",
        "features": [
          {
            "axis": "neckline",
            "value": "crew",
            "confidence": 0.97
          },
          {
            "axis": "sleeve",
            "value": "short",
            "confidence": 0.99
          }
        ],
        "featureKeys": [
          "neckline:crew",
          "sleeve:short"
        ],
        "taxonomyVersion": 4,
        "searchTextVersion": 2
      },
      "product": {
        "sku": "A1A2P-BB2J",
        "url": "https://shop.example.com/products/classic-crew-tee",
        "name": "Classic Crew Tee",
        "description": "<p>A heavyweight organic cotton tee with a relaxed fit.</p>",
        "careInstructions": "",
        "price": 49,
        "currency": "USD",
        "model": {
          "height": "",
          "size": ""
        },
        "setItems": [],
        "recommendedItems": [],
        "assets": {
          "images": [
            {
              "originalImageUrl": "https://cdn.shopify.com/s/files/1/0001/products/tee-front.jpg",
              "type": "",
              "uploaded": {
                "id": "3f9c2a1e-8d4b-4c6f-9a2e-1b7d5e0c4f88",
                "key": "images/3f9c2a1e-8d4b-4c6f-9a2e-1b7d5e0c4f88.jpeg"
              }
            }
          ],
          "generated": {
            "thumbnail": {
              "url": null
            },
            "segmented": []
          }
        },
        "variants": [
          {
            "variantId": "gid://shopify/ProductVariant/41611609636909",
            "sku": "A1A2P-BB2J-M",
            "label": "M / Black",
            "options": [
              {
                "name": "Size",
                "value": "M"
              },
              {
                "name": "Color",
                "value": "Black"
              }
            ],
            "inStock": true,
            "quantity": 4,
            "price": 49,
            "compareAtPrice": null
          }
        ]
      },
      "origin": {
        "siteUrl": "https://shop.example.com",
        "brandId": "shop-example",
        "brand": "Example Apparel",
        "country": "CA"
      },
      "createdAt": "2025-03-04T18:22:41.913Z",
      "updatedAt": "2025-03-04T18:22:41.913Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 1284,
    "hasMore": true
  }
}