Retrieve a queue entry

get/v1/datasets/{datasetId}/items/queue/{itemId}

Returns one queue entry by itemId, in any status including archived. Use it to poll a single product after upload, or to read worker.failure when an entry is failed.

This endpoint returns the stored document as-is, so the response also contains the internal _id and __v fields. Ignore them; they are not part of the contract and are absent from the list endpoint.

Private keyapi.v1.datasets.items.queue.retrieveNo demo

Path parameters

datasetIdstring (uuid)required

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

itemIdstring (uuid)required

The queue entry's itemId, as returned by the queue listing. The upload endpoint does not return ids.

Response

200The queue entry.

objectrequired

An entry in a dataset's ingest queue. Uploading products creates one entry per product in pending; a background worker claims entries, downloads images, extracts metadata and embeddings, and writes a DatasetItem with the same itemId. The entry is kept after processing with status complete (or failed); uploading or syncing the same SKU again updates this entry rather than creating another. Status meanings: pending waiting for a worker; processing claimed; partial_update a price/stock refresh that skips AI processing; complete a DatasetItem was written; failed see worker.failure; archived hidden from listings.

itemIdstring (uuid)required

Queue entry id, assigned at upload. The processed DatasetItem reuses it.

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

organizationIdstring (uuid)required

Owning organization.

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

datasetIdstring (uuid)required

Target dataset.

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

statusstringrequired

Processing state.

One ofpendingprocessingpartial_updatecompletefailedarchived

e.g. "pending"

QueueWorkerState

Processing bookkeeping. Created with an empty logs list at upload; the other sub-fields appear once a worker or sync sets them.

disableGenerativeAssetsboolean

Whether AI thumbnails are skipped. Always true at present because generative assets are disabled platform-wide.

default: truee.g. true

forceFullProcessboolean

When true the worker runs the full AI pipeline even if the SKU already exists as a processed item. Set internally by store syncs.

default: falsee.g. false

IngestProductrequired

The raw product shape accepted by the upload endpoint and stored on the queue entry as data. It mirrors a Shopify product export. Every field listed is required except gender. description and productType may be empty strings; name, handle and sku must be non-empty (an empty value passes field validation but fails at the database with a 500). The three date fields must be parseable and are normalised to ISO 8601 UTC on the way in.

versionnumberrequired

Ingest pipeline version the entry will be processed with.

e.g. 1

createdAtstring (date-time)required

When the entry was queued.

e.g. "2025-03-04T18:19:58.120Z"

updatedAtstring (date-time)required

Last status or worker change.

e.g. "2025-03-04T18:19:58.120Z"

_idstring

Internal database id. Not part of the contract.

__vinteger

Internal document version. Not part of the contract.

Errors

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

401

Organization '<organizationId>' not found.

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.

404

Queued item '<itemId>' not found in dataset '<datasetId>' for organization '<organizationId>'.

The dataset exists but its queue holds no entry with this itemId.

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

Response · 200

{
  "item": {
    "_id": "67c74b5e2f1a9c0012d4e8a1",
    "itemId": "8b0a1b62-7c2a-4b7f-9e2c-0f3a9b1f0c11",
    "organizationId": "0a2c1f4e-5b6d-7e8f-9012-3456789abcde",
    "datasetId": "c9b3c6c0-9b0f-4f42-bf3f-2b7a6b1b9d31",
    "status": "failed",
    "worker": {
      "logs": [
        {
          "type": "info",
          "message": "Claimed by worker w-7f2a",
          "createdAt": "2025-03-04T18:20:03.001Z"
        },
        {
          "type": "error",
          "message": "Failed: No images could be downloaded",
          "createdAt": "2025-03-04T18:21:10.442Z"
        }
      ],
      "lockedBy": null,
      "lockedAt": null,
      "failure": {
        "reason": "No images could be downloaded",
        "code": "PROCESSING_FAILED",
        "details": null,
        "timestamp": "2025-03-04T18:21:10.442Z"
      }
    },
    "disableGenerativeAssets": true,
    "forceFullProcess": false,
    "data": {
      "name": "Classic Crew Tee",
      "handle": "classic-crew-tee",
      "description": "",
      "publishedAt": "2024-11-02T09:15:00.000Z",
      "createdAt": "2024-11-02T09:15:00.000Z",
      "updatedAt": "2025-02-10T12:00:00.000Z",
      "productType": "T-Shirts",
      "sku": "A1A2P-BB2J",
      "price": 49,
      "tags": [],
      "variants": [],
      "images": [
        {
          "src": "https://cdn.shopify.com/s/files/1/0001/products/missing.jpg"
        }
      ],
      "options": []
    },
    "version": 1,
    "createdAt": "2025-03-04T18:19:58.120Z",
    "updatedAt": "2025-03-04T18:21:10.442Z",
    "__v": 0
  }
}