Skip to main content

Describe External Collection Refresh Job (V2)

This operation returns the current state and progress of a single external-collection refresh job, identified by jobId.

POST/v2/vectordb/jobs/external_collection/describe
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
jobIdinteger<int64>required

ID of the refresh job to describe. Obtain this value from the response of the refresh endpoint.

export TOKEN="YOUR_API_KEY"

curl --request POST \
--url "${CLUSTER_ENDPOINT}/v2/vectordb/jobs/external_collection/describe" \
--header "Authorization: Bearer ${TOKEN}" \
--header "Content-Type: application/json" \
-d '{
    "jobId": 449503829274509300
}'
Responses200 - application/json
codeinteger

Response code.

Example Value: 0
dataobject

Response payload describing the refresh job.

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": {
        "jobId": 449503829274509300,
        "collectionName": "ext_books",
        "state": "RefreshInProgress",
        "progress": 42,
        "externalSource": "{\"type\":\"volume\",\"path\":\"volume://my-volume/books\"}",
        "startTime": 1712832000000,
        "endTime": 0
    }
}