> ## Documentation Index > Fetch the complete documentation index at: https://developer.demand-iq.com/llms.txt > Use this file to discover all available pages before exploring further. # Get engagement summary > Returns seven engagement metrics for your organization: presentations sent, opened, average consumption, CTA clicks, questions asked, appointments booked, and contracts signed. Each metric includes a `percentChange` compared with the equal-length window immediately before the requested one, and every rate includes a `directional` flag. The response also includes three breakdowns for the requested window, without a `percentChange`: `funnel` (Created → Sent → Opened → Started → Completed for presentations created in the window), `visits` (visits per opened presentation), and `deliveryPath` (opened presentations that arrived without an email open or without an email send, plus opened presentations counted by the `utm_source` their link was shared with). Provide `since` and `until` together for a custom window, or omit both for the last 30 days ending now. If the window contains too many presentations, AI Presentations returns `422`. Narrow the window and retry. If only the prior comparison window is too large, the request still succeeds and every `percentChange` is `null`. Activity from a browser signed in to AI Presentations is left out of average consumption, CTA clicks, and questions asked, so previewing your own presentation link doesn't inflate them. That activity still counts toward `opened`. A teammate viewing a link on a device where they never signed in is counted as a prospect. Activity recorded before this exclusion shipped is counted as prospect activity. Pass `deckId` to limit the summary to one template. A `deckId` that doesn't belong to your organization returns a zero-valued summary rather than `404`. ## OpenAPI ````yaml /openapi.json get /api/engagement/summary openapi: 3.0.0 info: title: AI Presentations API version: 1.0.0 description: >- REST API for AI Presentations — an AI-powered presentation platform with narrated slides, live Q&A, and deck management. **Authentication**: Most endpoints require a session cookie obtained from `POST /api/auth/login`. Presentation playback endpoints (`/api/qa`, `/api/narration/*`) also accept a `presentationId` for unauthenticated viewer access. contact: name: Demand IQ url: https://demand-iq.com servers: - url: https://app.demand-iq.com description: Production - url: http://localhost:3000 description: Local development security: [] tags: - name: Decks description: Manage presentation decks - name: Slides description: Manage slides within a deck - name: FAQs description: Manage pre-built Q&A pairs - name: Branding description: Colors, logo, and call-to-action configuration - name: Q&A description: Live question answering and Q&A settings - name: Narration description: Text-to-speech synthesis - name: Presentations description: Create and manage personalized presentation instances - name: Generation description: AI-powered content generation from slide images - name: Images description: Image upload and management - name: Voices description: Available TTS voices - name: Utility description: Health check and diagnostics - name: Authentication description: Session-based login, logout, and identity - name: Company description: Organization contact info and knowledge base - name: Notifications description: Event subscriptions and delivery log - name: Contracts description: Contract template import and e-signature - name: Fonts description: Available Google Fonts for branding - name: Roof Measurements description: Request and track automated roof measurements - name: Actions description: Voice/text command detection for presentation control - name: Appointments description: Appointment scheduling for presentation viewers - name: Activity description: Recent presentation activity feed - name: Engagement description: Presentation engagement analytics - name: Onboarding description: >- Per-user product onboarding milestones (ENG-641). Milestone endpoints are idempotent and are called by the app UI — they should not be treated as tenant-integration surface. paths: /api/engagement/summary: get: tags: - Engagement summary: Get engagement summary description: >- Returns seven engagement metrics for your organization: presentations sent, opened, average consumption, CTA clicks, questions asked, appointments booked, and contracts signed. Each metric includes a `percentChange` compared with the equal-length window immediately before the requested one, and every rate includes a `directional` flag. The response also includes three breakdowns for the requested window, without a `percentChange`: `funnel` (Created → Sent → Opened → Started → Completed for presentations created in the window), `visits` (visits per opened presentation), and `deliveryPath` (opened presentations that arrived without an email open or without an email send, plus opened presentations counted by the `utm_source` their link was shared with). Provide `since` and `until` together for a custom window, or omit both for the last 30 days ending now. If the window contains too many presentations, AI Presentations returns `422`. Narrow the window and retry. If only the prior comparison window is too large, the request still succeeds and every `percentChange` is `null`. Activity from a browser signed in to AI Presentations is left out of average consumption, CTA clicks, and questions asked, so previewing your own presentation link doesn't inflate them. That activity still counts toward `opened`. A teammate viewing a link on a device where they never signed in is counted as a prospect. Activity recorded before this exclusion shipped is counted as prospect activity. Pass `deckId` to limit the summary to one template. A `deckId` that doesn't belong to your organization returns a zero-valued summary rather than `404`. parameters: - in: query name: since required: false schema: type: string format: date-time example: '2026-09-01T00:00:00Z' description: >- Start of the window (inclusive), as an RFC 3339 timestamp. Timezone offsets are accepted. Provide with `until`, or omit both for the last 30 days. - in: query name: until required: false schema: type: string format: date-time example: '2026-10-01T00:00:00Z' description: >- End of the window (exclusive), as an RFC 3339 timestamp. Must be after `since`. Provide with `since`, or omit both for the last 30 days. - in: query name: deckId required: false schema: type: string format: uuid description: >- Limit the summary to one template. An empty value is treated as absent. responses: '200': description: Engagement summary content: application/json: schema: $ref: '#/components/schemas/EngagementSummary' '400': description: >- Invalid query parameters, `since` or `until` provided without the other, or `since` not before `until` content: application/json: schema: $ref: '#/components/schemas/Error' '401': description: Not authenticated content: application/json: schema: $ref: '#/components/schemas/Error' '422': description: >- The window contains too many presentations. Narrow the window and retry. content: application/json: schema: $ref: '#/components/schemas/Error' '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/Error' security: - bearerAuth: [] - sessionCookie: [] components: schemas: EngagementSummary: type: object description: >- The seven engagement metrics for your organization over the requested window, plus the engagement funnel, visits per opened presentation, and delivery path counts. properties: window: type: object description: >- The window the metrics cover: the requested `since`/`until`, or the last 30 days ending at request time. properties: from: type: string format: date-time example: '2026-09-01T00:00:00.000Z' until: type: string format: date-time example: '2026-10-01T00:00:00.000Z' required: - from - until deckId: type: string format: uuid nullable: true description: >- The template filter applied, or `null` when the summary covers all templates. presentationsSent: allOf: - $ref: '#/components/schemas/EngagementCountMetric' description: Presentations successfully sent in the window. opened: allOf: - $ref: '#/components/schemas/EngagementRateMetric' description: >- Presentations whose viewer page was loaded at least once. This is not the email-open signal. Includes opens by a signed-in member of your organization, so previewing your own presentation link counts as an open. `rate.denominator` is the number of presentations created in the window. avgConsumption: allOf: - $ref: '#/components/schemas/EngagementRateMetric' description: >- Slides consumed out of the total slides in opened presentations created in the window. Unopened presentations are excluded, so this reflects viewing behavior rather than open rate. Slides viewed by a signed-in member of your organization are excluded. ctaClicks: allOf: - $ref: '#/components/schemas/EngagementRateMetric' description: >- Call-to-action clicks. `rate.denominator` excludes presentations from templates with no call to action configured. Clicks by a signed-in member of your organization are excluded. questionsAsked: type: object description: >- Questions viewers asked during presentations. Questions asked by a signed-in member of your organization are excluded. properties: count: type: integer example: 37 percentChange: type: number nullable: true example: 0.12 description: >- Relative change in `count` compared with the prior window. Follows the same rules as `EngagementCountMetric.percentChange`. escalated: type: integer example: 4 description: >- Questions the AI could not answer or answered with low confidence. A breakdown of `count`, so it has no `percentChange` of its own. required: - count - percentChange - escalated appointmentsBooked: allOf: - $ref: '#/components/schemas/EngagementCountMetric' description: Appointments booked from presentations. contractsSigned: allOf: - $ref: '#/components/schemas/EngagementCountMetric' description: Contracts signed from presentations. funnel: allOf: - $ref: '#/components/schemas/EngagementFunnel' description: >- The Created → Completed funnel for presentations created in the window. visits: type: object description: >- Visits per opened presentation. AI Presentations splits a presentation's opens into separate visits wherever 30 minutes pass between opens. Each opened presentation counts as at least one visit. Treat these values as a lower bound, because opens are rate-limited. properties: opened: type: integer example: 82 description: Opened presentations the averages are computed over. avg: type: number nullable: true example: 1.6 description: Mean visits per opened presentation. `null` when `opened` is 0. median: type: number nullable: true example: 1 description: >- Median visits per opened presentation. `null` when `opened` is 0. required: - opened - avg - median deliveryPath: type: object description: How opened presentations reached the viewer. properties: viewedWithoutEmailOpen: type: integer example: 11 description: >- Opened presentations that were sent and delivered by email, with no email open by a person recorded. viewedWithoutSend: type: integer example: 7 description: >- Opened presentations that were never sent by email, for example because the link was copied and shared directly. byOpenSource: type: object additionalProperties: type: integer example: email: 42 journeys: 9 none: 15 description: >- Opened presentations counted by the `utm_source` on the link of their first homeowner open. `email` means AI Presentations sent the link. Any other key is the value the system that shared the link declared. `none` counts opens with no source, including every open recorded before this breakdown was added. required: - viewedWithoutEmailOpen - viewedWithoutSend - byOpenSource required: - window - deckId - presentationsSent - opened - avgConsumption - ctaClicks - questionsAsked - appointmentsBooked - contractsSigned - funnel - visits - deliveryPath Error: type: object properties: error: type: string required: - error EngagementCountMetric: type: object properties: count: type: integer example: 120 percentChange: type: number nullable: true example: -0.08 description: >- Relative change compared with the equal-length window immediately before the requested one. `0.15` means +15%. `null` when the prior window could not be loaded because it exceeded the size limit, or when the prior count was 0 and the current count is not. A prior count of 0 and a current count of 0 returns `0`. required: - count - percentChange EngagementRateMetric: type: object properties: rate: $ref: '#/components/schemas/EngagementRate' percentChange: type: number nullable: true example: 0.15 description: >- Relative change in the ratio (numerator / denominator) compared with the equal-length window immediately before the requested one. `0.15` means +15%. `null` when the prior window could not be loaded because it exceeded the size limit, when either window has a denominator of 0, or when the prior ratio was 0 and the current one is not. A prior ratio of 0 and a current ratio of 0 returns `0`. directional: type: boolean example: true description: >- `true` when the metric varies too much between companies at current volume to trend reliably. Display it as a directional indicator rather than a trend. required: - rate - percentChange - directional EngagementFunnel: type: object description: >- The Created → Sent → Opened → Started → Completed funnel for presentations created in the window. Each step reports a count, a rate over the previous step, and a rate over Created. `completed.overCreated` is the headline conversion rate. properties: created: type: integer example: 120 description: Presentations created in the window. sent: allOf: - $ref: '#/components/schemas/EngagementFunnelStep' description: >- Presentations with at least one accepted email send. `overPrevious` is over Created. opened: allOf: - $ref: '#/components/schemas/EngagementFunnelStep' description: >- Presentations whose viewer page loaded at least once. A presentation opened from a copied link counts toward `count` but not toward `overPrevious`, which is over Sent. started: allOf: - $ref: '#/components/schemas/EngagementFunnelStep' description: >- Presentations where the viewer pressed Start on the intro screen. Only presentations opened on an intro count. `overPrevious` is over opened presentations that showed an intro. An opened presentation with no recorded start that was first viewed before AI Presentations began recording starts counts as `unknown`. completed: allOf: - $ref: '#/components/schemas/EngagementFunnelStep' description: >- Presentations whose viewer reached the last slide. `overPrevious` is over Started. noStartStep: type: integer example: 14 description: >- Opened presentations that had no intro screen, so the viewer had no Start to press. These are left out of `started` rather than counted as a 0% start rate. required: - created - sent - opened - started - completed - noStartStep EngagementRate: type: object description: >- A rate returned as its raw numerator and denominator rather than a pre-computed percentage, so you can hide rates whose denominator is too small to be meaningful. `unknown` counts items whose underlying data is no longer available, which is distinct from a real 0. properties: numerator: type: integer example: 42 denominator: type: integer example: 120 unknown: type: integer example: 0 required: - numerator - denominator - unknown EngagementFunnelStep: type: object description: One step of the engagement funnel. properties: count: type: integer example: 96 description: Presentations created in the window that reached this step. overPrevious: allOf: - $ref: '#/components/schemas/EngagementRate' description: >- Presentations that reached both this step and the previous one, over the presentations that reached the previous step. Because both steps are required, this rate never exceeds 100%. overCreated: allOf: - $ref: '#/components/schemas/EngagementRate' description: >- Presentations that reached this step, over the presentations created in the window. required: - count - overPrevious - overCreated securitySchemes: bearerAuth: type: http scheme: bearer description: >- A Demand IQ API key or service token, passed in the `Authorization: Bearer` header. sessionCookie: type: apiKey in: cookie name: session description: Session cookie obtained from `POST /api/auth/login`. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.