> ## Documentation Index > Fetch the complete documentation index at: https://docs.brudcast.com/llms.txt > Use this file to discover all available pages before exploring further. # Get the engagement report > Returns the open, click and click-to-open rates with their trends, the daily rates trend, the best send times heatmap, the device breakdown and the top clicked links. Every figure is scoped to email, the only channel that emits an open event. The click-through rate on each link divides its unique clicks by the all-time delivered total across every campaign, so it is not scoped to the requested range. Requires the `analytics:read` scope. ## OpenAPI ````yaml /api-reference/openapi.json get /api/v1/user/reports/engagement openapi: 3.0.0 info: title: Brudcast API version: 1.0.0 servers: - url: https://core-service.prod.brudcast.com description: Production security: [] tags: - name: Analytics x-displayName: Analytics - name: Campaigns x-displayName: Campaigns - name: Contacts x-displayName: Contacts - name: Mailboxes x-displayName: Mailboxes - name: Messages x-displayName: Messages - name: Sender Identities x-displayName: Sender Identities - name: Sending Domains x-displayName: Sending Domains - name: Templates x-displayName: Templates - name: Webhooks x-displayName: Webhooks paths: /api/v1/user/reports/engagement: get: tags: - Analytics summary: Get the engagement report description: >- Returns the open, click and click-to-open rates with their trends, the daily rates trend, the best send times heatmap, the device breakdown and the top clicked links. Every figure is scoped to email, the only channel that emits an open event. The click-through rate on each link divides its unique clicks by the all-time delivered total across every campaign, so it is not scoped to the requested range. Requires the `analytics:read` scope. parameters: - in: header name: X-Organization-Id required: false description: >- Required when authenticating with an access token. Optional with an API key, whose own organization binding is authoritative; a value contradicting it is refused with 403. schema: type: string format: uuid - in: query name: from required: false schema: type: string - in: query name: to required: false schema: type: string responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/ReportEngagementResponse' '401': description: The credential is missing, malformed, revoked or expired content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: >- The key lacks the scope the endpoint requires, or the organization does not match the credential content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '422': description: The payload or query string failed validation content: application/json: schema: $ref: '#/components/schemas/ValidationErrorResponse' '429': description: >- Rate limit exceeded; retry after the number of seconds in `retryAfter` content: application/json: schema: $ref: '#/components/schemas/RateLimitErrorResponse' security: - apiKey: [] - apiKeyBearer: [] components: schemas: ReportEngagementResponse: type: object properties: success: type: boolean example: true message: type: string data: $ref: '#/components/schemas/ReportEngagement' required: - success - message - data ErrorResponse: type: object properties: success: type: boolean example: false message: type: string example: Resource not found code: type: string enum: - E_VALIDATION_ERROR - E_UNAUTHORIZED_ACCESS - E_UNAUTHORIZED - E_FORBIDDEN - E_INSUFFICIENT_SCOPE - E_ROW_NOT_FOUND - E_TOO_MANY_REQUESTS - E_BUSINESS_RULE_VIOLATION - E_CAMPAIGN_NOT_SENDABLE - INSUFFICIENT_CREDITS - SUBSCRIPTION_REQUIRED example: E_ROW_NOT_FOUND required: - success - message - code ValidationErrorResponse: type: object properties: success: type: boolean example: false message: type: string example: The payload is invalid code: type: string enum: - E_VALIDATION_ERROR - E_UNAUTHORIZED_ACCESS - E_UNAUTHORIZED - E_FORBIDDEN - E_INSUFFICIENT_SCOPE - E_ROW_NOT_FOUND - E_TOO_MANY_REQUESTS - E_BUSINESS_RULE_VIOLATION - E_CAMPAIGN_NOT_SENDABLE - INSUFFICIENT_CREDITS - SUBSCRIPTION_REQUIRED example: E_VALIDATION_ERROR errors: type: array items: $ref: '#/components/schemas/ValidationErrorItem' required: - success - message - code - errors RateLimitErrorResponse: type: object properties: success: type: boolean example: false message: type: string example: Too many requests code: type: string enum: - E_VALIDATION_ERROR - E_UNAUTHORIZED_ACCESS - E_UNAUTHORIZED - E_FORBIDDEN - E_INSUFFICIENT_SCOPE - E_ROW_NOT_FOUND - E_TOO_MANY_REQUESTS - E_BUSINESS_RULE_VIOLATION - E_CAMPAIGN_NOT_SENDABLE - INSUFFICIENT_CREDITS - SUBSCRIPTION_REQUIRED example: E_TOO_MANY_REQUESTS retryAfter: type: number example: 60 required: - success - message - code - retryAfter ReportEngagement: type: object properties: kpis: $ref: '#/components/schemas/ReportEngagementKpis' ratesTrend: type: array items: $ref: '#/components/schemas/ReportRatesPoint' bestSendTimes: type: array items: $ref: '#/components/schemas/ReportSendTimeRow' deviceBreakdown: type: array items: $ref: '#/components/schemas/ReportDeviceBreakdownItem' topClickedLinks: type: array items: $ref: '#/components/schemas/ReportTopClickedLink' required: - kpis - ratesTrend - bestSendTimes - deviceBreakdown - topClickedLinks ValidationErrorItem: type: object properties: field: type: string example: emailAddress rule: type: string example: email message: type: string example: The emailAddress field must be a valid email address required: - field - rule - message ReportEngagementKpis: type: object properties: avgOpenRate: type: number example: 41.3 avgClickRate: type: number example: 8.7 ctor: type: number example: 21.1 description: Click-to-open rate, derived from raw rather than unique counts trends: $ref: '#/components/schemas/ReportEngagementTrends' required: - avgOpenRate - avgClickRate - ctor - trends ReportRatesPoint: type: object properties: date: type: string format: date example: '2026-07-01T00:00:00.000Z' openRate: type: number clickRate: type: number required: - date - openRate - clickRate ReportSendTimeRow: type: object properties: day: type: string example: Monday hours: type: array items: type: number description: >- Twenty-four counts, one per hour of the day, starting at midnight UTC required: - day - hours ReportDeviceBreakdownItem: type: object properties: name: type: string example: mobile value: type: number example: 58.2 description: Share of opens, as a percentage required: - name - value ReportTopClickedLink: type: object properties: url: type: string example: https://example.com/pricing clicks: type: number uniqueClicks: type: number ctr: type: number description: >- Unique clicks over the all-time delivered total across every campaign, so it is not scoped to the requested range required: - url - clicks - uniqueClicks - ctr ReportEngagementTrends: type: object properties: opened: $ref: '#/components/schemas/ReportTrend' clicked: $ref: '#/components/schemas/ReportTrend' required: - opened - clicked ReportTrend: type: object properties: direction: type: string enum: - up - down - flat - new description: How the figure moved against the preceding period of equal length value: type: number example: 12.5 description: Magnitude of the change, as a percentage required: - direction - value securitySchemes: apiKey: type: apiKey in: header name: X-API-Key description: >- An organization API key, prefixed `bk_live_`. Takes precedence over `Authorization` when both are sent. The key is bound to one organization, and the scopes it was issued with are enforced per endpoint. apiKeyBearer: type: http scheme: bearer bearerFormat: bk_live_... description: >- The same organization API key sent as `Authorization: Bearer bk_live_...`. Accepted only when the value begins with `bk_` and no `X-API-Key` header is present. ````