Insights

AI-powered analytics, anomaly detection, and intelligent recommendations for the Operations Command Center. Generate insights from real order and shipment data, ask natural language questions, and track carrier performance.

Generate Insights

POST/api/v1/insights/generate

Generate insights for an operation or organization.

Requiredinsights:read

Runs rule-based analysis and shipping analytics to produce insights such as anomalies, optimization suggestions, predictions, trends, alerts, and recommendations. When an operationId is provided, the analysis is scoped to that specific operation; otherwise, organization-wide shipping insights are returned.

Request Body

Field	Type	Description
`scope`	string	Insight scope: `operation`, `organization`, or `orders` (default: `operation`)
`operationId`	string	UUID of the operation to analyze (optional)
`orderIds`	string[]	Array of order UUIDs to scope analysis to (optional)
`types`	string[]	Filter by insight categories (optional). Values: `anomaly`, `optimization`, `prediction`, `trend`, `alert`, `recommendation`


curl -X POST "https://api.orderly-hub.com/api/v1/insights/generate" \
  -H "Authorization: Bearer oh_..." \
  -H "Content-Type: application/json" \
  -d '{
    "scope": "operation",
    "operationId": "550e8400-e29b-41d4-a716-446655440000",
    "types": ["anomaly", "recommendation"]
  }'

Response


{
  "data": {
    "insights": [
      {
        "id": "insight-1712000000000-cost_trend",
        "category": "trend",
        "severity": "info",
        "status": "new",
        "title": "Shipping Cost Trend",
        "summary": "Average shipping cost has increased 12% over the last 30 days.",
        "metrics": [
          { "label": "Average Cost", "value": "$8.42" },
          { "label": "Total Shipments", "value": 340 }
        ],
        "confidence": 0.9,
        "tags": ["cost_trend"],
        "detectedAt": "2026-04-08T12:00:00.000Z",
        "source": "rule-engine"
      },
      {
        "id": "abc-123",
        "category": "recommendation",
        "severity": "low",
        "status": "new",
        "title": "Consider consolidating shipments to Northeast region",
        "summary": "12 orders share destination clusters in the Northeast corridor.",
        "metrics": [
          { "label": "Count", "value": 12 },
          { "label": "Total Value", "value": "$1,284.50" }
        ],
        "actions": [
          {
            "id": "action-abc-123",
            "label": "View destination cluster",
            "type": "execute",
            "command": "destination_cluster"
          }
        ],
        "confidence": 0.85,
        "tags": ["destination_cluster"],
        "detectedAt": "2026-04-08T12:00:00.000Z",
        "source": "rule-engine"
      }
    ],
    "generatedAt": "2026-04-08T12:00:00.000Z",
    "expiresAt": "2026-04-08T12:05:00.000Z"
  }
}

Get Operation Insights

GET/api/v1/insights/operations/:operationId

Get a detailed insights summary for an operation.

Requiredinsights:read

Returns a comprehensive insights summary for a specific operation, including cost breakdowns by carrier and service, risk analysis, optimization recommendations, detected anomalies, and all generated insights. Cost data is derived from rate snapshots attached to the operation’s items.

Path Parameters

Parameter	Type	Description
`operationId`	string	UUID of the operation


curl -X GET "https://api.orderly-hub.com/api/v1/insights/operations/550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer oh_..."

Response


{
  "data": {
    "operationId": "550e8400-e29b-41d4-a716-446655440000",
    "operationName": "Weekly Fulfillment Batch",
    "summary": {
      "totalOrders": 142,
      "estimatedCost": 1823.50,
      "estimatedSavings": 0,
      "averageTransitDays": 3.2,
      "riskScore": 10
    },
    "costBreakdown": {
      "byCarrier": [
        { "carrier": "ups", "amount": 1205.30, "percentage": 66 },
        { "carrier": "fedex", "amount": 618.20, "percentage": 34 }
      ],
      "byService": [
        { "service": "GROUND", "amount": 1102.00, "percentage": 60 },
        { "service": "EXPRESS", "amount": 721.50, "percentage": 40 }
      ]
    },
    "riskAnalysis": {
      "highRiskOrders": 1,
      "delayRisk": 2,
      "weatherImpact": false,
      "carrierCapacityIssues": false
    },
    "optimizations": [],
    "anomalies": [],
    "insights": [
      {
        "id": "insight-001",
        "category": "recommendation",
        "severity": "low",
        "status": "new",
        "title": "Consider carrier consolidation",
        "summary": "Shifting 10% of UPS volume to FedEx Ground could save ~$45/week.",
        "confidence": 0.85,
        "tags": ["carrier_recommendation"],
        "detectedAt": "2026-04-08T12:00:00.000Z",
        "source": "rule-engine"
      }
    ]
  }
}

Ask Insights

POST/api/v1/insights/ask

Ask a natural language question about your data.

Requiredinsights:read

Submit a natural language question about your orders, shipments, carriers, or operations. Returns an answer with related insights and suggested follow-up queries. For deeper conversational analysis, use the AI agent chat endpoint.

Request Body

Field	Type	Description
`query`	string	Natural language question (1-1000 characters, required)
`context`	object	Optional context to scope the query
`context.operationId`	string	UUID of a specific operation
`context.orderIds`	string[]	Array of order UUIDs to focus on
`context.dateRange`	object	`{ start: string, end: string }` ISO 8601 date range
`context.includeOrders`	boolean	Include order data in analysis context
`context.includeShipments`	boolean	Include shipment data in analysis context
`context.includeCarriers`	boolean	Include carrier data in analysis context
`context.includeRates`	boolean	Include rate data in analysis context


curl -X POST "https://api.orderly-hub.com/api/v1/insights/ask" \
  -H "Authorization: Bearer oh_..." \
  -H "Content-Type: application/json" \
  -d '{
    "query": "Which carrier has the best on-time delivery rate this month?",
    "context": {
      "dateRange": {
        "start": "2026-04-01T00:00:00Z",
        "end": "2026-04-08T23:59:59Z"
      },
      "includeCarriers": true
    }
  }'

Response


{
  "data": {
    "response": {
      "answer": "Your question \"Which carrier has the best on-time delivery rate this month?\" has been noted. For detailed analytics, check the carrier performance and operation insights sections of the dashboard. For conversational analysis, use the AI agent chat which can query your data in real-time.",
      "insights": [],
      "suggestedQueries": [
        "View carrier performance",
        "Analyze operation costs",
        "Check delivery trends"
      ],
      "referencedData": {
        "orders": 0,
        "timeRange": "2026-04-01T00:00:00Z to 2026-04-08T23:59:59Z"
      },
      "processingTime": 50,
      "tokensUsed": 0
    },
    "generatedAt": "2026-04-08T12:00:00.000Z"
  }
}

Acknowledge Insight

POST/api/v1/insights/:insightId/acknowledge

Acknowledge, resolve, or dismiss an insight.

Requiredinsights:write

Updates the status of an insight. Use this to mark insights as acknowledged, resolved, or dismissed so they no longer appear as active alerts.

Path Parameters

Parameter	Type	Description
`insightId`	string	ID of the insight

Request Body

Field	Type	Description
`action`	string	One of `acknowledge`, `resolve`, or `dismiss` (default: `acknowledge`)
`note`	string	Optional note explaining the action (max 500 characters)


curl -X POST "https://api.orderly-hub.com/api/v1/insights/insight-abc-123/acknowledge" \
  -H "Authorization: Bearer oh_..." \
  -H "Content-Type: application/json" \
  -d '{
    "action": "resolve",
    "note": "Addressed by switching to FedEx Ground for Northeast orders."
  }'

Response


{
  "data": {
    "insightId": "insight-abc-123",
    "action": "resolve",
    "acknowledgedAt": "2026-04-08T12:05:00.000Z",
    "note": "Addressed by switching to FedEx Ground for Northeast orders."
  }
}

Get Carrier Performance

GET/api/v1/insights/carriers/performance

Get carrier performance insights from real shipment data.

Requiredinsights:read

Returns performance metrics for all carriers used by your organization, calculated from actual shipment data. Includes on-time rates, average transit times, cost per package, and trend indicators.

Query Parameters

Parameter	Type	Description
`days`	number	Lookback period in days (default: 30)


curl -X GET "https://api.orderly-hub.com/api/v1/insights/carriers/performance?days=30" \
  -H "Authorization: Bearer oh_..."

Response


{
  "data": [
    {
      "carrierId": "ups",
      "carrierName": "UPS",
      "onTimeRate": 0.94,
      "averageTransitDays": 3.1,
      "costPerPackage": 8.42,
      "totalShipments": 215,
      "deliveredCount": 202,
      "onTimeTrend": "stable",
      "costTrend": "up",
      "dateRange": {
        "start": "2026-03-09",
        "end": "2026-04-08"
      }
    },
    {
      "carrierId": "fedex",
      "carrierName": "FedEx",
      "onTimeRate": 0.97,
      "averageTransitDays": 2.8,
      "costPerPackage": 9.15,
      "totalShipments": 125,
      "deliveredCount": 121,
      "onTimeTrend": "improving",
      "costTrend": "down",
      "dateRange": {
        "start": "2026-03-09",
        "end": "2026-04-08"
      }
    }
  ]
}