Engagement Configs

The engagement config is the engagement pillar of an Activity Generation Config. It buckets active users into ordered engagement levels (e.g. casual, core, power) based on how much they use the product within a rolling window.

This resource is read-only: only GET (list) and GET /:id exist. Engagement configs are created and edited only through the AGC flow — see Create AGC and Update lifecycle.

The engaged latch is minLifetimeActionsForEngaged — the minimum number of lifetime actions a user must accumulate before they are considered engaged at all (platform default 1). There is no daysToChurned field. daysToChurned (and its snake_case form days_to_churned) does not exist on this pillar — decay and winback are handled by the resurrection pillar, not here.

Response fields

Field	Type	Description
`id`	string (uuid)	Engagement config id.
`name`	string	Display name.
`description`	string \| null	Optional description.
`sourceTable`	string	Table the engagement data is read from.
`sourceColumns`	string[] \| null	Columns used for the aggregation.
`dateColumn`	string	Column carrying the event timestamp.
`activityGenerationConfigId`	string (uuid)	Owning AGC (NOT NULL, 1:1).
`engagementWindowDays`	integer	Rolling window (days) over which engagement is measured.
`minLifetimeActionsForEngaged`	integer	Minimum lifetime actions to be considered engaged. Platform default `1`.
`countingMethod`	`event_ids` \| `active_days` \| `active_weeks`	What is counted within the window.
`isActive`	boolean	Whether the config is active.
`updatedBy`	string \| null	User id of the last editor.
`createdAt`	string (ISO 8601)	Creation timestamp.
`updatedAt`	string (ISO 8601)	Last update timestamp.
`engagementLevels`	array	Ordered engagement level buckets (see below).

`engagementLevel`

Field	Type	Description
`id`	string (uuid)	Level id.
`engagementConfigId`	string (uuid)	Owning engagement config.
`statusCode`	string	Retention status code emitted by this level (e.g. `habit`).
`userRetentionStatusConfigId`	string (uuid)	Resolved tenant retention status config.
`label`	string	Display label for the level.
`minThreshold`	integer	Inclusive lower bound (counted units) for this level.
`maxThreshold`	integer \| null	Inclusive upper bound; `null` means open-ended (top level).
`order`	integer	Ordering of the level within the ladder.
`isActive`	boolean	Whether the level is active.
`createdAt`	string (ISO 8601)	Creation timestamp.
`updatedAt`	string (ISO 8601)	Last update timestamp.

GET /api/engagement-configs

List the engagement configs of the tenant.

Auth: Required — lifecycle-config:view permission

Example

curl https://api.reten.ai/api/engagement-configs \
  -H "Authorization: Bearer <token>" \
  -H "x-tenant-id: <tenant-id>" \
  -H "x-project-id: <project-id>"

import axios from 'axios';

const response = await axios.get('https://api.reten.ai/api/engagement-configs', {
  headers: {
    Authorization: 'Bearer <token>',
    'x-tenant-id': '<tenant-id>',
    'x-project-id': '<project-id>',
  },
});

const engagementConfigs = response.data;

Response `200 OK`

[
  {
    "id": "e1111111-1111-1111-1111-111111111111",
    "name": "Engagement",
    "description": "Active-day engagement ladder",
    "sourceTable": "events",
    "sourceColumns": ["user_id", "event_name"],
    "dateColumn": "occurred_at",
    "activityGenerationConfigId": "agc11111-1111-1111-1111-111111111111",
    "engagementWindowDays": 28,
    "minLifetimeActionsForEngaged": 1,
    "countingMethod": "active_days",
    "isActive": true,
    "updatedBy": "u1111111-1111-1111-1111-111111111111",
    "createdAt": "2026-01-15T10:00:00.000Z",
    "updatedAt": "2026-01-20T12:30:00.000Z",
    "engagementLevels": [
      {
        "id": "l1111111-1111-1111-1111-111111111111",
        "engagementConfigId": "e1111111-1111-1111-1111-111111111111",
        "statusCode": "casual",
        "userRetentionStatusConfigId": "rs333333-3333-3333-3333-333333333333",
        "label": "Ocasional",
        "minThreshold": 1,
        "maxThreshold": 3,
        "order": 0,
        "isActive": true,
        "createdAt": "2026-01-15T10:00:00.000Z",
        "updatedAt": "2026-01-15T10:00:00.000Z"
      },
      {
        "id": "l2222222-2222-2222-2222-222222222222",
        "engagementConfigId": "e1111111-1111-1111-1111-111111111111",
        "statusCode": "habit",
        "userRetentionStatusConfigId": "rs444444-4444-4444-4444-444444444444",
        "label": "En hábito",
        "minThreshold": 8,
        "maxThreshold": null,
        "order": 1,
        "isActive": true,
        "createdAt": "2026-01-15T10:00:00.000Z",
        "updatedAt": "2026-01-15T10:00:00.000Z"
      }
    ]
  }
]

GET /api/engagement-configs/:id

Read a single engagement config with its engagement levels.

Auth: Required — lifecycle-config:view permission

Example

curl https://api.reten.ai/api/engagement-configs/e1111111-1111-1111-1111-111111111111 \
  -H "Authorization: Bearer <token>" \
  -H "x-tenant-id: <tenant-id>" \
  -H "x-project-id: <project-id>"

import axios from 'axios';

const response = await axios.get(
  'https://api.reten.ai/api/engagement-configs/e1111111-1111-1111-1111-111111111111',
  {
    headers: {
      Authorization: 'Bearer <token>',
      'x-tenant-id': '<tenant-id>',
      'x-project-id': '<project-id>',
    },
  }
);

const engagementConfig = response.data;

Response `200 OK`

{
  "id": "e1111111-1111-1111-1111-111111111111",
  "name": "Engagement",
  "description": "Active-day engagement ladder",
  "sourceTable": "events",
  "sourceColumns": ["user_id", "event_name"],
  "dateColumn": "occurred_at",
  "activityGenerationConfigId": "agc11111-1111-1111-1111-111111111111",
  "engagementWindowDays": 28,
  "minLifetimeActionsForEngaged": 1,
  "countingMethod": "active_days",
  "isActive": true,
  "updatedBy": "u1111111-1111-1111-1111-111111111111",
  "createdAt": "2026-01-15T10:00:00.000Z",
  "updatedAt": "2026-01-20T12:30:00.000Z",
  "engagementLevels": [
    {
      "id": "l2222222-2222-2222-2222-222222222222",
      "engagementConfigId": "e1111111-1111-1111-1111-111111111111",
      "statusCode": "habit",
      "userRetentionStatusConfigId": "rs444444-4444-4444-4444-444444444444",
      "label": "En hábito",
      "minThreshold": 8,
      "maxThreshold": null,
      "order": 1,
      "isActive": true,
      "createdAt": "2026-01-15T10:00:00.000Z",
      "updatedAt": "2026-01-15T10:00:00.000Z"
    }
  ]
}