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	'{"paths": ["s3://bucket/key1", "s3://bucket/key2"]}'
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
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
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]	target=job-95e8a01f-d519-4c1a-8311-26714f4db623&fileList=true&fileStatus=TOTAL

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

Examples:

Response for job execution status:

{
    "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	enum	No	Job status [RUNNING
lastKey	string	No	List jobs starting from this key
count	int	No	Expected number of jobs to list

Note: If no parameters are provided, all jobs will be listed.

Error Codes

HTTP Status	Error Code	Description
200	OK	Operation successful

Responses Example response for listing jobs (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"
        }
    ]
}

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	'{"paths": ["s3://bucket/key1", "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:

{
    "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

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:

Name	Type	Required	Description
state	enum	No	Job status [RUNNING
lastKey	string	No	List jobs starting from this key
count	int	No	Expected number of jobs to list

Note: If no parameters are provided, all jobs will be listed.

Error Codes

HTTP Status	Error Code	Description
200	OK	Operation successful

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"
        }
    ]
}

Rebalance

List all rebalance jobs

Method: GET

Path: /api/v1/rebalance

Parameters: none

Responses:

• 200 - OK: successful operation

  {
    "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

  {
    "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)

  {
     "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

  {
    "status": "No job found..."
  }

• 500 - Internal Server Error: unexpected error

  {
    "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:

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

Responses:

• 200 - OK: successful operation

  {
    "id": "54b88939-de49-46ef-acab-fe489f46d1a0"
  }

• 400 - Bad Request: the request doesn’t have a body or the required fields are missing

  {
    "status": "Required parameters not provided"
  }

• 409 - Conflict: resume the load job with the same path and return the previous job id

  {
    "id": "54b88939-de49-46ef-acab-fe489f46d1a0"
  }

• 500 - Internal Server Error: unexpected error

  {
    "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

  {
    "status": "ok"
  }

• 400 - Bad Request: the request doesn’t have a body or the required fields are missing

  {
    "status": "Required parameters not provided"
  }

• 410 - Gone: the job doesn’t exist or has already finished

  {
    "status": "The job doesn't exist or has already finished"
  }

• 500 - Internal Server Error: unexpected error

  {
    "status": "string"
  }

Clear Stale Cache

This operation differs from the 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

{
  "op": "clear-stale"
}

Responses:

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

  {
    "errors": {}
  }

• 200 - OK: non-empty errors object indicates that the operation fails to be submitted to at least one of the workers for execution

  {
    "errors": {
      "worker-host": "error message"
    }
  }

• 400 - Bad Request: the request doesn’t have a body or the required fields are missing

  {
    "status": "Required parameters not provided"
  }

• 500 - Internal Server Error: unexpected error

  {
    "status": "string"
  }

• 501 - Not Implemented: the specified operation type is not implemented

  {
    "status": "OP not implemented"
  }

Stop clearing stale cache

Method: DELETE

Path: /api/v1/cache

Parameters: none

Request body: Content-Type: application/json

{
  "op": "clear-stale"
}

Responses:

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

  {
    "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

  {
    "errors": {
      "worker-host": "error message"
    }
  }

• 400 - Bad Request: the request doesn’t have a body or the required fields are missing

  {
    "status": "Required parameters not provided"
  }

• 500 - Internal Server Error: unexpected error

  {
    "status": "string"
  }

• 501 - Not Implemented: the specified operation type is not implemented

  {
    "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:

{
  "op": "scan-stale"
}

Stop scanning — DELETE /api/v1/cache:

{
  "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)

  {
    "results": [
      {
        "path": "/data/",
        "ufs": "s3://my-bucket/",
        "options": {
          "s3a.secretKey": "string",
          "s3a.accessKeyId": "string"
        }
      }
    ]
  }

• 500 - Internal Server Error: unexpected error

  {
    "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)

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

• 404 - Not Found: mount point not found

  {
    "status": "No mount point found for path: /data/"
  }

• 500 - Internal Server Error: unexpected error

  {
    "status": "string"
  }

Create a mount point

Method: POST

Path: /api/v1/mount

Parameters: none

Request body: Content-Type: application/json

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

Responses:

• 200 - OK: successful operation

  {
    "status": "ok"
  }

• 400 - Bad Request: the request doesn’t have a body or the required fields are missing

  {
    "status": "Required parameters not provided"
  }

• 409 - Conflict: the path is already mounted, or the UFS has been mounted to another path

  {
    "status": "string"
  }

• 501 - Not Implemented: the mount table doesn’t support managing via an API (e.g.: static file mount table)

  {
    "status": "string"
  }

• 500 - Internal Server Error: unexpected error

  {
    "status": "string"
  }

Delete a mount point

Method: DELETE

Path: /api/v1/mount

Parameters: none

Request body: Content-Type: application/json

{
  "path": "/data"
}

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

Responses:

• 200 - OK: successful operation

  {
    "status": "ok"
  }

• 400 - Bad Request: the request doesn’t have a body or the required fields are missing

  {
    "status": "Required parameters not provided"
  }

• 410 - Gone: the path isn’t mounted to any UFS

  {
    "status": "string"
  }

• 501 - Not Implemented: the mount table doesn’t support managing via an API (e.g.: static file mount table)

  {
    "status": "string"
  }

• 500 - Internal Server Error: unexpected error

  {
    "status": "string"
  }

Quota

List all quota status

Method: GET

Path: /api/v1/quota

Parameters: none

Responses:

• 200 - OK: successful operation

  {
    "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

  {
    "status": "Quota not enabled"
  }

• 500 - Internal Server Error: unexpected error

  {
    "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

  {
    "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

  {
    "status": "No quota item found for path: /data/dir/to/path"
  }

• 501 - Not Implemented: quota is not enabled

  {
    "status": "Quota not enabled"
  }

• 500 - Internal Server Error: unexpected error

  {
    "status": "string"
  }

Add or update quota

Method: POST

Path: /api/v1/quota

Parameters: none

Request body: Content-Type: application/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

  {
    "status": "ok"
  }

• 400 - Bad Request: the request doesn’t have a body or the required fields are missing

  {
    "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

  {
    "status": "No mounted UFS found"
  }

• 501 - Not Implemented: quota is not enabled

  {
    "status": "Quota not enabled"
  }

• 500 - Internal Server Error: unexpected error

  {
    "status": "string"
  }

Delete quota

Method: DELETE

Path: /api/v1/quota

Parameters: none

Request body: Content-Type: application/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

  {
    "status": "ok"
  }

• 400 - Bad Request: the request doesn’t have a body or the required fields are missing

  {
    "status": "Required parameters not provided"
  }

• 400 - Bad Request: quota not found or other problems

  {
    "status": "string"
  }

• 501 - Not Implemented: quota is not enabled

  {
    "status": "Quota not enabled"
  }

• 500 - Internal Server Error: unexpected error

  {
    "status": "string"
  }

TTL

List all TTL policies

Method: GET

Path: /api/v1/ttl

Parameters: none

Responses:

• 200 - OK: successful operation

  {
    "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

  {
    "status": "TTL not enabled"
  }

• 500 - Internal Server Error: unexpected error

  {
    "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

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

  Note that the returned path is an Alluxio path.

• 404 - Not Found: TTL not found

  {
    "status": "No TTL policy found for path: /data/dir/to/path"
  }

• 501 - Not Implemented: TTL policy is not enabled

  {
    "status": "TTL not enabled"
  }

• 500 - Internal Server Error: unexpected error

  {
    "status": "string"
  }

Add or update TTL

Method: POST

Path: /api/v1/ttl

Parameters: none

Request body: Content-Type: application/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

  {
    "status": "ok"
  }

• 400 - Bad Request: the request doesn’t have a body or the required fields are missing

  {
    "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

  {
    "status": "No mounted UFS found"
  }

• 501 - Not Implemented: TTL policy is not enabled

  {
    "status": "TTL not enabled"
  }

• 500 - Internal Server Error: unexpected error

  {
    "status": "string"
  }

Delete TTL

Method: DELETE

Path: /api/v1/ttl

Parameters: none

Request body: Content-Type: application/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

  {
    "status": "ok"
  }

• 400 - Bad Request: the request doesn’t have a body or the required fields are missing

  {
    "status": "Required parameters not provided"
  }

• 400 - Bad Request: TTL not found

  {
    "status": "string"
  }

• 501 - Not Implemented: TTL is not enabled

  {
    "status": "TTL not enabled"
  }

• 500 - Internal Server Error: unexpected error

  {
    "status": "string"
  }

Priority Eviction

List all priority eviction policies

Method: GET

Path: /api/v1/priority

Parameters: none

Responses:

• 200 - OK: successful operation

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

Note that the returned paths are Alluxio paths.

• 501 - Not Implemented: Priority eviction is not enabled

  {
    "status": "Priority eviction not enabled"
  }

• 500 - Internal Server Error: unexpected error

  {
    "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

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

  Note that the returned path is an Alluxio path.

• 404 - Not Found: priority eviction not found

  {
    "status": "No priority rule found for path: /data/dir/to/path"
  }

• 501 - Not Implemented: priority eviction is not enabled

  {
    "status": "Priority eviction not enabled"
  }

• 500 - Internal Server Error: unexpected error

  {
    "status": "string"
  }

Add or update priority

Method: POST

Path: /api/v1/priority

Parameters: none

Request body: Content-Type: application/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

  {
    "status": "ok"
  }

• 400 - Bad Request: the request doesn’t have a body or the required fields are missing

  {
    "status": "Required parameters not provided"
  }

• 400 - Bad Request: priority string misformatted or other problems

  {
    "status": "string"
  }

• 501 - Not Implemented: priority eviction is not enabled

  {
    "status": "Priority eviction not enabled"
  }

• 500 - Internal Server Error: unexpected error

  {
    "status": "string"
  }

Delete priority

Method: DELETE

Path: /api/v1/priority

Parameters: none

Request body: Content-Type: application/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

  {
    "status": "ok"
  }

• 400 - Bad Request: the request doesn’t have a body or the required fields are missing

  {
    "status": "Required parameters not provided"
  }

• 501 - Not Implemented: priority eviction is not enabled

  {
    "status": "Priority eviction not enabled"
  }

• 500 - Internal Server Error: unexpected error

  {
    "status": "string"
  }

Node management

List all nodes

Method: GET

Path: /api/v1/nodes

Parameters: none

Responses:

• 200 - OK: successful operation

  {
    "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

  {
    "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)

  {
    "identity": "worker-587899dd-5da5-45d4-af40-ce481acc4087",
    "address": "192.168.1.19:29989",
    "status": "ONLINE"
  }

• 404 - Not Found: worker not found

  {
    "status": "worker not found..."
  }

• 500 - Internal Server Error: unexpected error

  {
    "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

  {
    "status": "ok"
  }

• 404 - Not Found: worker not found

  {
    "status": "worker not found..."
  }

• 500 - Internal Server Error: unexpected error

  {
    "status": "string"
  }

Global File Index

List all nodes

Method: GET

Path: /api/v1/file_index

Parameters: none

Responses:

• 200 - OK: successful operation

  {
    "results": [
      "file:///home/yimin/alluxio/ufs/10MB",
      "file:///home/yimin/alluxio/ufs/to_load/f1"
    ]
  }

• 500 - Internal Server Error: unexpected error

  {
    "status": "string"
  }

Add files into the global file index

Method: POST

Path: /api/v1/file_index

Parameters: none

Request body: Content-Type: application/json

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

Responses:

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

  {
    "entries": 10
  }

• 404 - Not Found: feature not enabled

  {
    "status": "Global file index is not enabled"
  }

• 500 - Internal Server Error: unexpected error

  {
    "status": "string"
  }

Remove files from the global file index

Method: DELETE

Path: /api/v1/file_index

Parameters: none

Request body: Content-Type: application/json

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

Responses:

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

  {
    "entries": 10
  }

• 404 - Not Found: feature not enabled

  {
    "status": "worker not found..."
  }

• 500 - Internal Server Error: unexpected error

  {
    "status": "string"
  }

Cache Filter

List all cache filter rules

Method: GET

Path: /api/v1/cache-filter

Parameters: none

Responses:

• 200 - OK: successful operation

{
  "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

  {
    "status": "string"
  }

• 501 - Not Implemented: cache filter is not enabled

  {
    "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

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

If the rule is maxAge, a time is required.

{
  "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.

{
  "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

  {
    "status": "Required parameters not provided"
  }

• 500 - Internal Server Error: unexpected error

  {
    "status": "string"
  }

• 501 - Not Implemented: cache filter is not enabled

  {
    "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

{
  "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

  {
    "status": "Required parameters not provided"
  }

• 500 - Internal Server Error: unexpected error

  {
    "status": "string"
  }

• 501 - Not Implemented: cache filter is not enabled

  {
    "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 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.

{
  "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
}

Parameters

Name	Type	Default	Description
groups[0].paths	array	required	path = one file, path/* = directory (non-recursive), path/** = directory (recursive). 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 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
only	string	none	Experimental. Comma-separated emit-filter tokens restricting which per-file records stream; the aggregate still folds every file. One token today: incomplete = emit only files that are not fully cached and consistent. FAILED records always emit. An unknown token returns 400

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, 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)

  {"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, 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, alluxio_path, file_length, length_source	list	Identity. 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
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
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 UFS listing length and a worker's recorded length disagree: {"ufs":{"length":N},"worker":{"length":N}}. Emission-only visibility; the reported file_length is unchanged
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, 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; cancelled scans add aborted: true, reason: "cancelled"
counts	ufs, both	Files per classification
failed_reasons	ufs, both	Failure reason → file count, capped at 50 distinct reasons
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	worker, both	Insertion-age histogram (<=10m / <=1h / <=24h / <=7d / >7d)
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 cut the scan short, and wall-clock time. checked means files checked (ufs), distinct resident files (worker), or join rows (both)

Example

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 .

List live workers

Method: GET

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

Responses:

• 200 - OK: successful operation

  {"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

  {"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

  {"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