---
name: tidb-tools-cdc
description: |
  List TiCDC changefeeds, map display names to business and kernel IDs,
  and inspect non-sensitive configuration. Works on all cluster types.
---

# Available Actions

## List Changefeeds

List TiCDC changefeeds for a cluster.

API Path: `/{cluster_id}/tidbtools/changefeeds`

Method: `GET`

This endpoint has no pagination parameters. The backend requests the first
upstream page with a fixed limit of 1000 business changefeeds, enriches each row
with kernel metadata when available, and sorts the result by `created_at`
descending. `total` is the number of returned rows, not a dataset-wide count.

### Response (`ListChangefeedsResp`)

| Field | Type |
|---|---|
| `items` | `ChangefeedSummary[]` |
| `total` | integer |

`ChangefeedSummary` fields:

| Field | Type | Enums |
|---|---|---|
| `id` | string | |
| `display_name` | string | |
| `status` | string | `creating`, `normal`, `starting`, `stopping`, `stopped`, `scaling`, `editing`, `warning`, `error`, `failed`, `deleting`, `deleted`, `finished` |

The endpoint uses business changefeed lists for lifecycle visibility and status,
then enriches each row from the internal list when a kernel row exists. The
summary `id` is therefore the kernel/internal changefeed ID and can be passed to
detail or write endpoints when it is non-empty. For a creating changefeed that
does not have a kernel row yet, `id` is empty while the item is still included
in the list and total.

To obtain `display_id`, changefeed architecture, and TiCDC cluster metadata,
call:

```text
/ticdc-meta/{cluster_type}/internal-changefeeds/{cluster_id}
```

Use `DEDICATED_TIDB`, `LOGICAL_CLUSTER`, or `SHARED_POOL` as `cluster_type`.
Each returned `id` is the kernel/internal changefeed ID. The field is empty for
a creating changefeed until its kernel row exists; `display_id` remains
available for display and correlation.

## Query Changefeed Metadata and ID Mapping

Use this read-only workflow when a user refers to the Changefeeds table in
`ops.tidbcloud.com`, asks which ID belongs to a product-facing name, or needs to
correlate an Ops Portal entry with Clinic metrics and logs.

### Preferred Helper

```bash
skills/platform/devops-api/tidb-tools-cdc/scripts/query-changefeed-mapping.sh \
  1379661944646413872
```

Arguments:

| Position | Required | Default | Meaning |
|---|---|---|---|
| `1` | Yes | - | TiDB cluster ID |
| `2` | No | `DEDICATED_TIDB` | `DEDICATED_TIDB`, `SHARED_POOL`, or `LOGICAL_CLUSTER` |
| `3` | No | `prod` | DevOps environment: `prod`, `staging`, or `dev` |

Authentication uses `DEVOPS_API_TOKEN` from the environment or `.env`, following
the parent `devops-api` skill.

The helper preserves its original output field names for compatibility:

| Helper field | Raw API field | Meaning |
|---|---|---|
| `changefeed_name` | `display_name` | Product-facing name in Ops Portal |
| `changefeed_id` | `display_id` | Business/display changefeed ID |
| `internal_id` | `id` | Kernel/internal TiCDC ID used by detail, write, metrics, and log workflows; empty until a kernel row exists |
| `destination` | `downstream_type` | Destination type such as `kafka` |
| `ticdc_cluster_id` | `ticdc_cluster.id` | Internal TiCDC cluster ID |
| `ticdc_cluster_name` | `ticdc_cluster.name` | TiCDC cluster name |

Example output:

```json
[
  {
    "changefeed_name": "aws_us_prod_risk_ip_site_usage_changfeed",
    "changefeed_id": "2082385093980905472",
    "internal_id": "1410801",
    "status": "failed",
    "destination": "kafka",
    "ticdc_cluster_id": "...",
    "ticdc_cluster_name": "ticdc-1379661944646413872"
  }
]
```

### Raw API

Call the full metadata endpoint through the shared wrapper:

```bash
skills/platform/devops-api/scripts/devops_http.sh \
  --env prod \
  --path /ticdc-meta/DEDICATED_TIDB/internal-changefeeds/1379661944646413872
```

The raw endpoint is subject to the same 1000-row cap. Every returned row also
contains the full, non-sensitive configuration fields documented for the detail
response below: network information, checkpoint, RCU, table config, start
position, downstream config, and TiCDC cluster metadata.

For legacy TiCDC metrics and logs, map the helper's `internal_id` to the runtime
label `changefeed-<internal_id>`. Do not assume that `display_name` is present in
TiCDC Prometheus labels or OpenAPI responses.

Name-to-business-ID table:

```bash
skills/platform/devops-api/tidb-tools-cdc/scripts/query-changefeed-mapping.sh \
  1379661944646413872 |
jq -r '.[] | [.changefeed_name, .changefeed_id] | @tsv'
```

Look up the kernel/internal ID for one display name:

```bash
skills/platform/devops-api/tidb-tools-cdc/scripts/query-changefeed-mapping.sh \
  1379661944646413872 |
jq -r '.[] | select(.changefeed_name == "aws_us_prod_risk_ip_site_usage_changfeed") | .internal_id'
```

This capability is read-only. Do not use the metadata endpoint directly for
pause, resume, update, or delete operations; use the corresponding operational
workflow.

## Get Changefeed Detail

Get one changefeed and its non-sensitive CDC configuration.

API Path: `/ticdc-meta/{cluster_type}/internal-changefeed/{changefeed_id}`

Method: `GET`

This endpoint intentionally does not accept `cluster_id`. The backend loads the
internal changefeed by kernel `changefeed_id`, obtains its business/display ID,
then loads the Connector metadata and applies cluster-scope authorization before
returning the detail.

Path parameters:

| Field | Type | Notes |
|---|---|---|
| `changefeed_id` | string | The kernel/internal changefeed ID from `/ticdc-meta/{cluster_type}/internal-changefeeds/{cluster_id}`. |
| `cluster_type` | string | Use `CHANGEFEED` for Dedicated and `CHANGEFEED_NG` for Premium/BYOC shared-pool changefeeds. |

Example:

```bash
./scripts/devops_http.sh \
  --path /ticdc-meta/CHANGEFEED/internal-changefeed/123456
```

### Response

The `changefeed` object contains:

| Field | Type | Notes |
|---|---|---|
| `id` | string | Kernel/internal changefeed identifier used by detail, configuration, and write endpoints |
| `display_id` | string | Business/display identifier used only for display and internal correlation |
| `display_name` | string | Changefeed name |
| `status` | string | Current status |
| `cluster_type` | string | Changefeed cluster type |
| `downstream_type` | string | Sink type |
| `created_at` | integer | Unix timestamp in seconds |
| `ticdc_cluster` | object | TiCDC cluster summary when available |
| `checkpoint_tso` | string | Checkpoint TSO as a string to avoid integer precision loss |
| `checkpoint_ts` | integer | Checkpoint Unix timestamp in seconds |
| `rcu` | string | Configured changefeed instance/RCU specification |
| `network_info` | object | Network type, endpoint IDs, ports, and Dedicated private-link/Kafka advertised settings when present |
| `table_config` | object | Filter rules, mode, case sensitivity, and event filters |
| `start_position` | object | Start mode, TSO, and timestamp |
| `downstream_config` | object | Sink-specific configuration with credentials omitted |

Sensitive downstream fields are omitted from the response, including passwords,
tokens, access/secret keys, SAS tokens, private keys, client secrets, and
credentials. Do not infer an omitted value as an empty credential.