Agent Native Batch Lookup

Batch lookup up to 100 products by ID with full agent-native metadata and currency conversion.

Base URL: https://api.buywhere.ai/v2/agents/batch-lookup

Overview

The Agent Native Batch Lookup endpoint retrieves detailed information for multiple products in a single request. It includes all agent-native enhancements like confidence scores, availability predictions, competitor counts, and supports currency conversion.

HTTP Method

POST /v2/agents/batch-lookup

Authentication

Requires API key in the Authorization header:

Authorization: Bearer bw_live_xxxxxxxxxxxxxxxx

Request Body

{
  "product_ids": [18472931, 18472932, 18472933],
  "target_currency": "USD",
  "affiliate_links": true,
  "include_metadata": true,
  "include_price_history": false
}

Request Example

cURL

curl -X POST "https://api.buywhere.ai/v2/agents/batch-lookup" \
  -H "Authorization: Bearer bw_live_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "product_ids": [18472931, 18472932, 18472933],
    "target_currency": "USD",
    "affiliate_links": true
  }'

Python

import httpx

API_KEY = "bw_live_xxxxxxxxxxxxxxxx"
BASE_URL = "https://api.buywhere.ai"

headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json"
}

response = httpx.post(
    f"{BASE_URL}/v2/agents/batch-lookup",
    json={
        "product_ids": [18472931, 18472932, 18472933],
        "target_currency": "USD",
        "affiliate_links": True
    },
    headers=headers
)
data = response.json()

print(f"Retrieved {data['total']} products")
for product in data['results']:
    print(f"\n{product['title']}")
    print(f"  ID: {product['id']}")
    print(f"  Price: {product['currency']} {product['price']}")
    print(f"  Price (SGD): {product.get('price_sgd', 'N/A')}")
    print(f"  Confidence: {product['confidence_score']}")
    print(f"  Availability: {product['availability_prediction']}")
    print(f"  Competitors: {product['competitor_count']}")
    print(f"  Buybox: {product['buybox_price']}")

JavaScript (Node.js)

const API_KEY = "bw_live_xxxxxxxxxxxxxxxx";
const BASE_URL = "https://api.buywhere.ai";

const response = await fetch(
  `${BASE_URL}/v2/agents/batch-lookup`,
  {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${API_KEY}`,
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      product_ids: [18472931, 18472932, 18472933],
      target_currency: "USD",
      affiliate_links: true
    })
  }
);

const data = await response.json();

console.log(`Retrieved ${data.total} products`);
data.results.forEach(product => {
  console.log(`\n${product.title}`);
  console.log(`  ID: ${product.id}`);
  console.log(`  Price: ${product.currency} ${product.price}`);
  console.log(`  Price (SGD): ${product.price_sgd || 'N/A'}`);
  console.log(`  Confidence: ${product.confidence_score}`);
  console.log(`  Availability: ${product.availability_prediction}`);
  console.log(`  Competitors: ${product.competitor_count}`);
  console.log(`  Buybox: ${product.buybox_price}`);
});

Go

package main

import (
    "bytes"
    "encoding/json"
    "fmt"
    "net/http"
)

func batchLookup(apiKey string, productIDs []int64) error {
    url := "https://api.buywhere.ai/v2/agents/batch-lookup"

    body := map[string]interface{}{
        "product_ids":      productIDs,
        "target_currency":  "USD",
        "affiliate_links":  true,
    }
    jsonBody, _ := json.Marshal(body)

    req, _ := http.NewRequest("POST", url, bytes.NewBuffer(jsonBody))
    req.Header.Set("Authorization", "Bearer "+apiKey)
    req.Header.Set("Content-Type", "application/json")

    client := &http.Client{}
    resp, err := client.Do(req)
    if err != nil {
        return err
    }
    defer resp.Body.Close()

    var result map[string]interface{}
    json.NewDecoder(resp.Body).Decode(&result)

    total := int(result["total"].(float64))
    fmt.Printf("Retrieved %d products\n", total)

    results := result["results"].([]interface{})
    for _, r := range results {
        m := r.(map[string]interface{})
        fmt.Printf("\n%s\n", m["title"])
        fmt.Printf("  ID: %.0f\n", m["id"].(float64))
        fmt.Printf("  Price: %s %s\n", m["currency"], m["price"])
        fmt.Printf("  Confidence: %.2f\n", m["confidence_score"].(float64))
    }
    return nil
}

Response

Success Response (200 OK)

{
  "results": [
    {
      "id": 18472931,
      "sku": "IPHONE15PRO256",
      "source": "shopee_sg",
      "title": "iPhone 15 Pro 256GB Natural Titanium",
      "price": "999.00",
      "currency": "USD",
      "price_sgd": "1349.00",
      "url": "https://shopee.sg/product/18472931",
      "brand": "Apple",
      "category": "Mobile Phones",
      "image_url": "https://cf.shopee.sg/file/xxxxx.jpg",
      "rating": 4.8,
      "review_count": 2341,
      "is_available": true,
      "in_stock": true,
      "stock_level": "in_stock",
      "confidence_score": 0.95,
      "availability_prediction": "in_stock",
      "competitor_count": 8,
      "buybox_price": "999.00",
      "affiliate_url": "https://buywhere.ai/track/abc123",
      "data_updated_at": "2026-04-15T12:00:00Z",
      "specs": {
        "storage": "256GB",
        "color": "Natural Titanium",
        "display": "6.1 inch Super Retina XDR"
      },
      "metadata_": {
        "original_price": 1499.00
      }
    }
  ],
  "total": 1,
  "has_more": false
}

Response Fields

Product Object Fields

Error Responses

401 Unauthorized

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or missing API key"
  }
}

422 Validation Error

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed",
    "details": {
      "errors": [
        {
          "field": "product_ids",
          "message": "Array must not exceed 100 items",
          "type": "max_length"
        }
      ]
    }
  }
}

Currency Conversion

Request prices in any supported currency:

---

Related Endpoints

• Agent Native Search - Search for products
• Agent Native Bulk Compare - Compare multiple products
• V2 Batch Details - Standard batch lookup