---
title: "Feedback API reference"
canonical_url: https://zentrik.ai/docs/api/feedback
markdown_url: https://zentrik.ai/docs/api/feedback.md
last_reviewed: 2026-09-03
---

# Feedback API reference

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

- Human reference: https://zentrik.ai/docs/api/feedback
- Complete Markdown index: https://zentrik.ai/docs/api/index.md
- Base URL: `https://zentrik.ai/api`
- Authentication: `Authorization: Bearer YOUR_API_KEY`
- Shared pagination and rate limits: https://zentrik.ai/docs/api/index.md#shared-conventions

## GET /external/v1/studies/feedback — List feedback events

Operation ID: `list-study-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.

Required API key scopes: `studies:read`

### Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `metric` | string | No | Stable metric key. |
| `subjectType` | string | No | Immutable subject type. |
| `subjectId` | uuid | No | Immutable subject id. |
| `submittedFrom` | ISO timestamp | No | Inclusive rating event timestamp. |
| `submittedTo` | ISO timestamp | No | Exclusive rating event timestamp. |
| `initiativeId` | uuid | No | Current accepted Initiative context. |
| `ideaId` | uuid | No | Current accepted Idea context. |
| `accountId` | uuid | No | Exact Account filter. |
| `limit` | number | No | 1–100 results. |
| `offset` | number | No | Number of results to skip. |

### Responses

| Status | Meaning | Description | Schema |
| --- | --- | --- | --- |
| 200 | Success | Feedback events were retrieved. | Array<FeedbackEvent> |

### Example response

```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 /external/v1/feedback/summary — Summarize feedback

Operation ID: `summarize-feedback`

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.

Required API key scopes: `studies:read`

### Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `metric` | string | Yes | Stable metric key, such as initiative_direction. |
| `subjectType` | string | Yes | Subject type required by the metric. |
| `subjectId` | uuid | Yes | Immutable rating subject. |
| `windowStart` | ISO timestamp | No | Inclusive start. Defaults to 14 days before windowEnd. |
| `windowEnd` | ISO timestamp | No | Exclusive end. Defaults to the request time. |

### Responses

| Status | Meaning | Description | Schema |
| --- | --- | --- | --- |
| 200 | Success | The fixed-window summary was calculated. | FeedbackSummary |

### Example response

```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"
      }
    }
  ]
}
```