Insights API

Reports

GET /reports/{report} serves the built-in reports. Time is set with from/to or last (1–366 days, or all); comparison with compare (none, previous_period, previous_year); grouping with grain; filtering with filter[]=dimension:value; ordering with sort=-measure.

The report names:

• overview
• products
• variants
• categories
• brands
• not_selling
• customers
• cohorts
• top_customers
• customer_groups
• fulfilment
• late_orders
• payments
• tax
• funnel
• searches

The report builder

POST /builder/run answers a custom question: measures, up to three dimensions, and filters. Rather than truncating a result that grew too large, it refuses with over_row_limit above 5,000 rows and suggests an export.

{
  "measures": ["net_sales", "orders"],
  "dimensions": ["category"],
  "filters": [
    { "dimension": "brand", "op": "in", "values": ["…"] }
  ],
  "last": 30
}

Permissions

Reads are permissioned per area — insights.sales.view, insights.products.view, insights.customers.view, insights.fulfilment.view, insights.finance.view, insights.behaviour.view — and each is also gated by the plan’s entitlements. Saved reports and schedules need insights.reports.manage, the builder insights.builder.use, and settings insights.settings.manage. A support session can only read: every write answers 403 support_read_only.

Refusals speak both languages

When insights refuses a request — a missing permission, a plan without the entitlement, a result over the row limit — the refusal carries a machine code plus message_ar and message_en, and often a suggestion for what to do instead.

Reports

• GET/measuresThe measures reports can show
• GET/statusData freshness, timezone, currency and sources
• GET/reports/{report}One of the built-in reports
• GET/dimensions/{dimension}/valuesValues of a filterable dimension
• POST/builder/runRun a custom report

Saved reports and schedules

• GET/saved-reportsList saved reports
• POST/saved-reportsSave a report
• PATCH/saved-reports/{id}Change a saved report
• DELETE/saved-reports/{id}Delete a saved report
• GET/schedulesList delivery schedules
• POST/schedulesSchedule a report delivery
• PATCH/schedules/{id}Change a schedule
• DELETE/schedules/{id}Delete a schedule
• GET/schedules/{id}/deliveriesWhat a schedule delivered

Exports and settings

• POST/exportsStart an export
• GET/exports/{id}The export’s progress
• GET/exports/{id}/fileDownload the finished file
• GET/settingsInsights settings
• PATCH/settingsChange insights settings