Skip to documentation

Feedback

Reconcile raw rating events and calculate transparent, reproducible fixed-window rollups while keeping feedback subjects, Study context, accounts, and source paths distinct.

2 endpoints

GET

List feedback events

GET /external/v1/studies/feedback

Read the raw, response-level audit feed. submittedAt is the rating event time: the Study response time for Study completion feedback, or the later Pulse submission time for a Live Interview. source identifies that path. The immutable feedback subject is separate from the Study’s current accepted context. For a stable synchronization run, hold submittedTo fixed, then follow X-Has-More and advance offset by X-Limit. submittedFrom is inclusive; submittedTo is exclusive. Resolve accountId through the Accounts API when customer names are needed.

Requirements

API scopes required:
studies:read

Request

Parameters

NameTypeDescription
metric stringStable metric key.
subjectType stringImmutable subject type.
subjectId uuidImmutable subject id.
submittedFrom ISO timestampInclusive rating event timestamp.
submittedTo ISO timestampExclusive rating event timestamp.
initiativeId uuidCurrent accepted Initiative context.
ideaId uuidCurrent accepted Idea context.
accountId uuidExact Account filter.
limit number1–100 results.
offset numberNumber of results to skip.

Responses

200
Success

Feedback events were retrieved.

Schema
Array<FeedbackEvent>

Example Response

200 OK
json
[
  {
    "id": "response-uuid",
    "rating": 5,
    "metric": "initiative_direction",
    "subject": {
      "type": "initiative",
      "id": "initiative-uuid"
    },
    "comment": "Keep this direction.",
    "submittedAt": "2026-07-14T10:00:00Z",
    "source": "live_interview",
    "accountId": "account-uuid",
    "study": {
      "id": "study-uuid",
      "publicId": "STUDY-8",
      "name": "Scheduler direction check",
      "status": "active",
      "type": "heatmap_interaction",
      "phase": "validation",
      "appPath": "/studies/STUDY-8"
    },
    "initiativeIds": [
      "initiative-uuid"
    ],
    "ideaIds": []
  }
]
GET

Summarize feedback

GET /external/v1/feedback/summary

Return one reproducible metric-and-subject rollup over rating event time. Average, rating sum, rated count, observable eligible interactions, coverage, distribution, source paths, comparison, Studies, and comments remain distinct. A copied Pulse link is not counted as delivered feedback; a submitted Live Interview Pulse is both rated and observable. Comment accounts include an id only; resolve names with accounts:read.

Requirements

API scopes required:
studies:read

Request

Parameters

NameTypeDescription
metric *stringStable metric key, such as initiative_direction.
subjectType *stringSubject type required by the metric.
subjectId *uuidImmutable rating subject.
windowStart ISO timestampInclusive start. Defaults to 14 days before windowEnd.
windowEnd ISO timestampExclusive end. Defaults to the request time.

Responses

200
Success

The fixed-window summary was calculated.

Schema
FeedbackSummary

Example Response

200 OK
json
{
  "metric": "initiative_direction",
  "subject": {
    "type": "initiative",
    "id": "initiative-uuid"
  },
  "window": {
    "start": "2026-07-01T00:00:00Z",
    "end": "2026-07-15T00:00:00Z",
    "days": 14
  },
  "summary": {
    "averageRating": 4.1,
    "ratingSum": 49,
    "ratedInteractionCount": 12,
    "eligibleInteractionCount": 15,
    "ratingCoverage": 0.8,
    "distribution": {
      "1": 0,
      "2": 1,
      "3": 2,
      "4": 4,
      "5": 5
    },
    "sourceCounts": {
      "study_completion": {
        "eligibleInteractionCount": 13,
        "ratedInteractionCount": 10
      },
      "live_interview": {
        "eligibleInteractionCount": 2,
        "ratedInteractionCount": 2
      }
    }
  },
  "previous": {
    "averageRating": 3.7,
    "ratedInteractionCount": 10
  },
  "studies": [
    {
      "id": "study-uuid",
      "publicId": "STUDY-8",
      "name": "Scheduler direction check",
      "averageRating": 4.1,
      "ratedInteractionCount": 12,
      "eligibleInteractionCount": 15
    }
  ],
  "recentComments": [
    {
      "responseId": "response-uuid",
      "rating": 5,
      "comment": "Keep this direction.",
      "submittedAt": "2026-07-14T10:00:00Z",
      "account": {
        "id": "account-uuid"
      },
      "study": {
        "id": "study-uuid",
        "publicId": "STUDY-8",
        "name": "Scheduler direction check"
      }
    }
  ]
}
Create a workspaceAsk supportDocumentation