Skip to main content

Describe Batch Job (V2)

This operation describes a batch job in a specified project.

GET/v2/projects/{projectId}/jobs/{jobId}
Connection Endpoint

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

https://api.cloud.zilliz.com

📘Notes

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

shell
export BASE_URL="https://api.cloud.zilliz.com"
Parameters
Authorizationstringheaderrequired

The authentication token should be an API key with appropriate privileges.

Example Value: Bearer {{TOKEN}}
projectIdstringpathrequired

The project ID.

Example Value: proj-xxxxxxxxxxxxxxxxxxx
jobIdstringpathrequired

The batch job ID.

Example Value: job-xxxxxxxxxxxxxxxxxx
bash
export TOKEN="YOUR_API_KEY"
export projectId="proj-xxxxxxxxxxxxxxxxxxx"
export jobId="job-xxxxxxxxxxxxxxxxxx"

curl --request GET \
--url "${BASE_URL}/v2/projects/${projectId}/jobs/${jobId}" \
--header "Authorization: Bearer ${TOKEN}" \
--header "Request-Timeout: 5" \
--header "Content-Type: application/json"
Responses200 OK - application/json

Returns details of the batch job.

One of the alternative object shapes the response body may take; a single shape applies per response.

codeinteger

Response code.

dataobject

Response payload that contains batch job details.

jobIdstringrequired

The job ID.

projectIdstringrequired

The project ID the job belongs to.

typestringrequired

The job type.

descriptionstring

The job description.

statusstringrequired

The job status.

regionIdstringrequired

The cloud region ID.

clusterIdstring

The cluster ID.

artifactobject

The output artifact produced by the job.

volumeNamestringrequired

The volume name the artifact is stored in.

pathstringrequired

The path of the artifact within the volume.

detailsobject

Details of a backfill job.

dbNamestring

The database name.

collectionNamestring

The collection name.

inputobject

A reference to job input or output data.

typestring

The data reference type.

volumeNamestring

The volume name.

pathstring

The data path within the volume.

formatstring

The data format.

fieldsarray

The target fields.

[]fieldsstring

One field name reported for the backfill job, taken from the non-empty scalar fields used to form aggregation buckets.

columnMappingobject

Source-to-target column mapping.

modestring

The backfill mode.

resourceSizestring

The resource size.

failureReasonobject

The reason a job failed.

codestring

The error code.

messagestring

The error message.

retryableboolean

Whether the job can be retried.

precheckReportobject

The precheck report for a backfill job.

passedboolean

Whether the precheck passed.

dbNamestring

The database name.

collectionNamestring

The collection name.

inputstring

The input description.

fieldsarray

The target fields.

[]fieldsstring

One field name included in the precheck report, taken from the non-empty scalar fields used to form aggregation buckets.

columnMappingobject

Source-to-target column mapping.

requiredSourceColumnsarray

The required source columns.

[]requiredSourceColumnsstring

One of the source columns required by the precheck.

errorsarray

The precheck errors.

[]errorsobject

A single precheck error.

codestring

The error code.

sourceColumnstring

The source column.

targetFieldstring

The target field.

expectedTypestring

The expected type.

actualTypestring

The actual type.

messagestring

The error message.

checkedRowsinteger<int64>

The number of checked rows.

createdAtstring

Creation time (ISO 8601).

submittedAtstring

Submission time (ISO 8601).

startedAtstring

Start time (ISO 8601).

finishedAtstring

Finish time (ISO 8601).

durationSecondsinteger<int64>

The duration in seconds.

Returns an error message.

codeinteger

Response code.

messagestring

Error message.

Successjson
{
    "code": 0,
    "data": {
        "jobId": "job-xxxxxxxxxxxxxxxxxx",
        "type": "SPARK",
        "description": "daily-vector-etl",
        "status": "RUNNING",
        "regionId": "aws-us-west-2",
        "clusterId": "in01-xxxxxxxxxxxxxxx",
        "createdAt": "2026-05-20T10:00:00Z",
        "startedAt": "2026-05-20T10:01:00Z",
        "finishedAt": null,
        "durationSeconds": 300,
        "artifact": {
            "volumeName": "stg-xxxxxxxxxxxxxxxxxxx",
            "path": "/jars/example-job.jar",
            "artifactUri": "volume://my-volume/jars/example-job.jar"
        },
        "submittedAt": "2026-05-20T10:00:30Z",
        "projectId": "proj-xxxxxxxxxxxxxxxxxxxx"
    }
}
Ctrl I