> For the complete documentation index, see [llms.txt](https://documentation.alluxio.io/ee-ai-en/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://documentation.alluxio.io/ee-ai-en/reference/rest-api.md).

# REST API

The Rest APIs are designed for jobs, configurations, and cluster management.

### Distributed Load

Pre-loads UFS (Underlying File System) data into worker caches to prevent performance degradation caused by cold reads.

#### Submit or resume a load job

| **Method** | **Path**     | **Parameters** | **Request Body Type**          |
| ---------- | ------------ | -------------- | ------------------------------ |
| POST       | /api/v1/load | None           | Content-Type: application/json |

**Parameters**

| **Name**      | **Type** | **Required** | **Description**                                                                                                                                                                                                                                                                                                                               | **Example**                                                                                |
| ------------- | -------- | ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ |
| `path`        | string   | No           | A single UFS directory or file to load, like CLI `--path`; the path also identifies the job for subsequent progress/stop queries                                                                                                                                                                                                              | '{"path": "s3://bucket/dir/"}'                                                             |
| `index`       | string   | No           | Path to the index file on UFS (must be mounted)                                                                                                                                                                                                                                                                                               | '{"index": "s3://bucket/key"}'                                                             |
| `paths`       | string   | No           | List of UFS paths to load. End each directory path with `/`. A path without the trailing `/` is treated as one file, so a directory given without it loads nothing. A file path may end with a space and `{range=...}` to load only those byte ranges, see [Cache Loading](https://documentation.alluxio.io/ee-ai-en/cache/cache-loading.md). | '{"paths": \["s3://bucket/dir1/", "s3://bucket/key2", "s3://bucket/key3 {range=0-4MiB}"]}' |
| `alias`       | string   | No           | Used in combination with paths for subsequent status queries                                                                                                                                                                                                                                                                                  | '{"paths": \["s3://bucket/key1"], "alias": "database1"}'                                   |
| `isOverWrite` | bool     | No           | Terminate an existing job for the same target and submit a fresh one with the new parameters, like CLI `--overwrite`                                                                                                                                                                                                                          | '{"path": "s3://bucket/dir/", "isOverWrite": true}'                                        |
| `options`     | object   | No           | Configuration options for the load job                                                                                                                                                                                                                                                                                                        | '{"index": "s3://bucket/key", "options":{"batchSize":10}}'                                 |

Note: You must choose exactly one of `path`, `index`, or `paths`. If `paths` is used, an `alias` can be specified; otherwise, a random alias will be generated and returned.

An `options` JSON can be used to configure the options of the load job. All options are optional. Possible configs are:

| Name               | Type   | Required | Description                                                                                                                                                                                                                                             |
| ------------------ | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `batchSize`        | int    | No       | Batch size for workers to load data from UFS                                                                                                                                                                                                            |
| `replicas`         | int    | No       | Number of file replicas to load. Defaults to the path-specific config or 1                                                                                                                                                                              |
| `skipIfExists`     | bool   | No       | Skip the loading process if the file already exists                                                                                                                                                                                                     |
| `loadPolicy`       | enum   | No       | Currently supports IF\_CHANGED. Updates the file if it has changed                                                                                                                                                                                      |
| `loadMetadataOnly` | bool   | No       | Only load file metadata                                                                                                                                                                                                                                 |
| `verify`           | bool   | No       | After the load completes, re-check every file and reload any that are not fully cached, like CLI `--verify`                                                                                                                                             |
| `fileFilterRegex`  | string | No       | Only load files whose path matches the regular expression                                                                                                                                                                                               |
| `preScanFile`      | bool   | No       | Count the files and bytes of the target in a separate listing, so that progress shows the totals. Starts when the job is first scheduled                                                                                                                |
| `skipQuotaCheck`   | bool   | No       | Skip the quota check that `alluxio.dora.load.job.must.check.quota` requires, like CLI `--skip-quota-check`                                                                                                                                              |
| `indexServiceMode` | enum   | No       | `withLoad`: rebuild the listing index of every directory in the loaded tree, concurrently with the data load. `indexOnly`: only rebuild the listing index — no data or metadata is loaded. Omitted: normal load. Unknown values are rejected with `400` |

**Example**

JSON request payload:

```
{
  "paths": [
    "s3://my-bucket/dir/to/path"
  ],
  "options": {
    "batchSize": 1,
    "replicas": 1,
    "loadMetadataOnly": true,
    "loadPolicy": "IF_CHANGED",
    "indexServiceMode": "withLoad"
  }
}
```

Success Response (JSON):

```
{
  "target":"job-95e8a01f-d519-4c1a-8311-26714f4db623",
  "id":"1cf35e69-b6e6-4807-8aae-588e0e994277"
}
```

**Error Codes**

| HTTP Code | Error Code            | Description                                                                                                                                                                                                                                                             |
| --------- | --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 200       | OK                    | Operation successful                                                                                                                                                                                                                                                    |
| 400       | Bad Request           | Request body missing or required fields missing; or `paths` while `alluxio.dora.load.job.must.check.quota` is `true` and `skipQuotaCheck` is not set: a list of paths has no load path or index file to look the quota up by, so load an `index` file or skip the check |
| 409       | Conflict              | A job with the same target and type already exists and keeps its original parameters — a running one continues, a stopped one is resumed; the response returns that job's id. Pass `isOverWrite` to replace it instead.                                                 |
| 500       | Internal Server Error | Unexpected error                                                                                                                                                                                                                                                        |

#### Get Load Job Progress

| **Method** | **Path**     | **Params** | **Request Body Type** |
| ---------- | ------------ | ---------- | --------------------- |
| GET        | /api/v1/load | Yes        | None                  |

**Parameters:**

| **Name**     | **Type** | **Required** | **Description**                                                                                                 | **Example**                                                                      |
| ------------ | -------- | ------------ | --------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- |
| `target`     | string   | Yes          | Field information returned when submitting the job                                                              | target=job-95e8a01f-d519-4c1a-8311-26714f4db623                                  |
| `fileList`   | bool     | No           | Retrieve the list of loaded files                                                                               | target=job-95e8a01f-d519-4c1a-8311-26714f4db623\&fileList=true                   |
| `fileStatus` | string   | No           | File list type \[TOTAL\|FAILURE], case-insensitive. Defaults to TOTAL when omitted. Any other value returns 400 | target=job-95e8a01f-d519-4c1a-8311-26714f4db623\&fileList=true\&fileStatus=TOTAL |

Note: 3.7 query parameters remain compatible, eg:`alias`,`index`

A query parameter the route does not accept, such as a misspelled `targe=`, returns `400` naming it; before, it was ignored and the request could list every job. For load and free jobs, a `target` with a trailing slash finds the job submitted without one.

With `fileList=true`, the response is 404 if the job is not found, or if the list was never written (for example the FAILURE list of a job with no failed files) or has expired. A file list is deleted once it is older than `alluxio.job.retention.time` (7d) and its job is no longer waiting, running, or stopped.

**Examples:**

Response for job execution status:

```json
{
    "id": "043cc6c2-b456-4d57-a807-a8c86256d8f2",
    "startTime": "2026-01-16T16:35:35.32+08:00",
    "endTime": "2026-01-16T16:35:42.149+08:00",
    "jobState": "SUCCEEDED",
    "timeElapsedMilliseconds": 6829,
    "paths": [
        "s3://test/index"
    ],
    "alias": "job-e7cc61f3-fdd5-45fe-a11b-e8f92f0c6d05",
    "batchSize": 200,
    "loadedBytes": 127,
    "totalBytes": 127,
    "loadedNonEmptyFiles": 1,
    "scannedFiles": 1,
    "replicas": "ALL"
}
```

Response for file list:

```
[
    {
        "path": "s3://test/index",
        "size": 0,
        "mTime": 0
    },
    {
        "path": "s3://test/index-copy",
        "size": 0,
        "mTime": 0
    }
]
```

**Error Codes**

| HTTP Code | Error Code            | Description          |
| --------- | --------------------- | -------------------- |
| 200       | OK                    | Operation successful |
| 404       | Not Found             | Job does not exist   |
| 500       | Internal Server Error | Unexpected error     |

#### Stop a load job

| **Method** | **Path**     | **Parameters** | **Request Body Type**          |
| ---------- | ------------ | -------------- | ------------------------------ |
| DELETE     | /api/v1/load | None           | Content-Type: application/json |

**Parameters**

| Name   | Type   | Required | Description                          | Example                                               |
| ------ | ------ | -------- | ------------------------------------ | ----------------------------------------------------- |
| target | string | Yes      | Target ID returned at job submission | {"target":"job-95e8a01f-d519-4c1a-8311-26714f4db623"} |

Note: Stop parameters remain compatible with version 3.7, eg:`alias`,`index`

**Error Codes**

| HTTP Status | Error Code  | Description                                |
| ----------- | ----------- | ------------------------------------------ |
| 200         | OK          | Operation successful                       |
| 400         | Bad Request | No request body or missing required fields |
| 404         | Not Found   | Load job does not exist                    |
| 410         | Gone        | Load job has already completed             |

#### List all load jobs

| **Method** | **Path**     | **Parameters** | **Request Body Type** |
| ---------- | ------------ | -------------- | --------------------- |
| GET        | /api/v1/load | yes            | None                  |

**Parameters:**

| **Name**       | **Type** | **Required** | **Description**                                                                                                                                                                                                                                                                                                                    |
| -------------- | -------- | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| state          | string   | No           | One job state, or several separated by commas: WAITING, RUNNING, VERIFYING, STOPPED, SUCCEEDED, FAILED; or `ALL`. Case-insensitive. Default: `ALL`. WAITING, RUNNING and VERIFYING cannot be combined with STOPPED, SUCCEEDED and FAILED in one request                                                                            |
| endedAfter     | string   | No           | List only the jobs that ended at or after this time, given in RFC 3339 form such as `2026-11-02T08:00:00Z` or `2026-11-02T16:00:00+08:00`. A time without an offset is read in the coordinator's time zone. Requires a `state` made only of STOPPED, SUCCEEDED and FAILED. A STOPPED job without a recorded end time is not listed |
| lastKey        | string   | No           | The `nextKey` of the previous page. See [Paging through a job list](#paging-through-a-job-list)                                                                                                                                                                                                                                    |
| count          | int      | No           | Maximum number of jobs on a page, from 1 to 10000. Default: 1000                                                                                                                                                                                                                                                                   |
| failureSamples | int      | No           | For each listed job, show up to this many failed files. From 0 to 100. Default: 0, no samples. See [Failure samples in a job list](#failure-samples-in-a-job-list)                                                                                                                                                                 |

Note: Without parameters, the first 1000 jobs of every state are listed. `isTruncated` in the response tells whether more jobs follow.

**Error Codes**

| HTTP Status | Error Code  | Description                                                                                                                                                                                                                                                                                                                        |
| ----------- | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 200         | OK          | Operation successful                                                                                                                                                                                                                                                                                                               |
| 400         | Bad Request | Unknown `state` or a combination of states that is not allowed; an `endedAfter` that cannot be parsed or is given without finished states; `count` or `failureSamples` out of range; a query parameter the route does not accept; or a `lastKey` that cannot be used (see [Paging through a job list](#paging-through-a-job-list)) |
| 404         | Not Found   | `lastKey` is the id of a job that no longer exists                                                                                                                                                                                                                                                                                 |

**Responses**

| **Field**     | **Description**                                                                                                                                                                     |
| ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `results`     | The jobs on this page                                                                                                                                                               |
| `isTruncated` | `true` if more jobs match after this page, `false` if this is the last page. Present in every response                                                                              |
| `nextKey`     | Present only when `isTruncated` is `true`. Pass it as `lastKey` to get the next page                                                                                                |
| `filter`      | The filter the coordinator applied: `type`, `state` (`["ALL"]` when the jobs are not filtered by state), `endedAfter` (only when given, in the coordinator's time zone) and `count` |

Example response for `GET /api/v1/load?count=2` (JSON):

```
{
    "results": [
        {
            "id": "53b3123d-a042-4eb1-90e5-73798b963b04",
            "startTime": "2026-01-17T08:22:52.787+08:00",
            "endTime": "2026-01-17T08:22:57.289+08:00",
            "jobState": "SUCCEEDED",
            "timeElapsedMilliseconds": 4502,
            "paths": [
                "s3://tidas-alluxio-test/index"
            ],
            "alias": "job-1cfb048e-7ca7-48d3-8dd3-aa2ed8472176",
            "batchSize": 200,
            "loadedBytes": 127,
            "totalBytes": 127,
            "loadedNonEmptyFiles": 1,
            "scannedFiles": 1,
            "replicas": "ALL"
        },
        {
            "id": "89e288cf-480a-40df-a45b-91c3e08cb138",
            "startTime": "2026-01-17T08:22:54.117+08:00",
            "endTime": "1970-01-01T08:00:00+08:00",
            "jobState": "RUNNING",
            "runningStage": "LOADING",
            "paths": [
                "s3://tidas-alluxio-test/index"
            ],
            "alias": "job-9869111f-99f3-4ee4-9dbe-6c0204b96aec",
            "batchSize": 200,
            "replicas": "ALL"
        }
    ],
    "isTruncated": true,
    "nextKey": "jc1.bG9hZApzMzovL3RpZGFzLWFsbHV4aW8tdGVzdC9pbmRleA",
    "filter": {
        "type": "load",
        "state": ["ALL"],
        "count": 2
    }
}
```

#### Paging through a job list

A list request returns at most `count` jobs: 1000 without `count`, and at most 10000. A larger `count` returns 400 rather than a shorter page. The same steps apply to `/api/v1/load`, `/api/v1/free`, `/api/v1/copy`, `/api/v1/oci-preload` and [`/api/v1/jobs`](#list-jobs-of-every-type):

1. Send the first request without `lastKey`.
2. If `isTruncated` is `true`, send the same request again with `lastKey` set to `nextKey`, unchanged. The next page starts right after this one and does not repeat its jobs.
3. Stop when `isTruncated` is `false`.

Decide by `isTruncated`, not by the number of jobs on the page: the last page can be full. A response without `isTruncated` comes from a coordinator older than this field; with it, a page that holds fewer than `count` jobs is the last one.

```shell
curl -s 'http://coordinator:19999/api/v1/load?state=FAILED&endedAfter=2026-11-02T00:00:00Z&count=100'
curl -s 'http://coordinator:19999/api/v1/load?state=FAILED&endedAfter=2026-11-02T00:00:00Z&count=100&lastKey=<nextKey>'
```

`lastKey` also accepts, as before:

* On the routes of one job type, the path of the last job of the previous page.
* On a deployment with a single coordinator (RocksDB job store), the `id` of the last job of the previous page. If that job no longer exists the request returns 404; if it is a job of another type, or a job the coordinator cannot read back from the job store, it returns 400. A deployment with several coordinators (etcd job store) does not accept an id and returns 400.

Limits:

* Jobs come in a stable order while the job store does not change, but the order is not specified. Do not rely on it.
* A list is not a snapshot. A job that is submitted, changes state, or is removed by retention cleanup while a client is paging may appear on two pages or on none.
* A `nextKey`, or a job path, keeps working after its job is removed by retention cleanup. A job id does not: the request returns 404 (400 on `/api/v1/jobs?type=all`), and the client starts again without `lastKey`.
* A `lastKey` that starts with `jc1.` but was not handed out by the coordinator returns 400.
* A job that the coordinator cannot read back from the job store is still listed, from its stored record. It shows `id`, `jobState`, `endTime`, `errorMessage`, `startTime` where the job type records it, and the path the job was submitted with, but not the progress fields of its type. A client should not expect every field of the route on every job.

#### Failure samples in a job list

With `failureSamples=N`, each listed job carries a `failureSamples` array of up to N failed files, so that a client can see why jobs failed without fetching each job's failed-file list. Without the parameter, or with `failureSamples=0`, the field is left out.

```shell
curl -s 'http://coordinator:19999/api/v1/load?state=FAILED&endedAfter=2026-11-02T00:00:00Z&failureSamples=3'
```

```
"failureSamples": [
    {
        "file": "s3://bucket/data/part-0001",
        "reason": "WORKER_FAILED",
        "message": "<error message>"
    }
]
```

| **Field** | **Description**                                                                                                |
| --------- | -------------------------------------------------------------------------------------------------------------- |
| `file`    | The failed file. `null` for a failure that is not about one file, such as a free that could not reach a worker |
| `reason`  | The kind of failure. Its values depend on the job type, see below                                              |
| `message` | The error message, cut to 1024 characters                                                                      |

* N is at most 100, and `count` × N at most 10000. A larger value returns 400 with the largest N allowed for the request's `count`.
* N is a maximum. A job gives fewer samples when it recorded fewer failures, and `[]` when it has nothing to sample. No job type or state makes the request fail.
* Load, copy and free jobs record their failed files only when the job ends `FAILED`. A job in any other state gives `[]`.
* Load: the newest failures first, one sample per file. A load job keeps its newest 1000 failure records, and every failed part of a large file is a record of its own, so a few large failing files can leave fewer than N distinct files to sample. `reason` is the reason the scheduler recorded, such as `WORKER_FAILED`; the cause, such as a denied read, is in `message`.
* Copy: an arbitrary subset of the failed files, not the newest ones. `reason` is an error code name such as `INTERNAL`.
* Free: failures of a whole worker (`WORKER_FAILED`) or of a batch of paths (`BATCH_FAILED`) come first, with `file` set to `null`, then failed files (`FREE_FAILED`, with the worker in `message`). Otherwise an arbitrary subset.
* OCI preload jobs track their failures in memory but do not persist them, so their samples are always `[]`. Move jobs give `[]` too.
* Samples are read from the job's stored record. They are the same on a RocksDB and an etcd job store, and after a coordinator restart, and cost no extra read per job.
* The parameter is accepted only when listing. A request with `id`, `target` or `fileList` that also carries `failureSamples` returns 400.

#### List jobs of every type

| **Method** | **Path**     | **Parameters** | **Request Body Type** |
| ---------- | ------------ | -------------- | --------------------- |
| GET        | /api/v1/jobs | yes            | None                  |

Lists jobs of every type in one paged list. A coordinator that serves this route lists `job-list-all` in the `features` of [`/api/v1/cluster-info`](#get-cluster-info).

**Parameters:**

| **Name**                                 | **Type** | **Required** | **Description**                                                                                                                                                                                                                                                                                            |
| ---------------------------------------- | -------- | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| type                                     | string   | No           | `load`, `free`, `copy`, `move`, `oci-preload`, `write-cache-decommission`, or `all`. Case-insensitive; `_` may be used in place of `-`. Default: `all`                                                                                                                                                     |
| state, endedAfter, count, failureSamples |          | No           | As for [listing load jobs](#list-all-load-jobs)                                                                                                                                                                                                                                                            |
| lastKey                                  | string   | No           | The `nextKey` of the previous page, or, on a RocksDB job store, the id of the last job of the previous page. When `type` is `all`, a job path or an id that matches no stored job returns 400: jobs of several types can share a path. With a single `type`, `lastKey` is accepted as on that type's route |

Each entry in `results` carries `jobType`, in the spelling of the `type` parameter, and the fields its type shows on its own route (`/api/v1/load`, `/api/v1/free`, `/api/v1/copy`, `/api/v1/oci-preload`). A move job shows the fields every job has and `path` as `{"source": ..., "destination": ...}`, the way a copy job shows it; a `write-cache-decommission` job shows the fields every job has and `path`. `isTruncated`, `nextKey` and `filter` are as for the per-type routes, and `filter.type` is the type listed, or `all`.

Example response for `GET /api/v1/jobs?state=SUCCEEDED` (JSON):

```
{
    "results": [
        {
            "jobType": "load",
            "id": "53b3123d-a042-4eb1-90e5-73798b963b04",
            "startTime": "2026-01-17T08:22:52.787+08:00",
            "endTime": "2026-01-17T08:22:57.289+08:00",
            "jobState": "SUCCEEDED",
            "timeElapsedMilliseconds": 4502,
            "paths": ["s3://tidas-alluxio-test/index"],
            "alias": "job-1cfb048e-7ca7-48d3-8dd3-aa2ed8472176"
        },
        {
            "jobType": "free",
            "id": "1498117f-bf66-4198-967d-1186588c56d1",
            "startTime": "2026-01-17T22:13:35.198+08:00",
            "endTime": "2026-01-17T22:13:40.385+08:00",
            "jobState": "SUCCEEDED",
            "timeElapsedMilliseconds": 5187,
            "paths": ["s3://test/rest1/test/"],
            "alias": "job-312c44ac-156c-4e5a-b142-e540067ad086"
        }
    ],
    "isTruncated": false,
    "filter": {
        "type": "all",
        "state": ["SUCCEEDED"],
        "count": 1000
    }
}
```

**Error Codes**

| HTTP Status | Error Code  | Description                                                                                                                                                           |
| ----------- | ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 200         | OK          | Operation successful                                                                                                                                                  |
| 400         | Bad Request | Unknown `type`; with `type=all`, a `lastKey` that is neither a `nextKey` nor the id of a stored job; or any reason given for [listing load jobs](#list-all-load-jobs) |
| 404         | Not Found   | With a single `type`, `lastKey` is the id of a job that no longer exists                                                                                              |

### Free Cache

Clean up worker cache data to release storage space.

#### Submit or resume a free job

| **Method** | **Path**     | **Parameters** | **Request Body Type**          |
| ---------- | ------------ | -------------- | ------------------------------ |
| POST       | /api/v1/free | None           | Content-Type: application/json |

**Parameters**

| **Name**      | **Type** | **Required** | **Description**                                                                                                                                                         | **Example**                                                                  |
| ------------- | -------- | ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
| `index`       | string   | No           | Index file path on UFS (must be mounted)                                                                                                                                | '{"index": "s3://bucket/key"}'                                               |
| `paths`       | string   | No           | List of UFS paths to be freed. End each directory path with `/`. A path without the trailing `/` is treated as one file, so a directory given without it frees nothing. | '{"paths": \["s3://bucket/dir1/", "s3://bucket/key2"]}'                      |
| `alias`       | string   | No           | Used with paths for status queries                                                                                                                                      | '{"paths": \["s3://bucket/key1", "s3://bucket/key2"], "alias": "database1"}' |
| `isOverWrite` | bool     | No           | Terminate an existing job for the same target and submit a fresh one with the new parameters, like CLI `--overwrite`                                                    | '{"index": "s3://bucket/key", "isOverWrite": true}'                          |
| `options`     | object   | No           | Configuration options for the free job                                                                                                                                  | '{"index": s3://bucket/key, "options":{"batchSize":10}}'                     |

Note: Either `index` or `paths` must be provided. If `paths` is used, an `alias` can be specified; otherwise, an internal random alias will be generated.

At most one of the parameters is required. Paths and alias must be provided together.

An `options` JSON can be used to configure the options of the free job. All options are optional. Possible configs are:

| **Name**       | **Type** | **Required** | **Description**                                                                                                                                              |
| -------------- | -------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `batchSize`    | int      | No           | Number of index entries dispatched to each worker per scheduling round; does not limit the release rate                                                      |
| `rateLimit`    | long     | No           | Release rate per worker in files per second, shared across all running free jobs; 0 means unlimited, unset defaults to `alluxio.job.free.rate.limit` (20000) |
| `replicas`     | int      | No           | Number of file replicas to free                                                                                                                              |
| `indexService` | bool     | No           | Free directory cache                                                                                                                                         |

**Example**

An example JSON request payload looks like the following:

```json
{
    "paths": [
        "s3://tidas-alluxio-test/index",
        "s3://tidas-alluxio-test/index-copy"
    ],
    "options": {
        "batchSize": "30"
    }
}
```

Successful Response (JSON):

```
{
    "target": "job-0aafec67-53b4-488c-b988-73493b2b9ebe",
    "id": "bc0c3296-ea1f-484b-b371-300bf4d54ca6"
}
```

**Error Codes**

| HTTP Code | Error Code            | Description                                                                                                                                                                                                             |
| --------- | --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 200       | OK                    | Operation successful                                                                                                                                                                                                    |
| 400       | Bad Request           | Request body missing or required fields missing                                                                                                                                                                         |
| 409       | Conflict              | A job with the same target and type already exists and keeps its original parameters — a running one continues, a stopped one is resumed; the response returns that job's id. Pass `isOverWrite` to replace it instead. |
| 500       | Internal Server Error | Unexpected error                                                                                                                                                                                                        |

#### Get Free Job Progress

| **Method** | **Path**     | **Parameters** | **Request Body Type** |
| ---------- | ------------ | -------------- | --------------------- |
| GET        | /api/v1/free | Yes            | None                  |

**Parameters:**

| Name   | Type   | Required | Description                                | Example                |
| ------ | ------ | -------- | ------------------------------------------ | ---------------------- |
| target | string | Yes      | The field returned when submitting the job | target=job-95e8a01f... |

Note: 3.7 query parameters remain compatible, eg:`alias`,`index`

A query parameter the route does not accept, such as a misspelled `targe=`, returns `400` naming it; before, it was ignored and the request could list every job. For load and free jobs, a `target` with a trailing slash finds the job submitted without one.

**Example**

Successful response for job status (JSON): **Responses:**

```
{
    "id": "17bb4213-891b-4c3f-bc32-8d314051514b",
    "startTime": "2026-01-17T21:59:11.831+08:00",
    "endTime": "2026-01-17T21:59:16.104+08:00",
    "jobState": "SUCCEEDED",
    "timeElapsedMilliseconds": 4273,
    "paths": ["s3://test/"],
    "alias": "job-95adb50b-4722-4a79-bd58-872cfeca48cb",
    "freedBytes": 409600,
    "totalBytes": 409600,
    "freedFiles": 100,
    "totalFiles": 100
}
```

**Error Codes**

| HTTP Status | Error Code | Description             |
| ----------- | ---------- | ----------------------- |
| 200         | OK         | Operation successful    |
| 404         | Not Found  | Load job does not exist |

#### Stop a free job

| **Method** | **Path**     | **Parameters** | **Request Body Type**          |
| ---------- | ------------ | -------------- | ------------------------------ |
| DELETE     | /api/v1/free | None           | Content-Type: application/json |

**Parameters**

| Name   | Type   | Required | Description                                | Example                                               |
| ------ | ------ | -------- | ------------------------------------------ | ----------------------------------------------------- |
| target | string | Yes      | The field returned when submitting the job | {"target":"job-95e8a01f-d519-4c1a-8311-26714f4db623"} |

Note: Stop parameters remain compatible with version 3.7, eg:`alias`,`index`

**Error Codes**

| HTTP Status | Error Code  | Description                                |
| ----------- | ----------- | ------------------------------------------ |
| 200         | OK          | Operation successful                       |
| 400         | Bad Request | No request body or missing required fields |
| 404         | Not Found   | Job does not exist                         |
| 410         | Gone        | Job has already completed                  |

#### List all free jobs

| **Method** | **Path**     | **Parameters** | **Request Body Type** |
| ---------- | ------------ | -------------- | --------------------- |
| GET        | /api/v1/free | yes            | None                  |

**Parameters:** `state`, `endedAfter`, `lastKey`, `count` and `failureSamples`, as for [listing load jobs](#list-all-load-jobs). See [Paging through a job list](#paging-through-a-job-list).

**Error Codes:** as for [listing load jobs](#list-all-load-jobs).

**Response** Example response for listing jobs (JSON):

```
{
    "results": [
        {
            "id": "1498117f-bf66-4198-967d-1186588c56d1",
            "startTime": "2026-01-17T22:13:35.198+08:00",
            "endTime": "2026-01-17T22:13:40.385+08:00",
            "jobState": "SUCCEEDED",
            "timeElapsedMilliseconds": 5187,
            "paths": ["s3://test/rest1/test/"],
            "alias": "job-312c44ac-156c-4e5a-b142-e540067ad086"
        },
        {
            "id": "3baf5ab6-c303-4a59-8678-f297870847f4",
            "startTime": "2026-01-17T22:13:26.177+08:00",
            "endTime": "2026-01-17T22:13:30.38+08:00",
            "jobState": "SUCCEEDED",
            "timeElapsedMilliseconds": 4203,
            "paths": ["s3://test/rest/test/"],
            "alias": "job-749f2cbf-32cb-44d5-aa4f-4a4e6b94689b"
        }
    ],
    "isTruncated": false,
    "filter": {
        "type": "free",
        "state": ["ALL"],
        "count": 1000
    }
}
```

### Rebalance

#### List all rebalance jobs

**Method:** `GET`

**Path:** `/api/v1/rebalance`

**Parameters:** `state`, `lastKey` and `count`, as for [listing load jobs](#list-all-load-jobs); see [Paging through a job list](#paging-through-a-job-list)

**Responses:**

* `200 - OK`: successful operation

  ```json
  {
    "results": [
      {...}
    ]
  }
  ```

  for more information on the job description, please refer to the **“Get the progress of a rebalance job”**
* `500 - Internal Server Error`: unexpected error

  ```json
  {
    "status": "string"
  }
  ```

#### Get the progress of a rebalance job

**Method:** `GET`

**Path:** `/api/v1/rebalance`

**Parameters:**

At most one of the parameters is required.

| **Name** | **Description**                                                                                                                    |
| -------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| `id`     | job id returned by POST                                                                                                            |
| `target` | the target workers of the rebalance job, can bea worker id (e.g. worker-54b88939-de49-46ef-acab-fe489f46d1a0)ALL (for all workers) |

**Responses:**

* `200 - OK`: successful operation(empty value will be omitted)

  ```json
  {
     "succeededWorkers":2,
     "bytesPreserved":4,
     "filesLoaded":0,
     "filesPreserved":1,
     "filesFailed":0,
     "totalWorkers":2,
     "bytesPruned":226,
     "filesPruned":5,
     "bytesLoaded":0,
     "timeElapsedMilliseconds":4536,
     "runningWorkers":0,
     "startTime":"2024-12-19T23:15:07.043+08:00",
     "id":"8de63d3a-63c8-4f08-bbc1-c87e3c0fb6d9",
     "state":"SUCCEEDED",
     "failedWorkers":0
  }
  ```
* `404 - Not Found`: no job found

  ```json
  {
    "status": "No job found..."
  }
  ```
* `500 - Internal Server Error`: unexpected error

  ```json
  {
    "status": "string"
  }
  ```

#### Submit or resume a rebalance job

**Method:** `POST`

**Path:** `/api/v1/rebalance`

**Parameters:** none

**Request body:** `Content-Type: application/json`

Required field

| **Name** | **Description**                                                                                                                                    |
| -------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| `target` | The target workers of the rebalance job, can be either a worker id (e.g. `worker-54b88939-de49-46ef-acab-fe489f46d1a0`) or `ALL` (for all workers) |

An `options` JSON can be used to configure the options of the load job. All options are optional. Possible configs are:

| **Name**         | **Description**                                                                                   |
| ---------------- | ------------------------------------------------------------------------------------------------- |
| `loadBatchSize`  | the batch size in the loading phase, the same as the batchSize option in the load job             |
| `loadBandwidth`  | The load bandwidth of each worker per second in bytes. e.g.: 10485746000...                       |
| `pruneBandwidth` | The prune bandwidth of each worker per second in bytes. e.g.: 10485746000...                      |
| `skipPrune`      | If rebalance should only load data and skip pruning the data that does not blong to the worker(s) |

An example JSON request payload looks like the following:

```json
{
  "target": "ALL",
  "options": {
    "loadBatchSize": 1000,
    "loadBandwidth": 10485746000,
    "pruneBandwidth": 10485746000,
    "skipPrune": false,
  }
}
```

**Responses:**

* `200 - OK`: successful operation

  ```json
  {
    "id": "54b88939-de49-46ef-acab-fe489f46d1a0"
  }
  ```
* `400 - Bad Request`: the request doesn’t have a body or the required fields are missing

  ```json
  {
    "status": "Required parameters not provided"
  }
  ```
* `409 - Conflict`: resume the load job with the same path and return the previous job id

  ```json
  {
    "id": "54b88939-de49-46ef-acab-fe489f46d1a0"
  }
  ```
* `500 - Internal Server Error`: unexpected error

  ```json
  {
    "status": "string"
  }
  ```

#### Stop a rebalance job

**Method:** `DELETE`

**Path:** `/api/v1/rebalance`

**Parameters:** none

**Request body:** `Content-Type: application/json`

At most one of the parameters is required.

| **Name** | **Description**                                                                                                                                    |
| -------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`     | job id returned by POST                                                                                                                            |
| `target` | the target workers of the rebalance job, can be either a worker id (e.g. `worker-54b88939-de49-46ef-acab-fe489f46d1a0`) or `ALL` (for all workers) |

**Responses:**

* `200 - OK`: successful operation

  ```json
  {
    "status": "ok"
  }
  ```
* `400 - Bad Request`: the request doesn’t have a body or the required fields are missing

  ```json
  {
    "status": "Required parameters not provided"
  }
  ```
* `410 - Gone`: the job doesn’t exist or has already finished

  ```json
  {
    "status": "The job doesn't exist or has already finished"
  }
  ```
* `500 - Internal Server Error`: unexpected error

  ```json
  {
    "status": "string"
  }
  ```

### Rebalance V2

The Rebalance V2 endpoints supersede the V1 [`/api/v1/rebalance`](#rebalance) endpoints for on-the-fly rebalance jobs, and drive the versioned consistent hash ring. For the operational workflow, see [Cache Rebalancing](https://documentation.alluxio.io/ee-ai-en/cache/cache-rebalancing.md).

All endpoints require `alluxio.coordinator.job.meta.store.type = ETCD`. When the etcd-based job metastore is not enabled, every endpoint below returns `501`:

| Code                    | Body                                                                              |
| ----------------------- | --------------------------------------------------------------------------------- |
| `501 - Not Implemented` | `{ "status": "Etcd-based job metastore is not enabled for the coordinator ..." }` |

For brevity, the `501` error response is omitted from each endpoint's response table below.

#### Submit a rebalance job

**Method:** `POST`

**Path:** `/api/v1/rebalance-v2`

**Parameters:**

All fields are optional; defaults come from the coordinator configuration.

| Name                        | Description                                                                                                                                                             |
| --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `skipExistingFiles`         | If `true`, skip files that already exist on the destination worker. Default `false`.                                                                                    |
| `maxParallelWorkerSessions` | Max concurrent worker-to-worker sessions per worker. Must be in `(0, 1000]`. Default `10`.                                                                              |
| `maxParallelFilesPerWorker` | Max concurrent file transfers per session. Must be a positive integer. Default `4`.                                                                                     |
| `loadSource`                | Where receivers read rebalanced file data from: `PEER` (pull pages from peer workers) or `UFS` (read directly from the UFS). Default `PEER`. See **Load source** below. |

A combined per-worker concurrency bound is imposed: `maxParallelWorkerSessions × maxParallelFilesPerWorker × 2 ≤ 2048`.

**Request body:** `Content-Type: application/json`

```json
{
  "skipExistingFiles": false,
  "maxParallelWorkerSessions": 10,
  "maxParallelFilesPerWorker": 4,
  "loadSource": "PEER"
}
```

**Responses:**

| Code                          | Body                                                                            | Description                                                                                                                                                                                                                     |
| ----------------------------- | ------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `200 - OK`                    | `{ "jobId": "<uuid>", "status": "RUNNING", "message": "" }`                     | Successful operation. `status` is `RUNNING` even when some workers failed to receive the dispatch; in that case `message` is `Some workers failed to receive dispatch: [<workerIds>]`.                                          |
| `400 - Bad Request`           | `{ "status": "..." }`                                                           | Bad parameters: `maxParallelWorkerSessions` is `<= 0` or `> 1000`; `maxParallelFilesPerWorker` is not a positive integer; the combined per-worker concurrency bound exceeds 2048; or `loadSource` is not one of `PEER` / `UFS`. |
| `400 - Bad Request`           | `{ "status": "Another rebalance job is already running with jobId <id>. ..." }` | Single-job invariant: another rebalance job is already running.                                                                                                                                                                 |
| `400 - Bad Request`           | `{ "status": "Job not run as no changes in cluster member are detected" }`      | Current and staging hash rings are identical (no joining or leaving workers).                                                                                                                                                   |
| `500 - Internal Server Error` | `{ "status": "<exception>" }`                                                   | Unexpected server error.                                                                                                                                                                                                        |

**Load source.** `loadSource` selects where each receiving worker reads the bytes of a rebalanced file. The file list, metadata discovery, and job orchestration are identical for both values — only the data source differs.

* `PEER` (default): the receiver pulls cached pages from peer workers over the worker-to-worker data path.
* `UFS`: the receiver reads the file's data directly from the UFS. When a listed file is not loadable from the UFS it is **skipped** (not failed), with a skip reason surfaced in the verbose `unitsSkippedPerPeer` histogram: `not_found_in_ufs` (the UFS is mounted but the file no longer exists) or `ufs_not_mounted` (the file's UFS is not mounted on the receiver).

{% hint style="warning" %}
With `loadSource=UFS`, existing workers keep serving the version they previously cached while newly added workers load the current version from the UFS. For files that change in the UFS this can leave replicas inconsistent across the ring. Opt in only when the UFS files are immutable, or when cache-filter / staleness policies are in place.
{% endhint %}

#### Get the status of a rebalance job

**Method:** `GET`

**Path:** `/api/v1/rebalance-v2`

**Parameters:**

| Name      | Description                                                                                                                                                                                                                                                                 |
| --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `jobId`   | \[Required] The job ID returned by POST.                                                                                                                                                                                                                                    |
| `verbose` | \[Optional] If `true`, each per-worker entry includes the full per-peer breakdown (counters, byte totals, skip-reason histogram, approximate-unique file estimates). If `false` or absent, each per-worker entry carries only `workerId`, `workerRole`, and `errorMessage`. |

When the job is in a non-terminal state, the coordinator polls each involved worker, reclassifies workers as `inProgress` / `succeeded` / `failed`, recomputes aggregated totals, and rewrites the etcd record (moving it to the finished prefix on terminal transition). The echoed `plan` reflects the submitted request, including the target hash ring members and the parameters used.

**Responses:**

| Code                          | Body                                               | Description                                                                                                                            |
| ----------------------------- | -------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| `200 - OK`                    | See the example below.                             | Successful operation. `status` is one of `STARTED`, `RUNNING`, `SUCCEEDED`, `FAILED`. The per-worker entry shape depends on `verbose`. |
| `400 - Bad Request`           | `{ "status": "Required parameters not provided" }` | The `jobId` query parameter is missing.                                                                                                |
| `404 - Not Found`             | `{ "status": "No job found for the ID: <jobId>" }` | No job exists for the given `jobId` in either the running or finished etcd prefix.                                                     |
| `500 - Internal Server Error` | `{ "status": "..." }`                              | Unexpected server error.                                                                                                               |

An example successful response body:

```json
{
  "jobId": "54b88939-de49-46ef-acab-fe489f46d1a0",
  "status": "RUNNING",
  "createdAt": 1700000000000,
  "plan": {
    "targetHashRing": ["worker-a", "worker-b", "worker-c", "worker-d"],
    "addedWorkers": ["worker-d"],
    "removedWorkers": [],
    "skipExistingFiles": false,
    "maxParallelWorkerSessions": 10,
    "maxParallelFilesPerWorker": 4,
    "loadSource": "UFS"
  },
  "progress": {
    "totalUnitsDiscovered": 4,
    "totalUnitsRebalanced": 3,
    "totalUnitsFailed": 1,
    "totalBytesRebalanced": 3072,
    "totalUnitsSkipped": 0
  },
  "workersInProgress": [{
    "workerId": "worker-d",
    "workerRole": "ADDED",
    "errorMessage": ""
  }],
  "workersSucceeded": [],
  "workersFailed": []
}
```

With `verbose=true`, each per-worker entry additionally carries the per-peer breakdown, e.g. `unitsSkippedPerPeer` which (under `loadSource=UFS`) may include the `not_found_in_ufs` and `ufs_not_mounted` reasons above:

```json
{
  "workerId": "worker-d",
  "workerRole": "ADDED",
  "errorMessage": "",
  "lastUpdateTimestampMs": 1700000001234,
  "unitsDiscoveredPerPeer": { "worker-a": 2, "worker-b": 1 },
  "unitsRebalancedPerPeer": { "worker-a": 2, "worker-b": 0 },
  "unitsFailedPerPeer":     { "worker-a": 0, "worker-b": 0 },
  "bytesRebalancedPerPeer": { "worker-a": 2048, "worker-b": 0 },
  "unitsSkippedPerPeer": {
    "worker-b": { "not_found_in_ufs": 1 }
  },
  "approximateUniqueFilesDiscovered": 3,
  "approximateUniqueFilesRebalanced": 2
}
```

#### Stop a running rebalance job

**Method:** `DELETE`

**Path:** `/api/v1/rebalance-v2`

**Parameters:**

| Name    | Description                              |
| ------- | ---------------------------------------- |
| `jobId` | \[Required] The job ID returned by POST. |

**Request body:** `Content-Type: application/json`

```json
{
  "jobId": "54b88939-de49-46ef-acab-fe489f46d1a0"
}
```

The coordinator broadcasts the stop signal to every involved worker; workers terminate cooperatively and the next GET reflects their terminal state.

**Responses:**

| Code                          | Body                                                                                                                            | Description                                               |
| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------- |
| `200 - OK`                    | `{ "jobId": "54b88939-...", "message": "Stop signal sent to workers. It may take some time for the job to be fully stopped." }` | Stop signal dispatched to all involved workers.           |
| `400 - Bad Request`           | `{ "status": "Only running job can be stopped. Job <jobId> is in status <status>" }`                                            | The job's persisted status is not `STARTED` or `RUNNING`. |
| `404 - Not Found`             | `{ "status": "No job found for the ID: <jobId>" }`                                                                              | No job exists for the given `jobId`.                      |
| `500 - Internal Server Error` | `{ "status": "Failed to stop rebalance job <jobId> on worker <workerId>: <exception>" }`                                        | The stop RPC failed for at least one involved worker.     |

### Membership

The `/membership` endpoints manage cluster membership and the versioned consistent hash ring; they supersede the deprecated `/nodes` endpoint (see [Node management](#node-management)). For the operational workflow, see [Cache Rebalancing](https://documentation.alluxio.io/ee-ai-en/cache/cache-rebalancing.md).

The endpoints that operate on the versioned hash ring (`GET /membership`, `GET /membership/staging`, `GET /membership/history`, `PUT /membership`, `PATCH /membership/staging`) require the feature to be enabled (`alluxio.user.consistent.hash.ring.versioning.enabled=true`); otherwise they return `400` with error code `VERSIONING_NOT_ENABLED`. `GET /membership/all`, `GET /membership/{workerId}`, and `DELETE /membership/{workerId}` do not require it.

Unless stated otherwise, error responses share a single JSON envelope (the `context` object is omitted when empty):

```json
{
  "error": "WORKER_NOT_FOUND",
  "message": "human-readable detail",
  "context": { "workers": ["worker-id-1"] }
}
```

The `fingerprint` field returned by the list endpoints is a sha256 over the member-identity set (`sha256:<hex>`); it is the optimistic-concurrency token echoed back as `expectedFingerprint` on `operation=commit`. It is always present (the empty-set value is returned when the ring is uninitialized).

#### Initialize or repair the hash ring

**Method:** `PUT`

**Path:** `/api/v1/membership`

**Request body:** `Content-Type: application/json`

```json
{
  "workerIds": ["worker-id-1", "worker-id-2"]
}
```

| Field       | Type      | Required | Description                                                                  |
| ----------- | --------- | -------- | ---------------------------------------------------------------------------- |
| `workerIds` | string\[] | Yes      | Non-empty list of already-registered worker IDs to initialize the ring with. |

This endpoint is safe for a stateless operator to PUT repeatedly:

* **Uninitialized ring** → initialized → `200` with `result=SUCCESS`.
* **Fully initialized ring** → `200` with `result=ALREADY_INITIALIZED` if the current workers match the input (a healthy ring is never overwritten); a different set → `409`.
* **Partially initialized ring** (e.g. a crash mid-bootstrap) → repaired from the request → `200` with `result=REPAIRED`.

The write is guarded by the ring-field revisions observed when the request was prepared, so a concurrent modification surfaces as `409 CAS_CONFLICT` rather than clobbering. The transaction guards a fixed set of keys regardless of worker count, so initializing a large cluster is not subject to etcd's per-transaction operation limit.

**Responses:**

```json
{
  "result": "SUCCESS",
  "currentMembers": ["worker-id-1", "worker-id-2"]
}
```

| Field            | Type      | Description                                                                                                                            |
| ---------------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| `result`         | string    | One of `SUCCESS` (fresh init), `ALREADY_INITIALIZED` (idempotent no-op on an identical ring), `REPAIRED` (a partial ring was repaired) |
| `currentMembers` | string\[] | Worker IDs the ring was initialized/repaired with, or the existing committed members when `ALREADY_INITIALIZED`                        |

| Code                          | Body (`error` code)        | Description                                                                                                  |
| ----------------------------- | -------------------------- | ------------------------------------------------------------------------------------------------------------ |
| `400 - Bad Request`           | `VERSIONING_NOT_ENABLED`   | Versioned hash ring is not enabled                                                                           |
| `400 - Bad Request`           | `INVALID_ARGUMENT`         | Request body is missing, `workerIds` is missing/empty, or a worker ID is malformed                           |
| `400 - Bad Request`           | `WORKER_NOT_FOUND`         | One or more requested workers are not registered (the offending IDs are in `context.workers`)                |
| `409 - Conflict`              | `RING_ALREADY_INITIALIZED` | The ring is already initialized with a different worker set (the existing set is in `context.actualMembers`) |
| `409 - Conflict`              | `CAS_CONFLICT`             | The ring was modified concurrently; retry                                                                    |
| `500 - Internal Server Error` | `INTERNAL`                 | Unexpected server error                                                                                      |

#### List committed members

**Method:** `GET`

**Path:** `/api/v1/membership`

**Parameters:** none

**Responses:**

```json
{
  "initialized": true,
  "members": [
    {
      "workerId": "worker-00000000-0000-0000-0000-000000000001",
      "address": "worker-host-1:29999",
      "status": "ONLINE",
      "capacityBytes": 107374182400,
      "usedBytes": 53687091200,
      "nodeLabel": "zone-a"
    }
  ],
  "fingerprint": "sha256:9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08"
}
```

| Field         | Type      | Description                                                                             |
| ------------- | --------- | --------------------------------------------------------------------------------------- |
| `initialized` | boolean   | Whether the ring has been initialized                                                   |
| `members`     | object\[] | Committed members as worker-detail objects (see fields below). Empty if not initialized |
| `fingerprint` | string    | Content-addressable fingerprint of the committed member set; always present             |

Worker-detail object fields:

| Field           | Type   | Description                                                                                                        |
| --------------- | ------ | ------------------------------------------------------------------------------------------------------------------ |
| `workerId`      | string | Unique worker identifier                                                                                           |
| `address`       | string | Worker's `host:rpcPort`                                                                                            |
| `status`        | string | `ONLINE` if the worker is currently live, `OFFLINE` otherwise (`UNKNOWN` for a member with no registration record) |
| `capacityBytes` | number | Total storage capacity in bytes                                                                                    |
| `usedBytes`     | number | Used storage in bytes                                                                                              |
| `nodeLabel`     | string | Node label assigned to the worker                                                                                  |

| Code                          | Body (`error` code)      | Description                                        |
| ----------------------------- | ------------------------ | -------------------------------------------------- |
| `400 - Bad Request`           | `VERSIONING_NOT_ENABLED` | Versioned hash ring is not enabled                 |
| `500 - Internal Server Error` | `INTERNAL`               | Unexpected error while retrieving membership state |

#### List all registered members

**Method:** `GET`

**Path:** `/api/v1/membership/all`

**Parameters:** none

Returns an array of worker-detail objects (fields as in **List committed members**). `inCurrent` and `inStaging` are included only when the versioned hash ring is enabled, and omitted otherwise.

**Responses:**

```json
[
  {
    "workerId": "worker-00000000-0000-0000-0000-000000000001",
    "address": "worker-host-1:29999",
    "status": "ONLINE",
    "capacityBytes": 107374182400,
    "usedBytes": 53687091200,
    "nodeLabel": "zone-a",
    "inCurrent": true,
    "inStaging": false
  }
]
```

| Field       | Type    | Description                                                                                    |
| ----------- | ------- | ---------------------------------------------------------------------------------------------- |
| `inCurrent` | boolean | Whether the worker is in the current (committed) hash ring (omitted if versioning is disabled) |
| `inStaging` | boolean | Whether the worker is in the staging hash ring (omitted if versioning is disabled)             |

| Code                          | Body (`error` code) | Description                                       |
| ----------------------------- | ------------------- | ------------------------------------------------- |
| `500 - Internal Server Error` | `INTERNAL`          | Unexpected error while retrieving the worker list |

#### Retrieve worker detail

**Method:** `GET`

**Path:** `/api/v1/membership/{workerId}`

**Path Parameters:**

| Name       | Description                                 |
| ---------- | ------------------------------------------- |
| `workerId` | Worker ID, matching pattern `worker-[\w-]+` |

See **List committed members** for field descriptions. `inCurrent` and `inStaging` are included only when versioning is enabled.

**Responses:**

```json
{
  "workerId": "worker-00000000-0000-0000-0000-000000000001",
  "address": "worker-host-1:29999",
  "status": "ONLINE",
  "capacityBytes": 107374182400,
  "usedBytes": 53687091200,
  "nodeLabel": "zone-a",
  "inCurrent": true,
  "inStaging": false
}
```

| Code                          | Body (`error` code) | Description                                              |
| ----------------------------- | ------------------- | -------------------------------------------------------- |
| `400 - Bad Request`           | `INVALID_ARGUMENT`  | The provided `workerId` is not a valid worker identifier |
| `404 - Not Found`             | `WORKER_NOT_FOUND`  | No registered worker exists with the given ID            |
| `500 - Internal Server Error` | `INTERNAL`          | Unexpected server error                                  |

#### List staging members

**Method:** `GET`

**Path:** `/api/v1/membership/staging`

**Parameters:** none

**Responses:**

```json
{
  "initialized": true,
  "members": [ { "workerId": "worker-...-000000000001", "address": "worker-host-1:29999", "status": "ONLINE", "capacityBytes": 107374182400, "usedBytes": 53687091200, "nodeLabel": "zone-a" } ],
  "diff": {
    "joining": ["worker-00000000-0000-0000-0000-000000000003"],
    "leaving": []
  },
  "fingerprint": "sha256:..."
}
```

When the staging ring has not been initialized, `initialized` is `false`, `members` is empty, `diff` is omitted, and `fingerprint` is the empty-set value.

| Field          | Type      | Description                                                                                  |
| -------------- | --------- | -------------------------------------------------------------------------------------------- |
| `initialized`  | boolean   | Whether a staging ring exists                                                                |
| `members`      | object\[] | Staging members as worker-detail objects. Empty if not initialized                           |
| `diff.joining` | string\[] | Workers present in staging but not in current (would be added on commit)                     |
| `diff.leaving` | string\[] | Workers present in current but not in staging (would be removed on commit)                   |
| `fingerprint`  | string    | Fingerprint of the staging member set; the `expectedFingerprint` token echoed back on commit |

| Code                          | Body (`error` code)      | Description                        |
| ----------------------------- | ------------------------ | ---------------------------------- |
| `400 - Bad Request`           | `VERSIONING_NOT_ENABLED` | Versioned hash ring is not enabled |
| `500 - Internal Server Error` | `INTERNAL`               | Unexpected server error            |

#### Update the staging ring

Modify the staging hash ring. Supports three operations: `add` and `remove` (atomic, idempotent batch edits) and `commit` (promote the staging ring to become the current ring, guarded by a fingerprint).

**Method:** `PATCH`

**Path:** `/api/v1/membership/staging`

**Request Body:** `Content-Type: application/json`

```json
{
  "operation": "add",
  "workerIds": ["worker-00000000-0000-0000-0000-000000000003"]
}
```

```json
{
  "operation": "commit",
  "expectedFingerprint": "sha256:..."
}
```

| Field                 | Type      | Required    | Description                                                                                                                                                                                                             |
| --------------------- | --------- | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `operation`           | string    | Yes         | One of `add`, `remove`, `commit`                                                                                                                                                                                        |
| `workerIds`           | string\[] | Conditional | Required for `add` and `remove`. Each must be registered for `add`. Already-staged (`add`) or already-absent (`remove`) workers are absorbed idempotently. Applied in a single atomic transaction. Ignored for `commit` |
| `expectedFingerprint` | string    | Conditional | Required for `commit`. The `fingerprint` read from a prior `GET /membership/staging`; the commit is rejected if the staging ring changed since                                                                          |

**Responses:**

```json
{
  "status": "SUCCESS",
  "staging": [
    "worker-00000000-0000-0000-0000-000000000001",
    "worker-00000000-0000-0000-0000-000000000002"
  ],
  "fingerprint": "sha256:..."
}
```

| Field         | Type      | Description                                                                           |
| ------------- | --------- | ------------------------------------------------------------------------------------- |
| `status`      | string    | `SUCCESS` for `add` / `remove`; for `commit`, one of `SUCCESS` or `NOTHING_TO_COMMIT` |
| `staging`     | string\[] | Updated list of worker IDs in the staging ring after the operation                    |
| `fingerprint` | string    | Fingerprint of the staging ring after the operation                                   |

| Code                          | Body (`error` code)      | Description                                                                                                           |
| ----------------------------- | ------------------------ | --------------------------------------------------------------------------------------------------------------------- |
| `400 - Bad Request`           | `VERSIONING_NOT_ENABLED` | Versioned hash ring is not enabled                                                                                    |
| `400 - Bad Request`           | `INVALID_ARGUMENT`       | Body missing, `operation` absent/invalid, `workerIds` missing for `add`/`remove`, or a worker ID malformed            |
| `400 - Bad Request`           | `MISSING_FINGERPRINT`    | `expectedFingerprint` is missing for a `commit` operation                                                             |
| `400 - Bad Request`           | `WORKER_NOT_FOUND`       | `add` references an unregistered worker, or `commit` finds a staged worker whose registration was concurrently purged |
| `409 - Conflict`              | `FINGERPRINT_MISMATCH`   | The `expectedFingerprint` on `commit` does not match the current staging ring                                         |
| `409 - Conflict`              | `CAS_CONFLICT`           | The staging ring was modified concurrently; retry                                                                     |
| `503 - Service Unavailable`   | `ETCD_UNAVAILABLE`       | etcd is unreachable                                                                                                   |
| `500 - Internal Server Error` | `INTERNAL`               | Unexpected server error                                                                                               |

#### Retrieve hash ring change history

**Method:** `GET`

**Path:** `/api/v1/membership/history`

**Parameters:** none

Returns an array of history entries (each a past ring version and the timestamp until which it was effective), or an empty array if no history exists.

**Responses:**

```json
[
  {
    "effectiveUntil": 1748822400000,
    "members": ["worker-00000000-0000-0000-0000-000000000001"]
  },
  {
    "effectiveUntil": 1748908800000,
    "members": [
      "worker-00000000-0000-0000-0000-000000000001",
      "worker-00000000-0000-0000-0000-000000000002"
    ]
  }
]
```

| Field            | Type      | Description                                               |
| ---------------- | --------- | --------------------------------------------------------- |
| `effectiveUntil` | number    | Unix timestamp (ms) when this ring version was superseded |
| `members`        | string\[] | Worker IDs that formed the hash ring during this period   |

| Code                          | Body (`error` code)      | Description                        |
| ----------------------------- | ------------------------ | ---------------------------------- |
| `400 - Bad Request`           | `VERSIONING_NOT_ENABLED` | Versioned hash ring is not enabled |
| `500 - Internal Server Error` | `INTERNAL`               | Unexpected server error            |

#### Purge a worker permanently

Purge the registration record of a worker from the membership store (permanently removes the worker's entry from etcd).

**Preconditions.** A worker can only be purged when both of the following are true:

1. The worker is `OFFLINE` — workers that are still heartbeating cannot be purged; stop the worker process first.
2. When the versioned hash ring is enabled, the ring must be initialized and the worker must be unbound — **not** referenced in the current or the staging member list.

Failed preconditions result in a `409 Conflict`. The endpoint is idempotent: purging a worker that has no registration record returns `200 OK`, so operator reconcile loops can retry safely.

**Method:** `DELETE`

**Path:** `/api/v1/membership/{workerId}`

**Path Parameters:**

| Name       | Description                                 |
| ---------- | ------------------------------------------- |
| `workerId` | Worker ID, matching pattern `worker-[\w-]+` |

**Responses:**

```json
{
  "status": "ok"
}
```

| Code                          | Body (`error` code)      | Description                                                                       |
| ----------------------------- | ------------------------ | --------------------------------------------------------------------------------- |
| `400 - Bad Request`           | `INVALID_ARGUMENT`       | The path parameter `workerId` is not a parseable worker identifier                |
| `409 - Conflict`              | `WORKER_STILL_LIVE`      | The worker is not in `OFFLINE` state (still heartbeating / online)                |
| `409 - Conflict`              | `WORKER_IN_CURRENT_RING` | Versioning is enabled and the worker is still referenced in the current hash ring |
| `409 - Conflict`              | `WORKER_IN_STAGING_RING` | Versioning is enabled and the worker is still referenced in the staging hash ring |
| `409 - Conflict`              | `RING_NOT_INITIALIZED`   | Versioning is enabled but the current/staging member lists are missing from etcd  |
| `503 - Service Unavailable`   | `ETCD_UNAVAILABLE`       | etcd is unreachable                                                               |
| `500 - Internal Server Error` | `INTERNAL`               | Unexpected server error                                                           |

### Clear Stale Cache

> This operation differs from the [Free Cache](#free-cache) operation in that:
>
> 1. The free job requires a list of files or directories as input arguments to specify what to free from the workers. The Clear Stale Cache operation does not require such input because what counts as “stale cache” is determined automatically by scanning the worker cache storage and consulting the current consistent hash ring.
> 2. The free job requires setting the correct number of replicas, otherwise it may free fewer replicas than expected, if file replication is enabled. The clear stale cache operation simply broadcasts to all the workers in the cluster, so it always triggers the clearing of stale cache on all workers, regardless of how many replicas there are.

The `op` field selects the mode: `clear-stale` deletes the stale data, while `scan-stale` only measures it — each worker logs how many stale bytes it holds and deletes nothing.

#### Start clearing stale cache

**Method:** `POST`

**Path:** `/api/v1/cache`

**Parameters:** none

**Request body:** `Content-Type: application/json`

```json
{
  "op": "clear-stale"
}
```

**Responses:**

* `200 - OK`: an empty errors object indicates that the operation has been successfully submitted to all workers for execution

  ```json
  {
    "errors": {}
  }
  ```
* `200 - OK`: non-empty errors object indicates that the operation fails to be submitted to at least one of the workers for execution

  ```json
  {
    "errors": {
      "worker-host": "error message"
    }
  }
  ```
* `400 - Bad Request`: the request doesn’t have a body or the required fields are missing

  ```json
  {
    "status": "Required parameters not provided"
  }
  ```
* `500 - Internal Server Error`: unexpected error

  ```json
  {
    "status": "string"
  }
  ```
* `501 - Not Implemented`: the specified operation type is not implemented

  ```json
  {
    "status": "OP not implemented"
  }
  ```

#### Stop clearing stale cache

**Method:** `DELETE`

**Path:** `/api/v1/cache`

**Parameters:** none

**Request body:** `Content-Type: application/json`

```json
{
  "op": "clear-stale"
}
```

**Responses:**

* `200 - OK`: an empty errors object indicates that all workers have been successfully notified to stop clearing stale cache

  ```json
  {
    "errors": {}
  }
  ```
* `200 - OK`: non-empty errors object indicates that the coordinator fails to notify at least one of the workers to stop clearing stale cache

  ```json
  {
    "errors": {
      "worker-host": "error message"
    }
  }
  ```
* `400 - Bad Request`: the request doesn’t have a body or the required fields are missing

  ```json
  {
    "status": "Required parameters not provided"
  }
  ```
* `500 - Internal Server Error`: unexpected error

  ```json
  {
    "status": "string"
  }
  ```
* `501 - Not Implemented`: the specified operation type is not implemented

  ```json
  {
    "status": "OP not implemented"
  }
  ```

#### Scan stale cache without deleting

Use `scan-stale` to measure stale cache without removing anything. Each worker scans its local storage and logs a summary (`Stale cache scan finished: scanned <N> files, found <N> stale bytes, removed <N> bytes`); no data is deleted. The method, path, and responses are identical to the clear-stale operation above — only the `op` value differs.

**Start scanning** — `POST` `/api/v1/cache`:

```json
{
  "op": "scan-stale"
}
```

**Stop scanning** — `DELETE` `/api/v1/cache`:

```json
{
  "op": "scan-stale"
}
```

### Mount Table

#### List mount points

**Method:** `GET`

**Path:** `/api/v1/mount`

**Parameters:** none

**Responses:**

* `200 - OK`: successful operation(options will be omitted if empty)

  ```json
  {
    "results": [
      {
        "path": "/data/",
        "ufs": "s3://my-bucket/",
        "options": {
          "s3a.secretKey": "string",
          "s3a.accessKeyId": "string"
        }
      }
    ]
  }
  ```
* `500 - Internal Server Error`: unexpected error

  ```json
  {
    "status": "string"
  }
  ```

#### Get mount point information

**Method:** `GET`

**Path:** `/api/v1/mount`

**Parameters:**

| **Name** | **Description**                        |
| -------- | -------------------------------------- |
| `path`   | Alluxio or UFS path of the mount point |

**Responses:**

* `200 - OK`: successful operation(options will be omitted if empty)

  ```json
  {
    "path": "/data/",
    "ufs": "s3://my-bucket/",
    "options": {
      "s3a.secretKey": "string",
      "s3a.accessKeyId": "string"
    }
  }
  ```
* `404 - Not Found`: mount point not found

  ```json
  {
    "status": "No mount point found for path: /data/"
  }
  ```
* `500 - Internal Server Error`: unexpected error

  ```json
  {
    "status": "string"
  }
  ```

#### Create a mount point

**Method:** `POST`

**Path:** `/api/v1/mount`

**Parameters:** none

**Request body:** `Content-Type: application/json`

```json
{
  "path": "/data",
  "ufs": "s3://my-bucket",
  "options": {
    "s3a.secretKey": "string",
    "s3a.accessKeyId": "string"
  }
}
```

**Responses:**

* `200 - OK`: successful operation

  ```json
  {
    "status": "ok"
  }
  ```
* `400 - Bad Request`: the request doesn’t have a body or the required fields are missing

  ```json
  {
    "status": "Required parameters not provided"
  }
  ```
* `409 - Conflict`: the path is already mounted, or the UFS has been mounted to another path

  ```json
  {
    "status": "string"
  }
  ```
* `501 - Not Implemented`: the mount table doesn’t support managing via an API (e.g.: static file mount table)

  ```json
  {
    "status": "string"
  }
  ```
* `500 - Internal Server Error`: unexpected error

  ```json
  {
    "status": "string"
  }
  ```

#### Delete a mount point

**Method:** `DELETE`

**Path:** `/api/v1/mount`

**Parameters:** none

**Request body:** `Content-Type: application/json`

```json
{
  "path": "/data"
}
```

Note that the path can be either a UFS path or an Alluxio path.

**Responses:**

* `200 - OK`: successful operation

  ```json
  {
    "status": "ok"
  }
  ```
* `400 - Bad Request`: the request doesn’t have a body or the required fields are missing

  ```json
  {
    "status": "Required parameters not provided"
  }
  ```
* `410 - Gone`: the path isn’t mounted to any UFS

  ```json
  {
    "status": "string"
  }
  ```
* `501 - Not Implemented`: the mount table doesn’t support managing via an API (e.g.: static file mount table)

  ```json
  {
    "status": "string"
  }
  ```
* `500 - Internal Server Error`: unexpected error

  ```json
  {
    "status": "string"
  }
  ```

### Quota

#### List all quota status

**Method:** `GET`

**Path:** `/api/v1/quota`

**Parameters:** none

**Responses:**

* `200 - OK`: successful operation

  ```json
  {
    "results": [
      {
        "path": "/data/dir/to/path",
        "state": "Available",
        "quotaBytes": 10737418240,
        "usedBytes": 9663676416,
        "reservedBytes": 1073741824
      }
    ]
  }
  ```

  Note that the returned paths are Alluxio paths.
* `501 - Not Implemented`: quota is not enabled

  ```json
  {
    "status": "Quota not enabled"
  }
  ```
* `500 - Internal Server Error`: unexpected error

  ```json
  {
    "status": "string"
  }
  ```

#### Get quota status

**Method:** `GET`

**Path:** `/api/v1/quota`

**Parameters:**

| **Name** | **Description**                       |
| -------- | ------------------------------------- |
| `path`   | Alluxio or UFS path of the quota rule |

**Responses:**

* `200 - OK`: successful operation

  ```json
  {
    "path": "/data/dir/to/path",
    "state": "Available",
    "quotaBytes": 10737418240,
    "usedBytes": 9663676416,
    "reservedBytes": 1073741824
  }
  ```

  Note that the returned paths are Alluxio paths.
* `404 - Not Found`: quota not found

  ```json
  {
    "status": "No quota item found for path: /data/dir/to/path"
  }
  ```
* `501 - Not Implemented`: quota is not enabled

  ```json
  {
    "status": "Quota not enabled"
  }
  ```
* `500 - Internal Server Error`: unexpected error

  ```json
  {
    "status": "string"
  }
  ```

#### Add or update quota

**Method:** `POST`

**Path:** `/api/v1/quota`

**Parameters:** none

**Request body:** `Content-Type: application/json`

```json
{
  "path": "/data/dir/to/path",
  "quotaBytes": 10737418240
}
```

Note that the path can be either a UFS path or an Alluxio path. The path must have been mounted in Alluxio's mount table.

**Responses:**

* `200 - OK`: successful operation

  ```json
  {
    "status": "ok"
  }
  ```
* `400 - Bad Request`: the request doesn’t have a body or the required fields are missing

  ```json
  {
    "status": "Required parameters not provided"
  }
  ```
* `400 - Bad Request`: the path doesn’t refer to a mounted UFS but it must be bound with an existing UFS

  ```json
  {
    "status": "No mounted UFS found"
  }
  ```
* `501 - Not Implemented`: quota is not enabled

  ```json
  {
    "status": "Quota not enabled"
  }
  ```
* `500 - Internal Server Error`: unexpected error

  ```json
  {
    "status": "string"
  }
  ```

#### Delete quota

**Method:** `DELETE`

**Path:** `/api/v1/quota`

**Parameters:** none

**Request body:** `Content-Type: application/json`

```json
{
  "path": "/data/dir/to/path"
}
```

Note that the path can be either a UFS path or an Alluxio path. The path must have been mounted in Alluxio's mount table.

**Responses:**

* `200 - OK`: successful operation

  ```json
  {
    "status": "ok"
  }
  ```
* `400 - Bad Request`: the request doesn’t have a body or the required fields are missing

  ```json
  {
    "status": "Required parameters not provided"
  }
  ```
* `400 - Bad Request`: quota not found or other problems

  ```json
  {
    "status": "string"
  }
  ```
* `501 - Not Implemented`: quota is not enabled

  ```json
  {
    "status": "Quota not enabled"
  }
  ```
* `500 - Internal Server Error`: unexpected error

  ```json
  {
    "status": "string"
  }
  ```

### TTL

#### List all TTL policies

**Method:** `GET`

**Path:** `/api/v1/ttl`

**Parameters:** none

**Responses:**

* `200 - OK`: successful operation

  ```json
  {
    "results": [
      {
        "path": "/data/dir/to/path",
        "ttlSeconds": 600
      }
    ]
  }
  ```

  Note that the returned path is an Alluxio path.
* `501 - Not Implemented`: TTL policy is not enabled

  ```json
  {
    "status": "TTL not enabled"
  }
  ```
* `500 - Internal Server Error`: unexpected error

  ```json
  {
    "status": "string"
  }
  ```

#### Get TTL policy

**Method:** `GET`

**Path:** `/api/v1/ttl`

**Parameters:**

| **Name** | **Description**                                  |
| -------- | ------------------------------------------------ |
| `path`   | Alluxio or UFS path of the TTL policy to look up |

**Responses:**

* `200 - OK`: successful operation

  ```json
  {
    "path": "/data/dir/to/path",
    "ttlSeconds": 600
  }
  ```

  Note that the returned path is an Alluxio path.
* `404 - Not Found`: TTL not found

  ```json
  {
    "status": "No TTL policy found for path: /data/dir/to/path"
  }
  ```
* `501 - Not Implemented`: TTL policy is not enabled

  ```json
  {
    "status": "TTL not enabled"
  }
  ```
* `500 - Internal Server Error`: unexpected error

  ```json
  {
    "status": "string"
  }
  ```

#### Add or update TTL

**Method:** `POST`

**Path:** `/api/v1/ttl`

**Parameters:** none

**Request body:** `Content-Type: application/json`

```json
{
  "path": "/data/dir/to/path",
  "ttlSeconds": 600
}
```

Note that the path can be either a UFS path or an Alluxio path. The path must have been mounted in Alluxio's mount table.

**Responses:**

* `200 - OK`: successful operation

  ```json
  {
    "status": "ok"
  }
  ```
* `400 - Bad Request`: the request doesn’t have a body or the required fields are missing

  ```json
  {
    "status": "Required parameters not provided"
  }
  ```
* `400 - Bad Request`: the path doesn’t refer to a mounted UFS but it must be bound with an existing UFS

  ```json
  {
    "status": "No mounted UFS found"
  }
  ```
* `501 - Not Implemented`: TTL policy is not enabled

  ```json
  {
    "status": "TTL not enabled"
  }
  ```
* `500 - Internal Server Error`: unexpected error

  ```json
  {
    "status": "string"
  }
  ```

#### Delete TTL

**Method:** `DELETE`

**Path:** `/api/v1/ttl`

**Parameters:** none

**Request body:** `Content-Type: application/json`

```json
{
  "path": "/data/dir/to/path"
}
```

Note that the path can be either a UFS path or an Alluxio path. The path must have been mounted in Alluxio's mount table.

**Responses:**

* `200 - OK`: successful operation

  ```json
  {
    "status": "ok"
  }
  ```
* `400 - Bad Request`: the request doesn’t have a body or the required fields are missing

  ```json
  {
    "status": "Required parameters not provided"
  }
  ```
* `400 - Bad Request`: TTL not found

  ```json
  {
    "status": "string"
  }
  ```
* `501 - Not Implemented`: TTL is not enabled

  ```json
  {
    "status": "TTL not enabled"
  }
  ```
* `500 - Internal Server Error`: unexpected error

  ```json
  {
    "status": "string"
  }
  ```

### Priority Eviction

#### List all priority eviction policies

**Method:** `GET`

**Path:** `/api/v1/priority`

**Parameters:** none

**Responses:**

* `200 - OK`: successful operation

  ```json
  {
    "results": [
      {
        "path": "/data/dir/to/path",
        "priority": "high"
      }
    ]
  }
  ```

Note that the returned paths are Alluxio paths.

* `501 - Not Implemented`: Priority eviction is not enabled

  ```json
  {
    "status": "Priority eviction not enabled"
  }
  ```
* `500 - Internal Server Error`: unexpected error

  ```json
  {
    "status": "string"
  }
  ```

#### Get priority eviction policy

**Method:** `GET`

**Path:** `/api/v1/priority`

**Parameters:**

| **Name** | **Description**                                     |
| -------- | --------------------------------------------------- |
| `path`   | Alluxio or UFS path of the priority rule to look up |

**Responses:**

* `200 - OK`: successful operation

  ```json
  {
    "path": "/data/dir/to/path",
    "priority": "high"
  }
  ```

  Note that the returned path is an Alluxio path.
* `404 - Not Found`: priority eviction not found

  ```json
  {
    "status": "No priority rule found for path: /data/dir/to/path"
  }
  ```
* `501 - Not Implemented`: priority eviction is not enabled

  ```json
  {
    "status": "Priority eviction not enabled"
  }
  ```
* `500 - Internal Server Error`: unexpected error

  ```json
  {
    "status": "string"
  }
  ```

#### Add or update priority

**Method:** `POST`

**Path:** `/api/v1/priority`

**Parameters:** none

**Request body:** `Content-Type: application/json`

```json
{
  "path": "/data/dir/to/path",
  "priority": "high"
}
```

Note that the path can be either a UFS path or an Alluxio path. The path must have been mounted in Alluxio's mount table.

**Responses:**

* `200 - OK`: successful operation

  ```json
  {
    "status": "ok"
  }
  ```
* `400 - Bad Request`: the request doesn’t have a body or the required fields are missing

  ```json
  {
    "status": "Required parameters not provided"
  }
  ```
* `400 - Bad Request`: priority string misformatted or other problems

  ```json
  {
    "status": "string"
  }
  ```
* `501 - Not Implemented`: priority eviction is not enabled

  ```json
  {
    "status": "Priority eviction not enabled"
  }
  ```
* `500 - Internal Server Error`: unexpected error

  ```json
  {
    "status": "string"
  }
  ```

#### Delete priority

**Method:** `DELETE`

**Path:** `/api/v1/priority`

**Parameters:** none

**Request body:** `Content-Type: application/json`

```json
{
  "path": "/data/dir/to/path"
}
```

Note that the path can be either a UFS path or an Alluxio path. The path must have been mounted in Alluxio's mount table.

**Responses:**

* `200 - OK`: successful operation

  ```json
  {
    "status": "ok"
  }
  ```
* `400 - Bad Request`: the request doesn’t have a body or the required fields are missing

  ```json
  {
    "status": "Required parameters not provided"
  }
  ```
* `501 - Not Implemented`: priority eviction is not enabled

  ```json
  {
    "status": "Priority eviction not enabled"
  }
  ```
* `500 - Internal Server Error`: unexpected error

  ```json
  {
    "status": "string"
  }
  ```

### Node management

#### List all nodes

**Method:** `GET`

**Path:** `/api/v1/nodes`

**Parameters:** none

**Responses:**

* `200 - OK`: successful operation

  ```json
  {
    "result": [
      {
        "identity": "worker-587899dd-5da5-45d4-af40-ce481acc4087",
        "address": "192.168.1.19:29989",
        "status": "ONLINE"
      },
      {
        "identity": "worker-844db66c-d7fd-46cc-8de0-2f3989360828",
        "address": "192.168.1.19:29999",
        "status": "OFFLINE"
      }
    ]
  }
  ```
* `500 - Internal Server Error`: unexpected error

  ```json
  {
    "status": "string"
  }
  ```

#### Query a node

**Method:** `GET`

**Path:** `/api/v1/nodes`

**Parameters:**

| **Name** | **Description**                                              |
| -------- | ------------------------------------------------------------ |
| `id`     | worker id (e.g. worker-587899dd-5da5-45d4-af40-ce481acc4087) |

**Responses:**

* `200 - OK`: successful operation\
  (empty value will be omitted)

  ```json
  {
    "identity": "worker-587899dd-5da5-45d4-af40-ce481acc4087",
    "address": "192.168.1.19:29989",
    "status": "ONLINE"
  }
  ```
* `404 - Not Found`: worker not found

  ```json
  {
    "status": "worker not found..."
  }
  ```
* `500 - Internal Server Error`: unexpected error

  ```json
  {
    "status": "string"
  }
  ```

#### Decommission a node (remove a node from etcd)

**Method:** `DELETE`

**Path:** `/api/v1/nodes`

**Parameters:**

| **Name** | **Description**                                              |
| -------- | ------------------------------------------------------------ |
| `id`     | worker id (e.g. worker-587899dd-5da5-45d4-af40-ce481acc4087) |

**Responses:**

* `200 - OK`: successful operation

  ```json
  {
    "status": "ok"
  }
  ```
* `404 - Not Found`: worker not found

  ```json
  {
    "status": "worker not found..."
  }
  ```
* `500 - Internal Server Error`: unexpected error

  ```json
  {
    "status": "string"
  }
  ```

### Global File Index

#### List all nodes

**Method:** `GET`

**Path:** `/api/v1/file_index`

**Parameters:** none

**Responses:**

* `200 - OK`: successful operation

  ```json
  {
    "results": [
      "file:///home/yimin/alluxio/ufs/10MB",
      "file:///home/yimin/alluxio/ufs/to_load/f1"
    ]
  }
  ```
* `500 - Internal Server Error`: unexpected error

  ```json
  {
    "status": "string"
  }
  ```

#### Add files into the global file index

**Method:** `POST`

**Path:** `/api/v1/file_index`

**Parameters:** none

**Request body:** `Content-Type: application/json`

```json
{
  "files": [
    "s3://foo/bar/f1",
    "s3://foo/bar/f2"
  ]
}
```

**Responses:**

* `200 - OK`: successful operation (# of entries added)

  ```json
  {
    "entries": 10
  }
  ```
* `404 - Not Found`: feature not enabled

  ```json
  {
    "status": "Global file index is not enabled"
  }
  ```
* `500 - Internal Server Error`: unexpected error

  ```json
  {
    "status": "string"
  }
  ```

#### Remove files from the global file index

**Method:** `DELETE`

**Path:** `/api/v1/file_index`

**Parameters:** none

**Request body:** `Content-Type: application/json`

```json
{
  "files": [
    "s3://foo/bar/f1",
    "s3://foo/bar/f2"
  ]
}
```

**Responses:**

* `200 - OK`: successful operation (# of entries removed)

  ```json
  {
    "entries": 10
  }
  ```
* `404 - Not Found`: feature not enabled

  ```json
  {
    "status": "worker not found..."
  }
  ```
* `500 - Internal Server Error`: unexpected error

  ```json
  {
    "status": "string"
  }
  ```

### Cache Filter

#### List all cache filter rules

**Method:** `GET`

**Path:** `/api/v1/cache-filter`

**Parameters:** none

**Responses:**

* `200 - OK`: successful operation

```json
{
  "results": [
    {
      "apiVersion": 1,
      "type": "metadata",
      "rules": {
        "defaultType": "immutable",
        "defaultMaxAge": null,
        "skipCache": ["s3://bucket/mutable-dir/.*"],
        "immutable": ["s3://bucket/immutable-dir/.*"],
        "maxAge": {"s3://bucket/auto-refresh/.*":  "1d"}
      }
    },
    {
      "apiVersion": 1,
      "type": "data",
      "rules": {
        "defaultType": "immutable",
        "defaultMaxAge": null,
        "skipCache": [],
        "immutable": [],
        "maxAge": {}
      }
    }
  ]
}
```

* `500 - Internal Server Error`: unexpected error

  ```json
  {
    "status": "string"
  }
  ```
* `501 - Not Implemented`: cache filter is not enabled

  ```json
  {
    "status": "Cache filter not enabled"
  }
  ```

#### Add a cache filter rule or update the default rule

**Method:** `POST`

**Path:** `/api/v1/cache-filter`

**Parameters:** none

**Request body:** `Content-Type: application/json`

```json
{
  "type": "data",
  "rule": "skipCache",
  "pattern": "s3a://data-bucket/c/.*"
}
```

If the rule is `maxAge`, a `time` is required.

```json
{
  "type": "data",
  "rule": "maxAge",
  "pattern": "s3a://auto-refresh/c/.*",
  "time": "1d"
}
```

If you want to update the default rule, set `updateDefault`. No need to specify a `pattern` because all paths that don't match any other rules will be captured by the default rule.

```json
{
  "type": "metadata",
  "rule": "skipCache",
  "updateDefault": true
}
```

**Responses:**

* `200 - OK`: successful operation
* `400 - Bad Request`: the request doesn’t have a body or the required fields are missing

  ```json
  {
    "status": "Required parameters not provided"
  }
  ```
* `500 - Internal Server Error`: unexpected error

  ```json
  {
    "status": "string"
  }
  ```
* `501 - Not Implemented`: cache filter is not enabled

  ```json
  {
    "status": "Cache filter not enabled"
  }
  ```

#### Remove a cache filter rule

**Method:** `DELETE`

**Path:** `/api/v1/cache-filter`

**Parameters:** none

**Request body:** `Content-Type: application/json`

```json
{
  "type": "data",
  "rule": "skipCache",
  "pattern": "s3a://data-bucket/c/.*"
}
```

No need to specify `time` if the rule is `maxAge`. Also, you can't remove a default rule. You can only change the default to another rule.

**Responses:**

* `200 - OK`: successful operation
* `400 - Bad Request`: the request doesn’t have a body or the required fields are missing

  ```json
  {
    "status": "Required parameters not provided"
  }
  ```
* `500 - Internal Server Error`: unexpected error

  ```json
  {
    "status": "string"
  }
  ```
* `501 - Not Implemented`: cache filter is not enabled

  ```json
  {
    "status": "Cache filter not enabled"
  }
  ```

### Cache Insight

Inspect what is cached, where it is cached, and whether the under storage and the cache agree. A scan is a live, read-only pass over under-storage listings and worker cache metadata; it never blocks application reads or writes, never loads data into the cache, and never mutates cache state.

Because the cluster keeps serving during a scan, results are approximate — a file can be cached, evicted, written, or deleted while the scan is in flight.

See [Cache Insight](https://documentation.alluxio.io/ee-ai-en/cache/cache-insight.md) for the feature guide.

#### Endpoints

| **Method** | **Path**                        | **Success**                | **Purpose**                                  |
| ---------- | ------------------------------- | -------------------------- | -------------------------------------------- |
| POST       | /api/v1/cache-insight           | 200 `application/x-ndjson` | Run a scan and stream its result             |
| GET        | /api/v1/cache-insight/workers   | 200 `application/json`     | List live workers for the `workers` selector |
| GET        | /api/v1/cache-insight/jobs      | 200 `application/json`     | List running scans                           |
| GET        | /api/v1/cache-insight/jobs/{id} | 200 `application/json`     | Poll one running scan                        |
| DELETE     | /api/v1/cache-insight/jobs/{id} | 202 `application/json`     | Request cooperative cancellation             |

#### Run a scan

**Method:** `POST`

**Path:** `/api/v1/cache-insight`

**Request Body Type:** `Content-Type: application/json`

Only `groups[].paths` is required. All other fields fall back to the defaults below.

```json
{
  "groups": [
    {
      "paths": [
        "s3://bucket/manifests/latest.json",
        "s3://bucket/train/**"
      ],
      "limit": 100000
    }
  ],
  "source": "both",
  "detail": "placement",
  "sample": 10,
  "sampleSize": 20,
  "scanRateLimit": 100000,
  "batchSize": 1000,
  "workers": ["10.0.0.12:29999"],
  "job_id": "audit-2026-07-14",
  "progress": false,
  "filters": [
    {"field": "completeness", "op": "==", "value": "incomplete"}
  ],
  "fields": ["ufs_path", "status", "cached_pct", "copies"],
  "maxRecordBytes": 33554432
}
```

**Parameters**

| **Name**             | **Type** | **Default**        | **Description**                                                                                                                                                                                                                                                                                                                                     |
| -------------------- | -------- | ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `groups[0].paths`    | array    | required           | UFS URIs or Alluxio paths. `path` = one file, `path/*` = directory (non-recursive), `path/**` = directory (recursive); a path without either suffix is always looked up as one file. Up to 100k paths. Overlapping paths are rejected with `400` naming the conflicting pairs. Exactly one group is supported today; more than one group is a `400` |
| `groups[0].name`     | string   | none               | Optional group label. Accepted on the wire but currently informational                                                                                                                                                                                                                                                                              |
| `groups[0].limit`    | int      | unlimited          | Stop after N files and mark the aggregate `truncated`. Absent means exhaustive                                                                                                                                                                                                                                                                      |
| `source`             | enum     | `ufs`              | `ufs` = read coverage against candidate workers, `worker` = cache contents (page-metadata scan), `both` = consistency audit joining the two                                                                                                                                                                                                         |
| `detail`             | enum     | `summary`          | Additive ladder `summary` < `list` < `placement` < `full`. See below                                                                                                                                                                                                                                                                                |
| `sample`             | int      | `1` (exact)        | Deterministic 1-in-N sampling of enumerated files. Aggregates become ×N estimates (relative error ≈ 1/√files) marked by a `sampled` block; re-runs pick the identical files. Explicit paths are never sampled                                                                                                                                       |
| `sampleSize`         | int      | `20`               | Per-status reservoir of example files in the aggregate. `0` disables it                                                                                                                                                                                                                                                                             |
| `scanRateLimit`      | int      | `100000`           | Page-metadata visits per second, per worker, for this scan. Taken as requested; the worker-global ceiling `alluxio.worker.cache.insight.scan.rate.limit` ([dynamic](https://documentation.alluxio.io/ee-ai-en/reference/dynamic-properties.md#observability)) still applies on top                                                                  |
| `batchSize`          | int      | `1000`             | Files per worker RPC, listing flush, and cursor page. Range 1–10000                                                                                                                                                                                                                                                                                 |
| `workers`            | array    | all                | Restrict the scan to selected workers (worker id, host, or `host:port`). Files whose candidates all fall outside the selection classify `UNCHECKED`. An unknown selector returns `400` listing the valid workers                                                                                                                                    |
| `job_id`             | string   | server fingerprint | Client-chosen id matching `[A-Za-z0-9._-]{1,64}`. Known before submitting, so progress and cancellation never require reading the stream back. Duplicate of a running job returns `409`                                                                                                                                                             |
| `progress`           | bool     | `false`            | `true` streams running aggregate snapshots. Either way a heartbeat flushes every \~2s                                                                                                                                                                                                                                                               |
| `listingParallelism` | int      | `0` (serial)       | Experimental, `source=ufs` only. `0`/`1`/absent = ordered serial listing; `>1` = that many concurrent range-listers. Bounded to \[0, 16]. Unordered, so it trades listing order for speed on large globs. Non-`ufs` sources return `400`                                                                                                            |
| `filters`            | array    | none               | Emit predicates, `{field, op, value}`, ANDed. Only matching per-file records stream; the aggregate still folds every scanned file and adds `filter_matched_files`, `filter_matched_bytes` and `filtered`. See **Filters** below. An invalid entry returns `400` with a message starting `invalid filter:`                                           |
| `fields`             | array    | whole record       | Per-file record fields to emit, applied after filtering. `record`, `ufs_path`, `input_path` and `error` are always kept. An unknown name returns `400` listing the valid names                                                                                                                                                                      |
| `maxRecordBytes`     | long     | `0` (unbounded)    | Ceiling on the per-file records the stream carries, in serialized characters. Emission stops there but the scan continues, so the aggregate stays exact and reports `records_truncated` and `records_emitted`. Negative returns `400`                                                                                                               |
| `only`               | string   | none               | Legacy form of the `completeness` filter. Comma-separated tokens `incomplete` (files not fully cached and consistent, `FAILED` included) and `complete` (the inverse). ANDed with `filters`. An unknown token returns `400`                                                                                                                         |

**Filters**

`filters` is a flat AND-list with no OR or nesting. Each entry names one field below, with one of the operators it accepts. Time thresholds are relative minutes; numeric values must be non-negative.

| **Field**                           | **Operators** | **Value**                      | **Description**                                                                                                                                                                  |
| ----------------------------------- | ------------- | ------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `completeness`                      | `==`          | `"complete"` \| `"incomplete"` | `complete`: every segment full on every expected replica, with no `inconsistency` and no failed `storage_check`. `incomplete` is the inverse                                     |
| `never_read`                        | `==`          | `true`                         | Resident, read-time tracking on, and no page ever read. `false` is rejected                                                                                                      |
| `not_read_in_minutes`               | `>=`          | minutes                        | No page read within the window, including never-read files                                                                                                                       |
| `newest_page_last_read_age_minutes` | `>=`, `<=`    | minutes                        | Age of the most recent read. A never-read file matches neither operator                                                                                                          |
| `newest_page_age_minutes`           | `>=`, `<=`    | minutes                        | Age of the most recently cached page                                                                                                                                             |
| `cached_bytes`                      | `>=`          | bytes                          | Bytes of the file cached                                                                                                                                                         |
| `file_length`                       | `>=`, `<=`    | bytes                          | The file's own size. From the UFS listing in `ufs`/`both`; from cache metadata in `worker` mode                                                                                  |
| `ufs_path`                          | `find`        | Java regex                     | Searched for in the UFS path (unanchored; write `^…$` for the whole path). At most 1000 characters                                                                               |
| `alluxio_path`                      | `find`        | Java regex                     | Searched for in the Alluxio path. A file no mount owns never matches and is counted in `filter_alluxio_unmounted`. Records carry `alluxio_path` only when this filter is present |

The last-read filters (`never_read`, `not_read_in_minutes`, `newest_page_last_read_age_minutes`) need workers that record page read times (`alluxio.worker.observability.read.time.enabled`). If a worker holding scanned pages does not, the stream ends with an `error` record and a final aggregate carrying `aborted: true, reason: "filter_unanswerable"`. A path pattern that runs longer than 250 ms on one path ends the stream the same way.

**Detail levels**

Levels are strictly additive — each keeps every field of the level below it. The RPC count is identical at every level; the payload is not.

| **Detail**  | **Per-file records** | **Adds**                                                                                                                                                                                             |
| ----------- | -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `summary`   | No                   | final aggregate only                                                                                                                                                                                 |
| `list`      | Yes                  | `status`, `cached_pct`, `cached_bytes`, `cached_age_minutes`, page-age and last-read-age ranges, `file_length`, `length_source`, segment tallies, `expected_replicas`, `complete_copies`, `copies[]` |
| `placement` | Yes                  | `copies[].missing_segments` / `partial_segments`, and `holders[]` — per-worker holdings with `candidate_segments` and fulfillment `cached_pct`                                                       |
| `full`      | Yes                  | `segments[]` — the per-segment × replica grid — plus `file_info` for explicit paths. Payload scales with segments × replicas and is not capped                                                       |

**Responses:**

* `200 - OK`: the scan was admitted; an NDJSON stream follows. In-stream problems arrive as `error` records, not HTTP errors.

  The body is **newline-delimited JSON**, not a single JSON document: one complete JSON value per line, streamed as the scan progresses. Parse line by line and tolerate unknown fields and record types.

  ```
  header  →  file × N  →  heartbeat / progress / error …  →  aggregate (final)
  ```

  ```json
  {"record":"header","job_id":"audit-1","source":"ufs","detail":"list","segmentation":true}
  {"record":"file","ufs_path":"s3://bucket/train/a.parquet","status":"PARTIAL","cached_pct":62}
  {"record":"heartbeat"}
  {"record":"aggregate","final":true,"counts":{"PARTIAL":1},"checked":1,"truncated":false}
  ```

  Treat a captured result as complete only when its last record is an `aggregate` with `"final": true`. A disconnected stream, or a cancellation observed before its final aggregate, is incomplete.
* `400 - Bad Request`: invalid parameters or parameter combinations. The JSON error identifies the rejected field, value, selector, filter, or overlapping path
* `429 - Too Many Requests`: the concurrent-scan cap (`alluxio.coordinator.cache.insight.max.concurrent.scans`, default 5) was reached. The body lists the running jobs so the caller can wait or cancel one
* `409 - Conflict`: `job_id` is already running; the response includes that job's info
* `503 - Service Unavailable`: worker membership is unavailable
* `500 - Internal Server Error`: unexpected error

**Record types**

| **Record**  | **Fields**                                                                                                                                                                             |
| ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `header`    | First record of every stream: `job_id`, `source`, `detail`, `segmentation`, `segment_size`, `workers_filter[]`, `scan_rate_limit`, `scan_rate_limit_unit`, `sample`, `generated_at_ms` |
| `file`      | One per scanned file, at `list` detail and deeper. See the field table below                                                                                                           |
| `aggregate` | Running snapshots carry `final: false`; the terminal record carries `final: true`. See the field table below                                                                           |
| `heartbeat` | Keepalive on quiet streams, \~2s cadence. No fields beyond `record`                                                                                                                    |
| `error`     | `message` — a non-fatal in-stream problem (for example, one path's listing failed). The scan continues and the final aggregate still arrives                                           |

**`file` record fields**

Null fields are omitted from the wire, so "optional" means the field appears only when it has something to report.

| **Field**                                                                                      | **Level** | **Description**                                                                                                                                                                                                                                                                                                                   |
| ---------------------------------------------------------------------------------------------- | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ufs_path`, `file_length`, `length_source`                                                     | list      | Identity. `file_length` is absent when unknown. `length_source` is which rung answered the length: `listing` (UFS listing), `cache` (worker metastore, UFS untouched), `worker_status` (may have consulted the UFS), or `ufs` (last resort)                                                                                       |
| `status`                                                                                       | list      | `FULL_ALL_REPLICAS` \| `FULL_ONE_REPLICA` \| `PARTIAL` \| `NONE` \| `FAILED` \| `UNCHECKED`                                                                                                                                                                                                                                       |
| `alluxio_path`                                                                                 | list      | The file's Alluxio path. Present only when the request has an `alluxio_path` filter and a mount owns the file                                                                                                                                                                                                                     |
| `cached_pct`, `cached_bytes`, `cached_age_minutes`                                             | list      | Readable (best-replica) coverage; age of the oldest resident page. The age is cache-insertion age, not access recency                                                                                                                                                                                                             |
| `newest_page_age_minutes`, `oldest_page_age_minutes`                                           | list      | How long ago the newest and oldest resident pages were cached                                                                                                                                                                                                                                                                     |
| `last_read_tracking`, `newest_page_last_read_age_minutes`, `oldest_page_last_read_age_minutes` | list      | How long ago the newest and oldest resident pages were last read. `last_read_tracking: true` without the age fields means every holder records reads and nothing has read the file; `false` means read times are unknown (a holder does not record them, or its scan failed). Absent when the file has no resident pages          |
| `segment_size`, `segment_count`, `segment_status`, `misplaced_bytes`                           | list      | Per-segment classification tallies using the same statuses, and bytes on non-candidate workers. The three segment descriptors appear only when the record has per-segment analysis (cluster segmentation on, or `detail` ≥ `placement`)                                                                                           |
| `expected_replicas`, `complete_copies`, `copies[]`                                             | list      | Logical copies. A copy is slot *i* of every segment, so it spans workers under segmentation. Each entry carries `replica_index`, `complete`, `cached_bytes`, `cached_pct`                                                                                                                                                         |
| `inconsistency`                                                                                | list      | `both` mode only. Present only when the storage length (the UFS listing for globs, the `storage_check` lookup for explicit paths) and a worker's recorded length disagree, in either direction: `{"ufs":{"length":N},"worker":{"length":N}}`. Emission-only visibility; the reported `file_length` and `cached_pct` are unchanged |
| `storage_check`                                                                                | list      | `both` mode, explicit paths a worker holds. A direct, uncached storage lookup: `{"state":"ok","length":N}`, `{"state":"absent"}` (the record is then `ORPHAN`), or `{"state":"failed","error":"..."}`. A failed check keeps the cache facts, carries no `inconsistency`, and never counts as `complete`                           |
| `copies[].missing_segments`, `copies[].partial_segments`                                       | placement | Range-encoded segment ids with no bytes (`"2-4"` = 2,3,4), and `{id, cached_pct}` per partially cached segment                                                                                                                                                                                                                    |
| `holders[]`                                                                                    | placement | The physical view: every worker holding any bytes, plus every zero-byte candidate. Carries `worker_id`, `host`, `cluster`, `candidate_segments`, fulfillment `cached_pct`, `cached_bytes`, `stale_bytes`, `cached_age_minutes`, the page-age and last-read-age fields above, and `resident_segments`                              |
| `segments[]`                                                                                   | full      | One entry per segment — `id`, `offset`, `length`, `status`, `misplaced_bytes` — each listing every replica cell (`replica_index`, `worker_id`, `host`, `candidate`, `active`, `cached_pct`, `cached_bytes`)                                                                                                                       |
| `file_info`                                                                                    | full      | Explicit paths only: `length`, `last_modified_ms`, `creation_time_ms`, `owner`, `group`, `mode`, `persisted`                                                                                                                                                                                                                      |
| `region`                                                                                       | both      | `MISS` (listed in storage, cached nowhere) \| `CACHED` (present on both sides) \| `ORPHAN` (resident in cache, absent from the current listing)                                                                                                                                                                                   |
| `input_path`, `error`                                                                          | any       | Emitted instead of the fields above when a requested path could not be resolved                                                                                                                                                                                                                                                   |

**`aggregate` record fields**

Fields that do not apply to the requested `source` are omitted.

| **Field**                                                                        | **Modes**       | **Description**                                                                                                                                                                                                                                                                                             |
| -------------------------------------------------------------------------------- | --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `final`, `aborted`, `reason`                                                     | all             | Stream state. `final: true` closes every stream; a scan that ended early adds `aborted: true` and `reason`: `cancelled`, or `filter_unanswerable` when a filter could not be evaluated                                                                                                                      |
| `counts`                                                                         | ufs, both       | Files per classification. A status appears only when the scan could reach it (for example, `FULL_ONE_REPLICA` only when some file expects more than one replica, `UNCHECKED` only with a `workers` filter); a present `0` means reachable and empty                                                         |
| `failed_reasons`                                                                 | ufs, both       | Failure reason → file count, capped at 50 distinct reasons. In `both` mode this includes failed listings and explicit paths that resolved nowhere                                                                                                                                                           |
| `storage_checks_failed`                                                          | both            | Explicit-path storage lookups that failed. Present when the scan ran any                                                                                                                                                                                                                                    |
| `regions`                                                                        | both            | `MISS` / `CACHED` / `ORPHAN` cardinalities                                                                                                                                                                                                                                                                  |
| `listing_order`                                                                  | both            | How the join's UFS side was ordered: `native` (the UFS lists ascending) or `sorted` (collected and sorted, capped at 100k)                                                                                                                                                                                  |
| `totals`                                                                         | worker, both    | `distinct_files`, `resident_entries`, `cached_bytes`, `misplaced_files`                                                                                                                                                                                                                                     |
| `bytes`                                                                          | all             | `scanned` (logical dataset bytes), `cached_logical` (best replica per file), `cached_physical` (across replicas), `stale`; `both` adds `orphan`                                                                                                                                                             |
| `cached_age_buckets`                                                             | all             | Insertion-age histogram (`<=10m` / `<=1h` / `<=24h` / `<=7d` / `>7d`)                                                                                                                                                                                                                                       |
| `last_read_buckets`                                                              | all             | Access-recency histogram over the same boundaries, plus `no read observed` (tracked, never read) and `unknown` (read times unavailable). All zeros in `ufs` mode                                                                                                                                            |
| `file_size_buckets`, `cached_pct_buckets`                                        | all             | Distributions. Size buckets use IEC boundaries                                                                                                                                                                                                                                                              |
| `top_cached`, `largest_stale_files`                                              | worker, both    | Bounded top-10 heaps by cached and stale bytes                                                                                                                                                                                                                                                              |
| `metadata_missing`                                                               | all             | `{count, samples}` — resident data whose length the scan could not resolve                                                                                                                                                                                                                                  |
| `workers[]`                                                                      | all             | Per-worker rows: residency (`resident_files`, `cached_bytes`, `stale_bytes`, `pages`, `cache_used_bytes`, `cache_capacity_bytes`) or, for `ufs`, check outcomes (`checked`, `full`, `partial`, `miss`, `failed`, `cached_bytes`)                                                                            |
| `workers_total`, `workers_scanned`, `workers_failed`, `failed_workers`, `errors` | all             | Fan-out health; `errors[]` holds per-worker exception messages                                                                                                                                                                                                                                              |
| `samples`                                                                        | ufs, both       | Per-status reservoir of example files: `{ufs_path, status, cached_pct}`                                                                                                                                                                                                                                     |
| `write_cache`                                                                    | worker, both    | `{v1: {pages, bytes}, v2: {pages, bytes}}` — write-cache side totals, excluded from residency                                                                                                                                                                                                               |
| `sampled`                                                                        | all             | `{rate, files}` — marks a sampled scan; counts and bytes are ×rate estimates                                                                                                                                                                                                                                |
| `checked`, `truncated`, `duration_ms`                                            | all             | Files classified, whether a `limit` or cap cut the scan short, and wall-clock time. `checked` means files checked (`ufs`), distinct resident files (`worker`), or join rows (`both`). A listing that failed, such as a nonexistent scope, is not `truncated`; it is a `FAILED` check with an `error` record |
| `filter_matched_files`, `filter_matched_bytes`                                   | filtered scans  | Files the filters matched and their cached bytes, counted at the filter decision. Exact at every detail level, including `summary`, and under a spent `maxRecordBytes`                                                                                                                                      |
| `filtered`                                                                       | filtered scans  | The histograms above (`counts`, `regions`, `cached_age_buckets`, `last_read_buckets`, `file_size_buckets`, `cached_pct_buckets`, `top_cached`, `largest_stale_files`, as the mode reports them) recomputed over the matching files only                                                                     |
| `filter_not_evaluable`, `filter_alluxio_unmounted`                               | filtered scans  | Files excluded because a filter could not judge them (a replica's scan lost the read history, or the mount table could not be read), and files an `alluxio_path` filter excluded because no mount owns them                                                                                                 |
| `records_emitted`, `records_truncated`                                           | truncated scans | Present only when `maxRecordBytes` stopped the rows early. The rows sent are the first that fit in scan order, not the largest                                                                                                                                                                              |

**Example**

```shell
curl -sN -X POST http://coordinator:19999/api/v1/cache-insight \
  -H 'Content-Type: application/json' \
  -d '{"groups":[{"paths":["s3://bucket/train/**"]}],"source":"ufs","detail":"summary"}' \
  | tail -1 | jq .
```

Count never-read cached files of 1 GiB or more, and the bytes they hold, without streaming rows:

```shell
curl -sN -X POST http://coordinator:19999/api/v1/cache-insight \
  -H 'Content-Type: application/json' \
  -d '{"groups":[{"paths":["s3://bucket/**"]}],"source":"worker","detail":"summary",
       "filters":[{"field":"never_read","op":"==","value":true},
                  {"field":"cached_bytes","op":">=","value":1073741824}]}' \
  | tail -1 | jq '{files: .filter_matched_files, bytes: .filter_matched_bytes}'
```

#### List live workers

**Method:** `GET`

**Path:** `/api/v1/cache-insight/workers`

**Responses:**

* `200 - OK`: successful operation

  ```json
  {"workers":[{"worker_id":"worker-844d...","host":"10.0.0.12","rpc_port":29999}]}
  ```
* `503 - Service Unavailable`: worker membership is unavailable

#### List, poll, and cancel running scans

**Method:** `GET`

**Path:** `/api/v1/cache-insight/jobs`, `/api/v1/cache-insight/jobs/{id}`

**Responses:**

* `200 - OK`: successful operation. `/jobs` returns the running list; `/jobs/{id}` returns one job. Each job row carries a running `checked` count, which is the REST way to watch progress without `progress: true` records in the stream

  ```json
  {"jobs":[{"job_id":"audit-1","source":"both","paths":["s3://bucket/**"],
            "path_count":1,"checked":48210,"running_ms":6180}]}
  ```
* `404 - Not Found`: unknown or already-finished job

**Method:** `DELETE`

**Path:** `/api/v1/cache-insight/jobs/{id}`

**Responses:**

* `202 - Accepted`: cancellation requested. Cancellation is cooperative — the scan unwinds at its next unit of work and its stream ends with `{"record":"aggregate","final":true,"aborted":true,"reason":"cancelled"}`. Closing the HTTP connection also cancels the scan within about one heartbeat interval

  ```json
  {"cancelling":{"job_id":"audit-1","source":"both","paths":["s3://bucket/**"],
                 "path_count":1,"checked":48210,"running_ms":6180}}
  ```
* `404 - Not Found`: unknown or already-finished job

### File Location

> **To be deprecated:** this endpoint is superseded by [Cache Insight](#cache-insight), which reports the same per-worker placement and additionally covers per-segment cached status, worker-side residency, and storage/cache reconciliation. Prefer `POST /api/v1/cache-insight` with `"detail": "full"` for new integrations.

Compute which workers hold the cached data for a file, optionally restricted to specific byte segments. Useful for locality-aware scheduling (Spark, Presto, Ray) and for debugging cache hit/miss behavior.

#### Get file or segment locations

**Method:** `GET`

**Path:** `/api/v1/location`

**Parameters**

| **Name**            | **Required** | **Description**                                                                                                                    |
| ------------------- | ------------ | ---------------------------------------------------------------------------------------------------------------------------------- |
| `path`              | Yes          | Alluxio or UFS path of the file                                                                                                    |
| `segments`          | No           | Segment spec (e.g. `0,2,5-7`). When set, the response is a list of segment-range locations                                         |
| `segment_size`      | No           | Override the configured segment size (e.g. `64MB`). Only used when `segments` is set; defaults to `alluxio.user.file.segment.size` |
| `check_all_workers` | No           | `true` to consult every worker even if the consistent-hash primary already holds the file. Only used when `segments` is not set    |

**Responses:**

* `200 - OK`: successful operation. The shape of the body depends on whether `segments` was supplied.

  When `segments` is not provided, the response is the file-level location map produced by the consistent-hash ring (one or more workers per file).

  When `segments` is provided, the response is a list of per-segment location entries, each describing the byte range and the workers that hold it.
* `400 - Bad Request`: `path` is missing

  ```json
  {
    "status": "Required parameters not provided"
  }
  ```
* `500 - Internal Server Error`: unexpected error

  ```json
  {
    "status": "string"
  }
  ```

### Replica Placement Rules

In multi-cluster deployments, replica placement rules control how many replicas of a given path prefix should live on each member cluster. Rules are keyed by an Alluxio path prefix.

#### List all replica rules

**Method:** `GET`

**Path:** `/api/v1/replica-rule`

**Parameters:** none

**Responses:**

* `200 - OK`: successful operation. Returns a map keyed by path prefix, with the corresponding rule as the value.

  ```json
  {
    "/data/shared/": {
      "...": "ReplicaClusterPlacementRule fields"
    }
  }
  ```
* `500 - Internal Server Error`: unexpected error

#### Add or update a replica rule

**Method:** `POST`

**Path:** `/api/v1/replica-rule`

**Request body:** `Content-Type: application/json`

Exactly one of `numReplicasPerCluster` or `rules` must be provided.

| **Name**                | **Type** | **Required** | **Description**                                                                                                                         |
| ----------------------- | -------- | ------------ | --------------------------------------------------------------------------------------------------------------------------------------- |
| `path`                  | string   | Yes          | Alluxio path prefix the rule applies to. Must not be a UFS path                                                                         |
| `numReplicasPerCluster` | int      | No           | Uniform replica count applied to every member cluster (must be > 0)                                                                     |
| `rules`                 | object   | No           | Per-cluster replica counts, e.g. `{"cluster-a": 2, "cluster-b": 1}`. Cluster names must be registered in the global client cluster info |

Examples:

```json
{
  "path": "/data/shared/",
  "numReplicasPerCluster": 2
}
```

```json
{
  "path": "/data/shared/",
  "rules": {
    "cluster-a": 2,
    "cluster-b": 1
  }
}
```

**Responses:**

* `200 - OK`: successful operation

  ```json
  {
    "status": "ok"
  }
  ```
* `400 - Bad Request`: `path` missing, `path` is a UFS path, both/neither of `numReplicasPerCluster` and `rules` set, a non-positive replica count, or an unknown cluster name in `rules`
* `500 - Internal Server Error`: unexpected error

#### Delete a replica rule

**Method:** `DELETE`

**Path:** `/api/v1/replica-rule`

**Request body:** `Content-Type: application/json`

```json
{
  "path": "/data/shared/"
}
```

**Responses:**

* `200 - OK`: successful operation

  ```json
  {
    "status": "ok"
  }
  ```
* `400 - Bad Request`: the request doesn't have a body or `path` is missing
* `500 - Internal Server Error`: unexpected error

### Cluster Info

Retrieves basic cluster information, including the cluster name, software version, total cache capacity and usage, and the number of online/offline workers.

#### Get cluster info

**Method:** `GET`

**Path:** `/api/v1/cluster-info`

**Parameters:** none

**Responses:**

* `200 - OK`: successful operation

  ```json
  {
    "name": "my-alluxio-cluster",
    "version": "3.x-15.0.0",
    "capacityBytes": 1099511627776,
    "usedBytes": 536870912000,
    "onlineWorkers": 5,
    "offlineWorkers": 1,
    "features": ["job-time-filter", "job-list-all"]
  }
  ```

  `features` names the optional API capabilities this coordinator serves, so a client can check for one before using it: `job-time-filter` for `endedAfter` on the job list routes, `job-list-all` for [`GET /api/v1/jobs`](#list-jobs-of-every-type). A response without `features` comes from an older coordinator that serves neither.
* `500 - Internal Server Error`: unexpected error

  ```json
  {
    "status": "string"
  }
  ```
