> For the complete documentation index, see [llms.txt](https://v2.dataos.info/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://v2.dataos.info/references/interfaces/apis/data-product-apis/api-reference/engagement.md).

# Engagement

Technical contract for working with consumer engagement data.

Engagement APIs let users subscribe to a Data Product and read the operational events that affect it. Caller identity comes from the Bearer token.

## Followers

Subscribe to a Data Product, see who is following it, and track adoption over time.

**Base path:** `/api/v1/followers`

Following is idempotent: following an already-followed product returns the existing active record instead of creating a duplicate.

***

### Follow this Data Product

**API endpoint:** POST /api/v1/followers

**Description:** Follow the current Data Product as the authenticated user. Optional metadata can record context such as the user's team or intended use.

**Request body:**

```json
{
  "metadata": {
    "team": "sales-analytics",
    "use_case": "executive-dashboard"
  }
}
```

**cURL:**

```bash
curl -s -X POST https://$BASE_URL/api/v1/followers \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "metadata": {
      "team": "sales-analytics",
      "use_case": "executive-dashboard"
    }
  }'
```

**Returns:** `200 OK` with the follower's `user_id`, active state, follow timestamp, and stored metadata.

***

### List active followers

**API endpoint:** GET /api/v1/followers

**Description:** Returns active followers ordered by follow date (newest first).

**Query parameters:**

| Parameter | Default | Description                           |
| --------- | ------- | ------------------------------------- |
| `limit`   | `50`    | Followers to return; range `1`–`100`. |
| `offset`  | `0`     | Followers to skip.                    |

**cURL:**

```bash
curl -s "https://$BASE_URL/api/v1/followers?limit=50&offset=0" \
  -H "Authorization: Bearer $TOKEN"
```

**Returns:** `200 OK` with `followers`, `total`, and pagination metadata.

***

### My follow status

**API endpoint:** GET /api/v1/followers/me

**Description:** Returns whether the authenticated user is currently following, when they followed, and any metadata attached at follow time.

**cURL:**

```bash
curl -s https://$BASE_URL/api/v1/followers/me \
  -H "Authorization: Bearer $TOKEN"
```

**Example response:**

```json
{
  "is_follower": true,
  "user_id": "sales-analyst",
  "active": true,
  "followed_at": 1789401600000,
  "metadata": {
    "team": "sales-analytics"
  }
}
```

**Returns:** `200 OK` with `is_follower`, `user_id`, active state, follow timestamp, and metadata. When the user has never followed or has unfollowed, the endpoint still returns `200 OK` with `is_follower: false`.

***

### Unfollow this Data Product

**API endpoint:** DELETE /api/v1/followers/me

**Description:** Stop following the Data Product as the authenticated user.

**cURL:**

```bash
curl -s -X DELETE https://$BASE_URL/api/v1/followers/me \
  -H "Authorization: Bearer $TOKEN"
```

**Returns:** `200 OK` with the updated inactive follower record. Returns `404 Not Found` when the user has never followed this product.

***

### Follower analytics

**API endpoint:** GET /api/v1/followers/analytics

**Description:** Without `granularity`, returns only the current active follower count. With `granularity` (`day`, `week`, or `month`), returns a time series showing follower counts per period.

**Query parameters:**

| Parameter     | Default | Description                                                                     |
| ------------- | ------- | ------------------------------------------------------------------------------- |
| `granularity` | None    | Bucket size for a time series. Omit it to return the current active count only. |
| `offset`      | `0`     | Buckets to skip, counting back from the present.                                |
| `limit`       | `30`    | Number of buckets to return when `granularity` is set.                          |

**cURL:**

```bash
# Current total only
curl -s https://$BASE_URL/api/v1/followers/analytics \
  -H "Authorization: Bearer $TOKEN"

# Monthly trend
curl -s "https://$BASE_URL/api/v1/followers/analytics?granularity=month&limit=6" \
  -H "Authorization: Bearer $TOKEN"
```

**Returns:** `200 OK` with `total_active`. A granular request also returns a time series. Returns `400 Bad Request` for invalid analytics parameters.

***

## Notifications

Notifications form a chronological event feed for plans, runs, audits, and data-quality execution. Use their run and plan links to investigate an event.

***

### List notifications

**API endpoint:** GET /api/v1/notifications

**Description:** Returns notifications ordered newest first. Filter by run or plan ID, or event type. `run_id` takes precedence when both IDs are set. Events include: `apply_start`, `apply_end`, `run_start`, `run_end`, `run_failure`, `audit_failure`, `dq_start`, `dq_end`, and more.

**Query parameters:**

| Parameter  | Default | Description                                                                                       |
| ---------- | ------- | ------------------------------------------------------------------------------------------------- |
| `run_id`   | None    | Filter by run ID. Takes precedence over `plan_id` when both are set.                              |
| `plan_id`  | None    | Filter by plan ID.                                                                                |
| `events`   | None    | Filter by one or more event names. Repeat this parameter as needed.                               |
| `start_ts` | None    | Include notifications with `created_ts` greater than or equal to this Unix timestamp, in seconds. |
| `end_ts`   | None    | Include notifications with `created_ts` less than or equal to this Unix timestamp, in seconds.    |
| `limit`    | `50`    | Notifications to return; range `1`–`100`.                                                         |
| `offset`   | `0`     | Notifications to skip.                                                                            |

**cURL:**

```bash
curl -s "https://$BASE_URL/api/v1/notifications?run_id=run_789&limit=50" \
  -H "Authorization: Bearer $TOKEN"

# Repeat events to select multiple event types
curl -s "https://$BASE_URL/api/v1/notifications?events=run_failure&events=audit_failure" \
  -H "Authorization: Bearer $TOKEN"
```

**Returns:** `200 OK` with the environment, notifications, total, pagination, and links to associated runs or plans when available.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://v2.dataos.info/references/interfaces/apis/data-product-apis/api-reference/engagement.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
