---
name: clinic-activity-hub
description: |
  Query canonical Data Proxy cluster lifecycle events for backup, scaling, maintenance, CDC, and GitOps activity.
---

# Cluster events (Activity Hub) API

Use the canonical org/cluster resource route:

```text
GET /data-proxy/api/v1/orgs/{orgID}/clusters/{clusterID}/activities
```

`{orgID}` is the TiDB Cloud/DBAAS org ID. Canonical cluster metadata exposes it as `orgId`; in a legacy Dashboard response it is `tenantID`, not Dashboard `orgID`.

## Request

| Parameter | Required | Description |
|-----------|----------|-------------|
| `begin_ts` | Yes | Start time, Unix seconds |
| `end_ts` | Yes | End time, Unix seconds |
| `limit` | No | Result limit; helper default is `100` |
| `cursor` | No | Cursor returned by the previous response; send it as a query parameter |
| `catalog` | No | Event catalog filter, for example `gitops` |
| `type` | No | Event type filter |
| `name` | No | Event name filter, for example `backupcluster` |
| `severity` | No | Severity filter |

The successful response retains `{activities,partial,cursor}`. When `cursor` is non-empty, send it unchanged in the next request's query string.

```bash
source scripts/clinic-shell.sh
get_clinic_auth

CURSOR=""
clinic_get_activities \
  "$DBAAS_ORG_ID" "$CLUSTER_ID" "$BEGIN_TS" "$END_TS" \
  100 "$CURSOR" "" "" "" ""
```

Direct request:

```bash
curl --fail-with-body --get \
  -H "Authorization: Bearer ${CLINIC_API_KEY}" \
  --data-urlencode "begin_ts=${BEGIN_TS}" \
  --data-urlencode "end_ts=${END_TS}" \
  --data-urlencode 'limit=20' \
  "${CLINIC_ENDPOINT}/data-proxy/api/v1/orgs/${DBAAS_ORG_ID}/clusters/${CLUSTER_ID}/activities"
```

## Common event families

| Scope | Examples |
|-------|----------|
| Dedicated/Premium | Create, scale, maintenance, pause/resume, backup/restore, import, changefeed operations, insufficient VM resources |
| Starter/Essential | Create, spending-limit or capacity changes, resource limitation, branch/public-endpoint operations, import/export, backup/restore |
| GitOps (`catalog=gitops`) | `upgrade`, `config-change`, `patch`, `scale`, `pause`, `resume`, `restore`, `import`, and `backup`, commonly with `:start`/`:finish` suffixes |

## Legacy compatibility

The existing path remains available for old consumers:

```text
GET /clinic/api/v1/activityhub/applications/{clinicInternalOrgID}/targets/{clusterID}/activities
```

It uses Dashboard `orgID` as `{clinicInternalOrgID}` and sends pagination `cursor` in a request header. Use `clinic_legacy_get_activities` only when maintaining that contract; canonical `clinic_get_activities` uses DBAAS org ID and query-based cursor pagination.