Meisei

    Analytics

    POST /analytics/query

    Aggregate a resource into chart-ready rows. Name the measures and dimensions you want, and pass the same filter document the resource's list endpoint takes, so one filter can drive both the list and the chart. Measure and dimension names are whitelisted per resource: anything else is rejected. Grouping by a date buckets it with granularity in the organization's time zone, and the empty buckets inside the series are filled in. Grouping by anything else returns the top limit combinations plus one Other row carrying the rest, unless includeOther is false. from and to bound the query to a time range (lastDays to a window ending now), and ?format=csv answers as CSV for a spreadsheet or a BI tool.

    Requires the analytics:read permission.

    Costs 5 rate limit tokens instead of the usual one. See Rate limits.

    Query parameters

    formatjson | csv

    Answer as csv rather than json: one header row naming the columns, then one line per row. Sending Accept: text/csv does the same.

    Body parameters

    resourcereviews | review-answers | orders | customers | products | loyalty-members | loyalty-activity | loyalty-rewardsrequired

    The resource to aggregate. Call /analytics/schema for what each one offers.

    measuresstring[]required

    The measures to report, by name. Names are whitelisted per resource and anything else is rejected: reviews (measures: count, avgRating, publishedCount, flaggedCount, negativeCount, verifiedBuyerCount, uniqueCustomers, uniqueProducts); review-answers (measures: count, averageStep, uniqueReviews); orders (measures: count, revenue, averageOrderValue, uniqueCustomers); customers (measures: count, subscribedCount, optedOutCount); products (measures: count, reviewedCount); loyalty-members (measures: count, activeCount); loyalty-activity (measures: count, pointsEarned, pointsSpent); loyalty-rewards (measures: count, redeemedCount).

    groupBystring[]

    The dimensions to group by, by name, at most three and at most one of them a date. Omit for a single total row.

    granularityhour | day | week | month | quarter | year

    The bucket size for a date dimension. Defaults to day. Ignored when nothing in groupBy is a date.

    filterstring

    The same filter document the resource's list endpoint takes, so the filter bar's current filter can be sent to both.

    timezonestring

    The time zone to bucket date dimensions in, as an IANA name such as America/New_York. Defaults to the organization's own time zone.

    limitinteger

    How many distinct group-by combinations to return, from 1 to 500, ranked by the first measure. Defaults to 50, or to no limit when includeOther is false. Everything past the cap is re-aggregated into one "Other" row.

    includeOtherboolean

    Whether to collapse the combinations past limit into one "Other" row. Defaults to true, which suits a chart. Set it to false when another tool reads the rows: every dimension then keeps its real values, and with no limit every combination comes back, up to 10000 rows.

    fromstring (date-time)

    Only count records at or after this instant, as an ISO 8601 date and time. It applies to timeField, beside the filter, and a grouped date's series then starts here.

    tostring (date-time)

    Only count records before this instant, as an ISO 8601 date and time. It applies to timeField, beside the filter, and a grouped date's series then ends here.

    lastDaysinteger

    Only count records from the last this many days, up to now. It applies to timeField like from does, and an explicit from takes its place.

    timeFieldstring

    The date from and to apply to, by dimension name. Defaults to the date in groupBy, or to createdAt when nothing is grouped by a date.

    fillGapsboolean

    Whether to materialize the empty buckets inside a date series, so a quiet week reads as zero rather than as a straight line. Defaults to true.

    Request
    curl \
  -X POST \
  "https://your-store.meisei.app/api/analytics/query" \
  -H "Authorization: Bearer sk_YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "resource": "reviews",
  "measures": [
    "string"
  ],
  "groupBy": [
    "string"
  ],
  "granularity": "hour",
  "filter": "string",
  "timezone": "string",
  "limit": 0,
  "includeOther": true,
  "from": "2025-01-15T09:30:00Z",
  "to": "2025-01-15T09:30:00Z",
  "lastDays": 0,
  "timeField": "string",
  "fillGaps": true
}'
    Response
    {
  "data": ["..."],
  "meta": {
    "resource": "reviews",
    "timezone": "string",
    "granularity": "hour",
    "dimensions": [
      {
        "name": "...",
        "label": "...",
        "type": "...",
        "association": "...",
        "valueLabels": "..."
      }
    ],
    "measures": [
      {
        "name": "...",
        "label": "...",
        "type": "...",
        "description": "..."
      }
    ],
    "truncated": true,
    "otherLabel": "string"
  }
}

    GET /analytics/schema

    List what the analytics endpoint can aggregate: every resource, with the measures and dimensions it accepts and what each one means. Use it to build a chart picker, or to check a saved chart still names something real.

    Requires the analytics:read permission.

    Request
    curl \
  "https://your-store.meisei.app/api/analytics/schema" \
  -H "Authorization: Bearer sk_YOUR_SECRET_KEY"
    Response
    {
  "data": [
    {
      "resource": "string",
      "measures": ["..."],
      "dimensions": ["..."]
    }
  ]
}