> ## Documentation Index
> Fetch the complete documentation index at: https://docs.craftkit.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Get engagement

> GET /v1/renders/:id/engagement — aggregate engagement counts plus the most recent events for a render.

<Info>**GET** `https://api.craftkit.dev/v1/renders/:id/engagement`</Info>

Returns per-type engagement counts, a `linkOpens` tally, the grand total, and up to the 25 most
recent events (newest first) for a single render. Scoped to your API key's project.

## Authorization

<ParamField header="Authorization" type="string" required>
  `Bearer ck_live_…` — a project API key.
</ParamField>

## Path parameters

<ParamField path="id" type="string" required>The render id. Must belong to this key's project.</ParamField>

## Response

`200` with the engagement summary.

<ResponseField name="counts" type="object">
  Per-type event counts. Always contains all seven keys, zero-filled when there is no activity.

  <Expandable title="counts">
    <ResponseField name="viewed" type="number">Document opens.</ResponseField>
    <ResponseField name="downloaded" type="number">PDF downloads.</ResponseField>
    <ResponseField name="printed" type="number">Print actions.</ResponseField>
    <ResponseField name="email_opened" type="number">Tracking-pixel opens on a sent email.</ResponseField>
    <ResponseField name="email_sent" type="number">Emails dispatched (partner audit).</ResponseField>
    <ResponseField name="share_created" type="number">Share links minted (partner audit).</ResponseField>
    <ResponseField name="share_revoked" type="number">Share links revoked (partner audit).</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="linkOpens" type="number">
  Subset of `viewed` events that came through a shared link (`shareId` is non-null). Separates
  link traffic from in-dashboard views.
</ResponseField>

<ResponseField name="total" type="number">Sum of all `counts`.</ResponseField>

<ResponseField name="recent" type="object[]">
  Up to 25 most recent events, newest first.

  <Expandable title="event">
    <ResponseField name="id" type="string">Event id.</ResponseField>

    <ResponseField name="eventType" type="string">
      One of `viewed`, `downloaded`, `printed`, `email_opened`, `email_sent`, `share_created`,
      `share_revoked`.
    </ResponseField>

    <ResponseField name="actorKind" type="string">
      `recipient` (the share recipient), `partner` (you), or `system` (server-side automation).
    </ResponseField>

    <ResponseField name="shareId" type="string | null">Originating share link, when present.</ResponseField>
    <ResponseField name="sourceIp" type="string | null">Best-effort client IP.</ResponseField>
    <ResponseField name="userAgent" type="string | null">Client user-agent string.</ResponseField>
    <ResponseField name="metadata" type="object | null">Free-form bag stored with the event.</ResponseField>
    <ResponseField name="createdAt" type="string">ISO-8601 timestamp.</ResponseField>
  </Expandable>
</ResponseField>

## Errors

| Status | code           | Meaning                                       |
| ------ | -------------- | --------------------------------------------- |
| 401    | `unauthorized` | Missing, invalid, or revoked key.             |
| 403    | `forbidden`    | Key's project no longer exists.               |
| 404    | `not_found`    | No render with that id in this key's project. |

```bash cURL theme={null}
curl https://api.craftkit.dev/v1/renders/$RENDER_ID/engagement \
  -H "Authorization: Bearer $CRAFTKIT_API_KEY"
```

```json 200 theme={null}
{
  "counts": {
    "viewed": 12,
    "downloaded": 3,
    "printed": 1,
    "email_opened": 4,
    "email_sent": 2,
    "share_created": 1,
    "share_revoked": 0
  },
  "linkOpens": 8,
  "total": 23,
  "recent": [
    {
      "id": "…",
      "eventType": "viewed",
      "actorKind": "recipient",
      "shareId": "…",
      "sourceIp": "203.0.113.7",
      "userAgent": "Mozilla/5.0 …",
      "metadata": null,
      "createdAt": "2026-05-03T10:20:00.000Z"
    }
  ]
}
```