Skip to main content

List External Collection Refresh Jobs (V2)

This operation lists external-collection refresh jobs. When collectionName is omitted or empty, returns refresh jobs across all external collections in the target database.

POST/v2/vectordb/jobs/external_collection/list
Connection Endpoint

The base URL for this API is in the following format:

https://{cluster-id}.{region}.vectordb.zillizcloud.com:19530

📘Notes
  • Use the cluster endpoint if you are using serving clusters.

    • Free & Serverless

      https://{cluster-id}.serverless.{region}.vectordb.zillizcloud.com

    • Dedicated

      https://{cluster-id}.{region}.vectordb.zillizcloud.com:19530

The endpoints on the control plane currently supports up to 20 requests per second per user per endpoint.

export CLUSTER_ENDPOINT="https://{cluster-id}.{region}.vectordb.zillizcloud.com:19530"
Parameters
Authorizationstringheaderrequired

The authentication token should be an API key with appropriate privileges or a pair of colon-joined username and password, like username:password. If you are using a project endpoint, only a valid API key with sufficient permissions applies.

Example Value: Bearer {{TOKEN}}
Request Bodyapplication/json
dbNamestring

Name of the database to list refresh jobs from.

collectionNamestring

Name of the external collection. Leave empty or omit to list refresh jobs for all external collections in the database.

export TOKEN="YOUR_API_KEY"

curl --request POST \
--url "${CLUSTER_ENDPOINT}/v2/vectordb/jobs/external_collection/list" \
--header "Authorization: Bearer ${TOKEN}" \
--header "Content-Type: application/json" \
-d '{
    "dbName": "default",
    "collectionName": "ext_books"
}'
Responses200 - application/json
codeinteger

Response code.

Example Value: 0
dataobject

Response payload that wraps the list of refresh jobs.

recordsarray

List of refresh jobs in detail.

[]recordsobject

A refresh job in detail.

jobIdinteger<int64>

ID of the refresh job.

collectionNamestring

Name of the external collection associated with this refresh job.

statestring

Current state of the refresh job.

progressinteger

Refresh progress in percentage (0-100).

externalSourcestring

JSON-encoded source configuration this job is refreshing from. An object url in a Zilliz Cloud volume applies.

startTimeinteger<int64>

Unix timestamp at which the refresh job started.

endTimeinteger<int64>

Unix timestamp at which the refresh job ended; 0 when the job is still running.

reasonstring

Failure reason. Present only when state is RefreshFailed.

Returns an error message.

codeinteger

Response code.

messagestring

Error message.

{
    "code": 0,
    "data": {
        "records": [
            {
                "jobId": 449503829274509300,
                "collectionName": "ext_books",
                "state": "RefreshCompleted",
                "progress": 100,
                "externalSource": "{\"type\":\"volume\",\"path\":\"volume://my-volume/books\"}",
                "startTime": 1712832000000,
                "endTime": 1712832600000
            },
            {
                "jobId": 449503829274509300,
                "collectionName": "ext_movies",
                "state": "RefreshInProgress",
                "progress": 42,
                "externalSource": "{\"type\":\"volume\",\"path\":\"volume://my-volume/movies\"}",
                "startTime": 1712833000000,
                "endTime": 0
            }
        ]
    }
}