Skip to content

Get Engagement Counts#

Returns range-scoped engagement inventory counts for polls and trivia questions.

Endpoint#

GET /api/app/analytics/engagementCounts

Query Parameters#

Parameter Type Required Description
startDate string (ISO 8601) Yes Range start timestamp (must be aligned to a whole hour, UTC)
endDate string (ISO 8601) Yes Range end timestamp, exclusive (must be aligned to a whole hour, UTC)

Authentication#

This endpoint requires:

  • bearer authentication (Authorization: Bearer <token>)
  • an analytics-enabled CMS role (editor, admin, developer, superadmin, or systemadmin)
  • tenant context (for example x-storyteller-api-key: <tenant-guid>)

See Authentication for details.

Request#

Example Request#

GET /api/app/analytics/engagementCounts?startDate=2026-01-01T00:00:00Z&endDate=2026-02-01T00:00:00Z
Host: cmsapi.localhost
Authorization: Bearer <jwt>
x-storyteller-api-key: 11111111-2222-3333-4444-555555555555

Response#

Success Response#

Status Code: 200 OK

{
  "kind": "analytics.engagement-counts",
  "version": "1",
  "env": "Production",
  "tenant": "11111111-2222-3333-4444-555555555555",
  "range": {
    "startUtc": "2026-01-01T00:00:00Z",
    "endUtcExclusive": "2026-02-01T00:00:00Z"
  },
  "definitions": {
    "definitionVersion": "1"
  },
  "metrics": {
    "createdInRange": {
      "pollCount": 8,
      "triviaQuestionCount": 42
    },
    "activityInRange": {
      "pollCount": 5,
      "triviaQuestionCount": 19
    }
  }
}

Error Responses#

Status Code: 400 Bad Request

Common cases:

  • missing tenant context
  • startDate is not earlier than endDate
  • range is larger than the maximum supported window (120 days)
  • startDate or endDate is not aligned to a whole-hour boundary

Metric Definitions#

  • createdInRange.pollCount: number of poll entities created in the selected range.
  • createdInRange.triviaQuestionCount: number of trivia question entities created in the selected range.
  • activityInRange.pollCount: number of distinct polls with at least one vote event in the selected range.
  • activityInRange.triviaQuestionCount: number of distinct trivia questions with at least one answer event in the selected range.