# Products Search Search Carrefour KSA's anonymous product catalog by keyword with 0-based pagination, SAR prices, discounts, availability, suppliers, and product URLs. - Platform: [Carrefour KSA](https://docs.upscrape.com/docs/platforms/carrefourksa) - Capability ID: `carrefourksa.products.search` - Cost: 1 credit per request - Maximum runtime: 120 seconds - Execute endpoint: `POST https://data.upscrape.com/execute` ## Request Use the exact public capability ID in the shared execute envelope. ```bash curl --request POST \ --url https://data.upscrape.com/execute \ --header "Authorization: Bearer YOUR_API_KEY" \ --header "Content-Type: application/json" \ --header "Prefer: wait=30" \ --data '{ "input": { "page": 0, "page_size": 5, "query": "milk", "sort_by": "relevance" }, "capability": "carrefourksa.products.search" }' ``` ## Input | Field | Type | Required | Description | | --- | --- | --- | --- | | `page` | `integer` | No | 0-based results page. | | `page_size` | `integer` | No | Products per page. Maximum 100. | | `query` | `string` | Yes | Product search text, for example milk, rice, or diapers. | | `sort_by` | `string` | No | Sort order. | ### Example input ```json { "page": 0, "page_size": 5, "query": "milk", "sort_by": "relevance" } ``` ## Response Successful output is returned in `results[0].data`. Raw platform output is intentionally open-ended and may evolve with the upstream source. ### Illustrative sample output This redacted fixture is an example, not a fixed response schema. ```json { "pagination": { "num_of_pages": 228, "page": 0, "total_products": 1137 }, "products": [ { "soldByWeight": false, "isBulk": false, "ean": "6281057010059", "isFBC": false, "category": [ { "aliasName": "FKSA1600000", "id": "FKSA1600000", "level": 1, "name": "Fresh Food", "url": "/c/FKSA1600000/" }, { "aliasName": "FKSA1630000", "id": "FKSA1630000", "level": 2, "name": "Dairy & Eggs", "url": "/c/FKSA1630000/" }, { "aliasName": "FKSA1630500", "id": "FKSA1630500", "level": 3, "name": "Milk & Laban", "url": "/c/FKSA1630500/" }, { "aliasName": "FKSA1630517", "id": "FKSA1630517", "level": 4, "name": "UHT Milk Full Fat", "url": "/c/FKSA1630517/" } ], "freeGift": false, "amendableOrders": [], "links": { "defaultImages": [ "https://cdn.mafrservices.com/sys-master-root/h94/h07/9153798471710/53201_main.jpg?im=Resize=1700", "https://cdn.mafrservices.com/sys-master-root/hdc/h1f/9111278747678/53201_1.jpg?im=Resize=1700" ], "images": [ { "href": "https://cdn.mafrservices.com/sys-master-root/h94/h07/9153798471710/53201_main.jpg?im=Resize=200", "kind": "image", "properties": { "format": "plpThumbnail", "imageType": "GALLERY", "url": "https://cdn.mafrservices.com/sys-master-root/h94/h07/9153798471710/53201_main.jpg?im=Resize=200" }, "rel": "assets", "type": "GET" }, { "href": "https://cdn.mafrservices.com/sys-master-root/hdc/h1f/9111278747678/53201_1.jpg?im=Resize=200", "kind": "image", "properties": { "format": "plpThumbnail", "imageType": "GALLERY", "url": "https://cdn.mafrservices.com/sys-master-root/hdc/h1f/9111278747678/53201_1.jpg?im=Resize=200" }, "rel": "assets", "type": "GET" } ], "productUrl": { "href": "/mafsau/en/uht-milk-full-fat/nadec-uht-ff-milk-1l-x12/p/53201", "kind": "product", "rel": "self", "type": "GET" }, "tracking": [] }, "type": "FOOD", "promoVoucher": {}, "variants": [], "dxtVouchers": [], "isMarketPlace": false, "availability": { "isAvailable": true, "max": 2 }, "servingIntents": [ "SLOTTED" ], "foodType": "FRESH", "preorder": false, "howGood": false, "bulkMessage": "", "ageRestricted": false, "isVirtualBundle": false, "supplier": "Carrefour", "delivery": [], "name": "Nadec Milk Long Life Full Fat 1L × 12 Pieces", "id": "53201", "promoBadges": [ { "id": "a72f55da-96e5-4e30-9b9c-d93188d791ca", "placement": "AREA-A", "priority": 1, "seller": "Carrefour", "text": { "boldText": "BESTSELLER", "normalText": "" }, "type": "BestSeller" } ], "productCategoriesHearchi": "Fresh Food/Dairy & Eggs/Milk & Laban/UHT Milk Full Fat", "price": { "currency": "SAR", "discount": { "endDate": "8/25/2026, 8:59:00 PM", "formattedValue": "SAR53.99", "minBuyingValue": "53.99", "price": 53.99, "type": "percentage", "value": 29 }, "formattedValue": "SAR76.25", "minBuyingValue": "76.25", "price": 76.25 }, "warranty": false, "extraLoyaltyPointsEarned": 0, "size": null, "brand": { "id": "14017", "name": "Nadec" }, "isExpress": false, "loyaltyPoints": 0, "isScalable": false, "isRecommended": false, "countryOrigin": null, "deliveryFees": { "freeDeliveryThreshold": 120 }, "productOrigin": null, "countryOriginEn": null, "nutritionIndicator": null, "unit": { "incrementBy": 1, "itemsPerUnit": 0, "max": 2, "maxToOrder": 2, "min": 1, "size": null, "unitItem": 0, "unitOfMeasure": "pieces" }, "page_type": "group_id", "stock": { "stockLevelStatus": "inStock" }, "isDirectMatch": true, "offers": [ { "brightbites": false, "id": "offer_carrefour_", "internationalShipping": false, "purchaseIndicators": { "SHIPPING": [ "SLOTTED" ] }, "sellerName": "Carrefour", "serviceProductTypes": null, "shippingIndicator": "SLOTTED", "shopId": "0000", "type": "main" } ], "availableVariants": [] }, { "soldByWeight": false, "isBulk": false, "ean": "6281039102154", "isFBC": false, "category": [ { "aliasName": "FKSA1600000", "id": "FKSA1600000", "level": 1, "name": "Fresh Food", "url": "/c/FKSA1600000/" }, { "aliasName": "FKSA1630000", "id": "FKSA1630000", "level": 2, "name": "Dairy & Eggs", "url": "/c/FKSA1630000/" }, { "aliasName": "FKSA1630500", "id": "FKSA1630500", "level": 3, "name": "Milk & Laban", "url": "/c/FKSA1630500/" }, { "aliasName": "FKSA1630517", "id": "FKSA1630517", "level": 4, "name": "UHT Milk Full Fat", "url": "/c/FKSA1630517/" } ], "freeGift": false, "amendableOrders": [], "links": { "defaultImages": [ "https://cdn.mafrservices.com/pim-content/SAU/media/product/745164/1754805604/745164_main.jpg?im=Resize=1700" ], "images": [ { "href": "https://cdn.mafrservices.com/pim-content/SAU/media/product/745164/1754805604/745164_main.jpg?im=Resize=200", "kind": "image", "properties": { "format": "plpThumbnail", "imageType": "GALLERY", "url": "https://cdn.mafrservices.com/pim-content/SAU/media/product/745164/1754805604/745164_main.jpg?im=Resize=200" }, "rel": "assets", "type": "GET" } ], "productUrl": { "href": "/mafsau/en/uht-milk-full-fat/saudia-whole-milk-ff-1ltr-x12/p/745164", "kind": "product", "rel": "self", "type": "GET" }, "tracking": [] }, "type": "FOOD", "promoVoucher": {}, "variants": [], "dxtVouchers": [], "isMarketPlace": false, "availability": { "isAvailable": true, "max": 2 }, "servingIntents": [ "SLOTTED" ], "foodType": "FRESH", "preorder": false, "howGood": false, "bulkMessage": "", "ageRestricted": false, "isVirtualBundle": false, "supplier": "Carrefour", "delivery": [], "name": "Saudia Whole Milk Full Fat UHT Milk 1L x12", "id": "745164", "promoBadges": [ { "id": "a72f55da-96e5-4e30-9b9c-d93188d791ca", "placement": "AREA-A", "priority": 1, "seller": "Carrefour", "text": { "boldText": "BESTSELLER", "normalText": "" }, "type": "BestSeller" } ], "productCategoriesHearchi": "Fresh Food/Dairy & Eggs/Milk & Laban/UHT Milk Full Fat", "price": { "currency": "SAR", "formattedValue": "SAR72.00", "minBuyingValue": "72.00", "price": 72 }, "warranty": false, "extraLoyaltyPointsEarned": 0, "size": "1L x12", "brand": { "id": "13138", "name": "Saudia" }, "isExpress": false, "loyaltyPoints": 0, "isScalable": false, "isRecommended": false, "countryOrigin": null, "deliveryFees": { "freeDeliveryThreshold": 120 }, "productOrigin": null, "countryOriginEn": null, "nutritionIndicator": null, "unit": { "incrementBy": 1, "itemsPerUnit": 0, "max": 2, "maxToOrder": 2, "min": 1, "size": "1L x12", "unitItem": 0, "unitOfMeasure": "pieces" }, "page_type": "group_id", "stock": { "stockLevelStatus": "inStock" }, "isDirectMatch": true, "offers": [ { "brightbites": false, "id": "offer_carrefour_", "internationalShipping": false, "purchaseIndicators": { "SHIPPING": [ "SLOTTED" ] }, "sellerName": "Carrefour", "serviceProductTypes": null, "shippingIndicator": "SLOTTED", "shopId": "0000", "type": "main" } ], "availableVariants": [] }, { "soldByWeight": false, "isBulk": false, "ean": "6281007034043", "isFBC": false, "category": [ { "aliasName": "FKSA1600000", "id": "FKSA1600000", "level": 1, "name": "Fresh Food", "url": "/c/FKSA1600000/" }, { "aliasName": "FKSA1630000", "id": "FKSA1630000", "level": 2, "name": "Dairy & Eggs", "url": "/c/FKSA1630000/" }, { "aliasName": "FKSA1630500", "id": "FKSA1630500", "level": 3, "name": "Milk & Laban", "url": "/c/FKSA1630500/" }, { "aliasName": "FKSA1630502", "id": "FKSA1630502", "level": 4, "name": "Full Fat Milk", "url": "/c/FKSA1630502/" } ], "freeGift": false, "amendableOrders": [], "links": { "defaultImages": [ "https://cdn.mafrservices.com/pim-content/SAU/media/product/560836/1755187203/560836_main.jpg?im=Resize=1700", "https://cdn.mafrservices.com/pim-content/SAU/media/product/560836/1755187203/560836_1.jpg?im=Resize=1700", "https://cdn.mafrservices.com/sys-master-root/h14/h0e/50520430116894/560836_2.jpg?im=Resize=1700" ], "images": [ { "href": "https://cdn.mafrservices.com/pim-content/SAU/media/product/560836/1755187203/560836_main.jpg?im=Resize=200", "kind": "image", "properties": { "format": "plpThumbnail", "imageType": "GALLERY", "url": "https://cdn.mafrservices.com/pim-content/SAU/media/product/560836/1755187203/560836_main.jpg?im=Resize=200" }, "rel": "assets", "type": "GET" }, { "href": "https://cdn.mafrservices.com/pim-content/SAU/media/product/560836/1755187203/560836_1.jpg?im=Resize=200", "kind": "image", "properties": { "format": "plpThumbnail", "imageType": "GALLERY", "url": "https://cdn.mafrservices.com/pim-content/SAU/media/product/560836/1755187203/560836_1.jpg?im=Resize=200" }, "rel": "assets", "type": "GET" }, { "href": "https://cdn.mafrservices.com/sys-master-root/h14/h0e/50520430116894/560836_2.jpg?im=Resize=200", "kind": "image", "properties": { "format": "plpThumbnail", "imageType": "GALLERY", "url": "https://cdn.mafrservices.com/sys-master-root/h14/h0e/50520430116894/560836_2.jpg?im=Resize=200" }, "rel": "assets", "type": "GET" } ], "productUrl": { "href": "/mafsau/en/full-fat-milk/almarai-fresh-milk-ff-2-85l/p/560836", "kind": "product", "rel": "self", "type": "GET" }, "tracking": [] }, "type": "FOOD", "promoVoucher": {}, "variants": [], "dxtVouchers": [], "isMarketPlace": false, "availability": { "isAvailable": true, "max": 50 }, "servingIntents": [ "SLOTTED" ], "foodType": "FRESH", "preorder": false, "howGood": false, "bulkMessage": "", "ageRestricted": false, "isVirtualBundle": false, "supplier": "Carrefour", "delivery": [], "name": "Almarai Full Fat Fresh Milk 2.85L", "id": "560836", "promoBadges": [ { "id": "a72f55da-96e5-4e30-9b9c-d93188d791ca", "placement": "AREA-A", "priority": 1, "seller": "Carrefour", "text": { "boldText": "BESTSELLER", "normalText": "" }, "type": "BestSeller" } ], "productCategoriesHearchi": "Fresh Food/Dairy & Eggs/Milk & Laban/Full Fat Milk", "price": { "currency": "SAR", "formattedValue": "SAR16.50", "minBuyingValue": "16.50", "price": 16.5 }, "warranty": false, "extraLoyaltyPointsEarned": 0, "size": null, "brand": { "id": "03111", "name": "Almarai" }, "isExpress": false, "loyaltyPoints": 0, "isScalable": false, "isRecommended": false, "countryOrigin": null, "deliveryFees": { "freeDeliveryThreshold": 120 }, "productOrigin": null, "countryOriginEn": null, "nutritionIndicator": null, "unit": { "incrementBy": 1, "itemsPerUnit": 0, "max": 50, "maxToOrder": 50, "min": 1, "size": null, "unitItem": 0, "unitOfMeasure": "pieces" }, "page_type": "group_id", "stock": { "stockLevelStatus": "inStock" }, "isDirectMatch": true, "offers": [ { "brightbites": false, "id": "offer_carrefour_", "internationalShipping": false, "purchaseIndicators": { "SHIPPING": [ "SLOTTED" ] }, "sellerName": "Carrefour", "serviceProductTypes": null, "shippingIndicator": "SLOTTED", "shopId": "0000", "type": "main" } ], "availableVariants": [] } ], "query": "milk" } ``` ### Illustrative output fields Derived from the sample above for orientation only. These fields are not a fixed response schema. | Path | Observed type | Example | | --- | --- | --- | | `pagination` | `object` | 3 fields | | `pagination.num_of_pages` | `integer` | 228 | | `pagination.page` | `integer` | 0 | | `pagination.total_products` | `integer` | 1137 | | `products` | `array` | 3 items | | `products` | `array` | 3 items | | `query` | `string` | milk | ## Execution behavior A `200` response completed inline. A `202` response was queued; poll `GET /jobs/{id}` until the job reaches `completed` or `failed`. Use an `Idempotency-Key` when retrying must not create a duplicate logical job. ## Related documentation - [Authentication](https://docs.upscrape.com/docs/api/authentication) - [Jobs and results](https://docs.upscrape.com/docs/api/jobs) - [Errors and retries](https://docs.upscrape.com/docs/api/errors) - [Idempotency](https://docs.upscrape.com/docs/api/idempotency)