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

# 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 optional post-study ratings and participant identity from Study completions and Live Interview Pulse submissions. Responses without a rating are omitted. Use GET /external/v1/studies/:id/responses for research answers, including responses that skipped the rating. Existing keys with studies:read receive the same name, email, and company display as the Study UI automatically; no new key, additional scope, or include flag is required. participant is null when identity is unknown. Saved identity is also available on historical responses. submittedAt is the rating event time; source identifies the submission path. The feedback subject is separate from the Study’s current accepted context. For a stable synchronization run, hold submittedTo fixed, follow X-Has-More, and advance offset by X-Limit. submittedFrom is inclusive; submittedTo is exclusive.

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 | Each participant contains nullable id, name, email, accountId, accountName, and account, plus type: public_user, portal_user, or discovery_user. id identifies a linked portal or discovery user; it is not a People/Contact ID. Participants known only through saved response details have id: null even when their name and email are available. The outer id is the group Pulse submission ID when present, otherwise the response ID. Group Pulse identity and account attribution come from the attendee’s saved submission, without falling back to the interview owner. For other feedback, account reflects the response’s linked Account. accountName falls back to captured company text when no Account is linked; account and accountId then remain null. Research answers, notes, transcripts, and clicks are excluded. | 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",
    "participant": {
      "id": null,
      "name": "Dana Ruiz",
      "email": "dana@example.com",
      "type": "public_user",
      "accountId": "account-uuid",
      "accountName": "Northstar Dental",
      "account": {
        "id": "account-uuid",
        "name": "Northstar Dental"
      }
    },
    "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"
      }
    }
  ]
}
```