# List dataset items `GET https://stylor.ai/api/v1/datasets/{datasetId}/items` - Authentication: private API key, sent as `Authorization: Bearer sgpt-sk-…::…` - Rate-limit resource: `api.v1.datasets.items.list` - Demo key: not accepted - Web page: https://stylor.ai/guides/rest/v1/list-dataset-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. ## Example request ```bash curl -X GET "https://stylor.ai/api/v1/datasets/YOUR_DATASET_ID/items" \ -H "Authorization: Bearer $STYLOR_API_KEY" ``` ## Path parameters - `datasetId` (string (uuid), required): The dataset's id, as returned when it was created. ## Query parameters - `page` (integer): 1-based page number. Non-numeric values are rejected. [default `1`; minimum 1] - `limit` (integer): Items per page. Values above 200 are rejected with a 422 rather than clamped. [default `10`; minimum 1; maximum 200] ## Responses ### 200 A page of active items. Content type `application/json`: - `items` (array, required): Items on this page, newest first. - `itemId` (string (uuid), required): Unique item id. It is the same id the queue entry was given at upload time. [example `"8b0a1b62-7c2a-4b7f-9e2c-0f3a9b1f0c11"`] - `datasetId` (string (uuid), required): The dataset the item belongs to. [example `"c9b3c6c0-9b0f-4f42-bf3f-2b7a6b1b9d31"`] - `organizationId` (string (uuid), required): The organization that owns the dataset. [example `"0a2c1f4e-5b6d-7e8f-9012-3456789abcde"`] - `status` (string, required): Only `active` items are listed and searchable. [one of `"active"`, `"archived"`; example `"active"`] - `version` (number, required): Ingest pipeline version the item was processed with. [example `1`] - `metadata` (DatasetItemMetadata, required): 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. - `description` (string): The text the item is embedded as for search: its product name and product type, then its labelled attributes, most distinguishing first, with nothing said twice. Not prose. `searchTextVersion` says which recipe built it; items processed before September 2026 hold a one-sentence summary instead. [default `""`; max length 400; example `"lucile mini dress dresses womens black slim satin mini length cowl neck sleeveless zip closure"`] - `gender` (string, required): Target gender. If the dataset is configured with a target gender (`mens` or `womens`), every item takes that value. [one of `"mens"`, `"womens"`, `"unisex"`; example `"womens"`] - `age_group` (string, nullable): Who the item is sized for, separate from gender (a girls' dress is `womens` and `kids`). `null` on items processed before September 2026. [one of `"adult"`, `"kids"`, `"baby"`, `null`; example `"adult"`] - `color_rgb` (array, required): The item's own colour as `[r, g, b]`, each 0–255, measured from its photos with the background removed. [min items 3; max items 3] - `color_family` (string, required): Colour bucket of the colourway this listing sells. [one of `"black"`, `"charcoal"`, `"grey"`, `"silver"`, `"white"`, `"ivory"`, `"cream"`, `"beige"`, `"tan"`, `"camel"`, `"brown"`, `"chocolate"`, `"khaki"`, `"olive"`, `"green"`, `"mint"`, `"teal"`, `"turquoise"`, `"blue"`, `"navy"`, `"purple"`, `"lavender"`, `"pink"`, `"rose"`, `"coral"`, `"peach"`, `"red"`, `"burgundy"`, `"rust"`, `"orange"`, `"mustard"`, `"yellow"`, `"gold"`, `"multicolour"`, `"other"`; example `"black"`] - `colors` (array): Every colour the item is sold in, read from its colour options (lower-case, as the store names them); `[color_family]` when it has none. - `pattern` (string, required): Pattern printed or woven into the fabric. [one of `"solid"`, `"striped"`, `"checked"`, `"plaid"`, `"gingham"`, `"floral"`, `"ditsy floral"`, `"animal print"`, `"geometric"`, `"abstract"`, `"polka dot"`, `"paisley"`, `"camouflage"`, `"chevron"`, `"herringbone"`, `"tie dye"`, `"colour block"`, `"graphic"`, `"other"`; example `"solid"`] - `material` (array): Fibres the listing states, main fabric first. Empty when the listing does not say. [one of `"cotton"`, `"linen"`, `"hemp"`, `"wool"`, `"cashmere"`, `"alpaca"`, `"mohair"`, `"silk"`, `"down"`, `"leather"`, `"suede"`, `"faux leather"`, `"shearling"`, `"polyester"`, `"nylon"`, `"elastane"`, `"acrylic"`, `"viscose"`, `"modal"`, `"lyocell"`, `"acetate"`, `"metal"`, `"wood"`, `"glass"`, `"ceramic"`, `"rubber"`, `"straw"`, `"paper"`, `"other"`] - `fit` (string, nullable): How a garment is cut relative to the body. `null` for anything without a fit (footwear, bags, jewellery). [one of `"skinny"`, `"slim"`, `"regular"`, `"relaxed"`, `"oversized"`, `"other"`, `null`; example `"slim"`] - `slot` (string, required): Where the item is worn, or what kind of thing it is. The primary search filter. [one of `"accessory"`, `"bag"`, `"jewellery"`, `"headwear"`, `"eyewear"`, `"hosiery"`, `"bottom"`, `"footwear"`, `"outerwear"`, `"full body"`, `"sleepwear"`, `"swimwear"`, `"non fashion"`, `"top"`, `"underwear"`; example `"full body"`] - `family` (string): What kind of thing it is within its slot, for example `dress`, `boot`, `t shirt`; `other` when the taxonomy has no name for it. [example `"dress"`] - `features` (array): How the item varies, one answer per attribute that applies to its family (a dress has a neckline and a length; a scarf has neither). - `axis` (string) [example `"neckline"`] - `value` (string) [example `"cowl"`] - `confidence` (number, nullable): The labeller's probability for this answer, 0–1. [example `0.86`] - `featureKeys` (array): `features` flattened to sorted `axis:value` strings, for filtering. - `taxonomyVersion` (integer, nullable): The taxonomy version the item was labelled under. [example `4`] - `searchTextVersion` (integer, nullable): Which recipe built `description`. `2` leads with the product name and type (since September 2026); `null` on items embedded before versions were recorded. An item is re-embedded under the current recipe when it is next reprocessed. [example `2`] - `product` (DatasetItemProduct, required): Merchant-facing product data. Everything here comes from your upload or your dataset configuration, not from AI. - `sku` (string, required): The product-level SKU you supplied. Unique within a dataset. [example `"A1A2P-BB2J"`] - `url` (string (uri), required): Product page URL, built as `/products/`. [example `"https://shop.example.com/products/classic-crew-tee"`] - `name` (string, required): Product title. [example `"Classic Crew Tee"`] - `description` (string): Product description as supplied; may contain HTML. [default `""`; example `"

A heavyweight organic cotton tee with a relaxed fit.

"`] - `careInstructions` (string): Care instructions. Not populated by the ingest queue. [default `""`; example `""`] - `price` (number, required): Product price, in the market named by `market`: as stored, the store's default market; on a search result, the shopper's (see `referencePrice`). `0` when the upload had no price. [example `49`] - `currency` (string, required): ISO 4217 code of `price`. As stored, the currency the source reports (a Shopify Storefront API source reports its own), falling back to the dataset's configured currency, then `CAD`. On a search result, the shopper's market's currency. [example `"USD"`] - `market` (string, nullable): Handle of the store price list the prices, sale prices and stock are in, such as `us`, `ca` or `international-xof` (a Shopify market, split by currency when one market charges several). Stored on every item: the store's default market, or `null` for sources with no markets (uploads, a store's public product feed). On a search result, the market the product was priced for. [example `"us"`] - `marketExact` (boolean): Response only, on search results. `true` when the prices are the shopper's own market's. `false` when the store's default market's prices are standing in, with the reason in `marketFallback`. [example `true`] - `marketFallback` (string): Response only, present when `marketExact` is `false`. Why the shopper's own market could not be answered. `no-country`: the request sent no `country`. `not-served`: the store does not sell into that country. `unread`: the shopper's market could not be read. `no-row`: the product has no prices stored for that market yet (synced before the market existed). `no-markets`: the source has no markets. `stale`: the stored market prices were built against a different default market than the product is in. [one of `"no-country"`, `"not-served"`, `"unread"`, `"no-row"`, `"no-markets"`, `"stale"`; example `"no-country"`] - `available` (boolean): Response only, on search results. `true` when the shopper can buy it: sold in their market, with at least one variant in stock there. The Stylor agent never recommends a product for which this is `false`. [example `true`] - `onSale` (boolean): Response only, on search results. `true` when a variant the shopper can buy (in stock) has a `compareAtPrice` above its `price` in the shopper's market. A reduced price on a sold-out variant does not count. [example `true`] - `discount` (integer): Response only, on search results. The largest percent off among in-stock variants, rounded; `0` when `onSale` is `false`. [example `20`] - `referencePrice` (number): Response only, on search results. The stored price in the store's default market, before re-pricing for the shopper. [example `49`] - `referenceCurrency` (string): Response only, on search results. The currency of `referencePrice`. [example `"USD"`] - `model` (DatasetItemModelInfo): Details of the model shown in the product photography, when known. Empty strings when not provided. - `height` (string): Model height, free text. [default `""`; example `""`] - `size` (string): Size worn by the model. [default `""`; example `""`] - `setItems` (array): SKUs of products sold together with this one. Not populated by the ingest queue. - `recommendedItems` (array): SKUs of merchant-recommended companions. Not populated by the ingest queue. - `assets` (DatasetItemAssets): Images attached to the item. - `images` (array): Stored product images, in the order they were supplied. At most 10 images are kept per item; any beyond the tenth are dropped at ingest. [max items 10] - `originalImageUrl` (string (uri), required): The `src` you supplied at upload time. [example `"https://cdn.shopify.com/s/files/1/0001/products/tee-front.jpg"`] - `type` (string): What the photo shows: one of `flat front`, `flat back`, `mannequin`, `underside`, `detail`, `model full body`, `model cropped`, `hand`, `group`, `scene`, `not product`. Items processed before September 2026 carry an older vocabulary (`packshot`, `model_front`, `lifestyle`, …). [default `""`; example `"model full body"`] - `uploaded` (StoredImage, required): A copy of an image that Stylor stores itself. Only the object `key` is returned; turn it into a URL by prefixing the image delivery endpoint: `https://stylor.ai/api/v1/image/{key}`. Append transform segments such as `/-/resize/600x/-/format/webp` to that URL to get a resized or re-encoded variant. - `id` (string (uuid), required): Identifier of the stored copy. It is the UUID portion of `key`. [example `"3f9c2a1e-8d4b-4c6f-9a2e-1b7d5e0c4f88"`] - `key` (string, required): Object key to pass to `GET /v1/image/{key}`. Catalogue images use the form `images/.jpeg`. [example `"images/3f9c2a1e-8d4b-4c6f-9a2e-1b7d5e0c4f88.jpeg"`] - `generated` (DatasetItemGeneratedAssets): Assets Stylor generates for an item. Generative assets are currently disabled platform-wide, so new items carry a `null` thumbnail URL and an empty `segmented` list. - `thumbnail` (object): An AI-generated product thumbnail. - `url` (string, nullable): Absolute URL of the thumbnail on the image delivery endpoint, or `null` when none was generated. [example `null`] - `segmented` (array): Background-removed cut-outs. - `sourceImageId` (string, required): The `uploaded.id` of the product image the cut-out was made from. [example `"3f9c2a1e-8d4b-4c6f-9a2e-1b7d5e0c4f88"`] - `uploaded` (StoredImage, required): A copy of an image that Stylor stores itself. Only the object `key` is returned; turn it into a URL by prefixing the image delivery endpoint: `https://stylor.ai/api/v1/image/{key}`. Append transform segments such as `/-/resize/600x/-/format/webp` to that URL to get a resized or re-encoded variant. - `id` (string (uuid), required): Identifier of the stored copy. It is the UUID portion of `key`. [example `"3f9c2a1e-8d4b-4c6f-9a2e-1b7d5e0c4f88"`] - `key` (string, required): Object key to pass to `GET /v1/image/{key}`. Catalogue images use the form `images/.jpeg`. [example `"images/3f9c2a1e-8d4b-4c6f-9a2e-1b7d5e0c4f88.jpeg"`] - `variants` (array): Purchasable variants. Renamed from `sizes`, which is what the field had always held: a variant is the product of every option axis, so these rows are `S / Cream` and `Regular / XXS-UK6` — size crossed with colour, or with fit — not sizes. - `variantId` (string): The storefront's own variant id, when the source reported one. Empty for catalogues read from a store's public product feed, which does not return it. [example `"gid://shopify/ProductVariant/41611609636909"`] - `sku` (string, required): The variant SKU, exactly as supplied. [example `"A1A2P-BB2J-M"`] - `label` (string, required): The variant's full name, for example `Medium` or `M / Black`. [example `"M / Black"`] - `options` (array): Each option axis separately, which `label` cannot reliably be parsed back into. Axis names are merchant-authored and their casing is not dependable — one store writes `Size` and `Color`, another `size` and `fit`. Match case-insensitively. - `name` (string) [example `"Color"`] - `value` (string) [example `"Black"`] - `inStock` (boolean, required): The variant's availability at the last sync, in the market the product is priced in: the store's default market as stored, the shopper's own on a search result. [example `true`] - `quantity` (integer, nullable): Units in stock, or `null` when the source did not report a count. `null` and `0` are different answers. A public product feed never reports a count; a Storefront API source reports one only when its token carries the inventory scope. [example `4`] - `price` (number, required): Variant price in the product's `currency`. On a search result, the shopper's market's price (see `DatasetItemProduct.market`). [example `49`] - `compareAtPrice` (number, nullable): The variant's list price when it is reduced, otherwise `null`. In the same market as `price`. [example `79`] - `referencePrice` (number, nullable): Response only, on search results. The variant's stored price in the store's default market (in the product's `referenceCurrency`), present when the variant was re-priced for the shopper's market. Never stored. [example `49`] - `imageRef` (string, nullable): This variant's own photo, when the source distinguishes one from the product's. - `origin` (DatasetItemOrigin, required): Where the item came from. Copied from the dataset's store configuration at processing time. - `siteUrl` (string): Store URL from the dataset configuration. [default `""`; example `"https://shop.example.com"`] - `brandId` (string): Store identifier from the dataset configuration. [default `""`; example `"shop-example"`] - `brand` (string): Store or brand name. [default `""`; example `"Example Apparel"`] - `country` (string): Store country from the dataset configuration. [default `""`; example `"CA"`] - `createdAt` (string (date-time), required): When the processed item was first written. [example `"2025-03-04T18:22:41.913Z"`] - `updatedAt` (string (date-time), required): When the item was last rewritten by a sync or reprocess. [example `"2025-03-04T18:22:41.913Z"`] - `pagination` (ItemPagination, required): Page metadata returned by the item and queue list endpoints. There is no page count; iterate while `hasMore` is `true`. - `page` (integer, required): The page that was returned (1-based). [example `1`] - `limit` (integer, required): The page size that was applied. [example `10`] - `total` (integer, required): Total number of records matching the listing. [example `1284`] - `hasMore` (boolean, required): Whether `page + 1` would return at least one record. [example `true`] Example: ```json { "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": "

A heavyweight organic cotton tee with a relaxed fit.

", "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 } } ``` ## Errors Every error is a JSON object with an `error` string. Match on the status code; the message is written for people. | Status | Message | When | | --- | --- | --- | | 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. | ### Shared authentication, quota and rate-limit errors | Status | Message | When | | --- | --- | --- | | 401 | API key missing. | The `Authorization` header is absent, is not `Bearer `, or the key does not have three dash-separated segments. | | 401 | Authentication failed: public key is invalid or not recognized. | A public-key endpoint was called with a key that does not exist. | | 401 | Authentication failed: private key provided instead of a public key. | A public-key endpoint was called with an `sgpt-sk-…` key. | | 401 | Authentication failed: token is not recognized. | A private-key endpoint was called with a key whose lookup segment does not exist. | | 401 | Authentication failed: private key is invalid. | A private-key endpoint was called with a key whose secret does not match. | | 401 | Authentication failed: public key provided instead of a private key. | A private-key endpoint was called with an `sgpt-pk-…` key. | | 401 | Authentication failed: bearer token format is invalid. | A private key was sent without its `::` lookup segment. | | 401 | Authentication failed: API key could not be read. Regenerate the key. | The key's embedded organization data could not be decrypted or parsed. | | 403 | Demo mode is not available for private-key routes. Demos are only supported with public API keys. | The demo key was sent to a private-key endpoint. | | 403 | Demo mode is not supported on this API route. Check the documentation for available demo endpoints. | The demo key was sent to a public-key endpoint that opts out of demo mode. | | 403 | No active subscription for this organization. | The organization that owns the key has no active subscription. | | 403 | No quota found for organization "". | The organization has no quota record for the current billing period. | | 403 | No entitlement for "". | The plan's quota template has no entry for this endpoint. | | 403 | Access denied to "". | The plan's quota template turns this endpoint off. | | 429 | Monthly quota exceeded for "" (/ used). | The billing-period quota for this endpoint is exhausted. `Retry-After` gives the seconds until the period resets. | | 429 | RPM limit exceeded for "" (/ used). | More than the allowed requests per minute were sent. `Retry-After` is 60. | | 500 | Internal server error. | An unexpected failure on the server. The message is always this string; details are logged, never returned. Quota consumed by the request is refunded, as it is for every 5xx response. |