Product Insights.

The endpoint is a single synchronous POST. Send whichever of the three datasets you have. The endpoint runs every analyzer that its inputs support and returns all insights in one response. You do not need to call /forecast or any other endpoint first. The endpoint does the required statistical modeling internally.

Example Request

{
  "identifier": "SKU-12345",
  "product_name": "Wireless Mouse",
  "base_currency": "USD",
  "sales": [
    {"date": "2024-01-05", "quantity_sold": 12, "selling_price": 25.00},
    {"date": "2024-02-05", "quantity_sold": 18, "selling_price": 25.00},
    {"date": "2024-03-05", "quantity_sold": 9,  "selling_price": 22.50}
  ],
  "purchases": [
    {"date": "2024-01-01", "quantity_purchased": 100, "cost_price": 10.00,
     "supplier_id": "SUPP-001", "purchase_order_date": "2023-12-18",
     "expected_delivery_date": "2023-12-30", "actual_delivery_date": "2024-01-01"}
  ],
  "cost_history": [
    {"date": "2024-01-01", "cost_price": 10.00},
    {"date": "2024-03-01", "cost_price": 11.50, "change_reason": "supplier price increase"}
  ],
  "insight_settings": {
    "margin_threshold": 0.10,
    "enable_seasonality_detection": true
  }
}

Top-level fields identify the product and configure the analysis. Unlike the forecasting endpoints, product-insights takes no model, periods, or frequency. It works directly from the data you provide.

Every row in every dataset needs a date. Dates must be YYYY-MM-DD or YYYY-MM-DD HH:MM:SS. The format must be consistent within a dataset. You cannot mix date-only and date-time rows in the same array. The API sorts the rows chronologically for you, so you can send them in any order.

sales[]

purchases[]

cost_history[]

The optional insight_settings object controls how sensitive the analyzers are. Thresholds use fractions: 0.30 means "flag a 30% change." For any value you omit, the API uses the defaults below.

On success (HTTP 200) the body always has the same top-level shape. It contains a result object with the analysis and a meta object with timing and data-quality information.

{
  "result": {
    "tenant_context": null,
    "identifier": "SKU-12345",
    "product_info": { "name": "Wireless Mouse", "group_id": null },
    "base_currency": "USD",
    "insights": [
      {
        "class": "margin",
        "type": "margin_compression",
        "severity": "warning",
        "title": "Margin dropped 8.2% versus baseline",
        "description": "Average gross margin fell from 58.0% to 49.8% over the recent period.",
        "metrics": {
          "current_margin_percent": 49.8,
          "baseline_margin_percent": 58.0,
          "margin_change_percentage": -8.2,
          "transactions_analyzed": 3
        },
        "recommendation": {
          "action": "review_pricing",
          "description": "Review selling price or negotiate cost to protect margin.",
          "priority": "high"
        },
        "confidence": "medium",
        "date": "2024-03-05",
        "change_status": "new"
      }
    ],
    "summary": {
      "total_insights": 1,
      "severity_distribution": { "critical": 0, "warning": 1, "info": 0 },
      "categories": ["profitability"],
      "analysis_period": { "start_date": "2024-01-01", "end_date": "2024-03-05", "total_days": 65 },
      "data_sources_analyzed": ["sales", "purchases", "cost_history"]
    },
    "comparison": null
  },
  "meta": {
    "timing": { "validation": 2.1, "analysis": 148.7, "total": 151.9 },
    "data_quality": {
      "total_data_points": 6,
      "datasets_provided": ["sales", "purchases", "cost_history"]
    }
  }
}

result fields

result.summary fields

summary.categories — possible values

Each insight type maps to one business category. On this single-product endpoint you will see these values:

• sales
• profitability
• costs
• purchasing
• currency
• sales_patterns
• supply_chain
• seasonal_patterns

Portfolio-level categories (pricing, customer_risk, portfolio_risk, categories, inventory_management) only appear via batch analysis, which compares products against each other.

Every entry in insights has the same envelope. The metrics object is the only part whose keys vary. They depend on the insight type (documented in the catalog).

Which analyzers run depends on which datasets you send. The tables below group every insight type by the dataset that enables it, with the severity levels it can emit and its most important metrics. A type appears in the response only when it meets its trigger condition, usually a change beyond the relevant threshold.

Requires sales

Requires purchases

Requires cost_history

Cross-currency (any dataset, needs ≥ 2 distinct currencies)

The endpoint stores every analysis against its identifier (and tenant_context, if given). On the next call for the same product, the endpoint compares the new insights against the previous run and returns a comparison object. You can then show what is new since the last analysis, instead of showing everything again. The comparison object is null only on the very first analysis.

"comparison": {
  "from": "2024-06-01T09:14:22+00:00",
  "to": "2024-07-01T08:02:11+00:00",
  "result": [
    {
      "hasSignificantChange": true,
      "summary": "Margin fell a further 4.1 points",
      "changes": [
        {
          "class": "margin",
          "metric": "current_margin_percent",
          "previousValue": 49.8,
          "currentValue": 45.7,
          "change": -4.1,
          "changePercentage": -8.2,
          "isSignificant": true,
          "severity": "warning",
          "description": "Margin continued to compress."
        }
      ]
    }
  ],
  "developments": {
    "new": [ { "type": "cost_price_change", "class": "cost", "severity": "warning", "title": "Unit cost up 15%" } ],
    "changed": [ { "type": "margin_compression", "class": "margin", "severity": "warning", "title": "Margin dropped further" } ],
    "resolved": [ { "type": "sales_volume_anomaly", "class": "sales", "severity": "info", "title": "Sales spike normalised" } ],
    "unchanged_count": 2,
    "summary": "1 new, 1 changed, 1 resolved, 2 unchanged"
  }
}

developments

The top-level meta object reports timing and a quick summary of the data you supplied.

To analyze many products at once, upload them as a batch. Batch analysis runs asynchronously. It also computes portfolio-level insights that compare products against each other: ABC classification, customer and product-group concentration, price elasticity, and weekday performance. The single-product endpoint cannot produce these insights.

Send a series array of 1–1000 items. Each item has exactly the same shape as a single /product-insights body. The API rejects structural problems immediately with a 422 and a per-index error map, and it queues nothing. Structural problems are a missing identifier, no dataset at all, or a payload above your plan's datapoint limit. On success you receive 202 Accepted immediately with a batch you can poll. The full per-datapoint validation runs during processing. An item that fails it appears as a failed analysis in the batch status, with the validation error, and does not block the upload.

{
  "series": [
    {
      "identifier": "SKU-1",
      "sales": [
        {"date": "2024-01-15", "quantity_sold": 10, "selling_price": 5.00},
        {"date": "2024-02-15", "quantity_sold": 20, "selling_price": 5.00}
      ]
    },
    {
      "identifier": "SKU-2",
      "cost_history": [
        {"date": "2024-01-01", "cost_price": 2.00},
        {"date": "2024-03-01", "cost_price": 2.60}
      ]
    }
  ]
}

Very large payloads can exceed the server's request-body limit and fail mid-transfer. For those payloads, request a presigned upload URL. PUT your JSON payload directly to upload_url. The payload is an object with the same series array. Then submit the batch: POST the returned file_key to /v2/batch/product-insights instead of series. With a file upload, all validation runs asynchronously. Invalid items appear as failed analyses in the batch status.

{
  "upload_url": "https://s3.…(signed URL, valid 30 minutes)",
  "headers": {},
  "file_key": "batch-uploads/product-insights/42/9b2c….json",
  "expires_in": 1800
}

Poll with the batch identifier. The response carries a status of pending, processing, completed, or failed. When the batch finishes, the response also carries the per-product results. An unknown identifier returns 404.

{
  "uuid": "9b2c...",
  "identifier": "my-batch-01",
  "status": "completed",
  "batch_parts": 1,
  "results": [ /* one analysis per product, same shape as result.insights */ ],
  "started_at": "2024-07-01T08:00:00+00:00",
  "completed_at": "2024-07-01T08:00:12+00:00"
}

HTTP Status Codes

422 Validation Error

{
  "error": "Validation failed",
  "errors": {
    "identifier": ["The identifier field is required."],
    "data": ["At least one dataset (sales, purchases, or cost_history) must be provided."]
  },
  "time_taken_ms": 1.4
}

400 Bad Request

{
  "error": "Could not analyse the supplied data",
  "time_taken_ms": 3.2
}