Retrend AI
Docs
Reports API

Reports API

Run and retrieve conversation and merchandising reports via /v2/reports.

Use the Reports API to generate and fetch analytics snapshots (conversation deltas, category trends, direct search OOS impact) for a store and time window. Two endpoints share the same payload:

  • POST <https://api.retrend.ai/v2/reports/general> — fetches the most recent report for the given parameters (or a specific start date).
  • POST <https://api.retrend.ai/v2/reports/run-now> — triggers generation immediately with the same request shape.

These examples assume you already created a session token as described in API Dependencies and you will authenticate each request with organization-id and x-session headers. Include kiosk headers (kiosk-id, x-kiosk, x-temp-kiosk, x-device-id) when calling from kiosk clients.

Request shape (ReportRequest)

All fields are in the JSON body:

  • store_num (number, required) — store number to report on.
  • report (enum Report, required) — one of:
    • conversation_delta_report
    • category_interest_trends
    • direct_search_oos_impact
  • duration (enum ReportDuration, required) — daily, weekly, monthly, quarterly, or yearly.
  • start_date (string, optional) — ISO date. If omitted, the most recent period is used.

Example (conversation delta, last completed week):

curl -X POST "https://api.retrend.ai/v2/reports/general" \
  -H "organization-id: $RETREND_ORG_ID" \
  -H "x-session: $RETREND_SESSION" \
  -H "Content-Type: application/json" \
  -d "{\"store_num\":2,\"report\":\"conversation_delta_report\",\"duration\":\"weekly\"}"

To force a fresh run:

curl -X POST "https://api.retrend.ai/v2/reports/run-now" \
  -H "organization-id: $RETREND_ORG_ID" \
  -H "x-session: $RETREND_SESSION" \
  -H "Content-Type: application/json" \
  -d "{\"store_num\":2,\"report\":\"category_interest_trends\",\"duration\":\"monthly\",\"start_date\":\"2024-08-01\"}"

Response shape (ReportResponse)

report is one of three typed report objects:

  • ConversationDeltaReport: volumes over time, intent breakdowns, and channel mix with percent change.
  • CategoryInterestTrendsReport: top/rising broadtypes and subtypes plus bar data.
  • DirectSearchOOSImpactReport: direct-search volume, OOS counts/rates, top searched products, and time-series for search and OOS rate.

Common fields across reports: report_name, client_id, store_num, duration, start_date, end_date, created_at. Each report adds its own metrics and chart series per the OpenAPI schema.

Implementation tips

  • Choose general for “latest period” retrieval; use run-now when you need on-demand freshness (with the same request body).
  • Use consistent store_num formatting; this API expects the numeric store number, not store_id.
  • Cache responses by (store_num, report, duration, start_date) to avoid redundant runs.
Info API EssentialsTagging API