Skip to main content

Create Spark K-means Job (V2)

This operation creates a K-means clustering job.

POST/v2/projects/{projectId}/jobs/kmeans
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}}
Idempotency-Keystringheader

A unique key that makes repeated create requests idempotent.

Example Value: spark-job-20260814-001
projectIdstringpathrequired

The project ID.

Example Value: proj-xxxxxxxxxxxxxxxxxxxx
Request Bodyapplication/json
descriptionstring

The job description.

regionIdstringrequired

The cloud region ID.

inputobject

A data resource (input or output) reference for a Spark job.

typestringrequired

The data resource type.

volumeNamestringrequired

The volume name.

pathstringrequired

The data path within the volume.

formatstring

The data format.

writeModestring

The write mode.

dbNamestring

The database name.

collectionNamestring

The collection name.

outputobject

A data resource (input or output) reference for a Spark job.

typestringrequired

The data resource type.

volumeNamestringrequired

The volume name.

pathstringrequired

The data path within the volume.

formatstring

The data format.

writeModestring

The write mode.

dbNamestring

The database name.

collectionNamestring

The collection name.

resourceSizestring

The resource size for the job.

timeoutSecondsinteger

The timeout in seconds.

primaryKeyFieldstringrequired

The primary key field.

vectorFieldstringrequired

The vector field.

metricstring

The distance metric.

numClustersintegerrequired

The number of clusters.

Create Spark Jobbash
export TOKEN="YOUR_API_KEY"
export projectId="proj-xxxxxxxxxxxxxxxxxxxx"

curl --request POST \
--url "${BASE_URL}/v2/projects/${projectId}/jobs/kmeans" \
--header "Authorization: Bearer ${TOKEN}" \
--header "Idempotency-Key: spark-job-20260814-001" \
--header "Request-Timeout: 5" \
--header "Content-Type: application/json" \
-d '{
    "description": "Daily vector processing job.",
    "regionId": "aws-us-west-2",
    "input": {
        "type": "VOLUME",
        "volumeName": "volume-xxxxxxxxxxxxxxxxxxx",
        "path": "/input/data.parquet",
        "format": "parquet"
    },
    "output": {
        "type": "VOLUME",
        "volumeName": "volume-xxxxxxxxxxxxxxxxxxx",
        "path": "/output/results",
        "format": "parquet",
        "writeMode": "OVERWRITE"
    },
    "resourceSize": "medium",
    "timeoutSeconds": 3600,
    "primaryKeyField": "id",
    "vectorField": "embedding",
    "metric": "L2",
    "numClusters": 8
}'
Responses201 Created - application/json

Returns the created Spark job.

A success response.

codeinteger

Response code.

Example Value: 0
dataobject

Summary information about a Spark batch job.

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.

createdAtstring

Creation time (ISO 8601).

startedAtstring

Start time (ISO 8601).

finishedAtstring

Finish time (ISO 8601).

durationSecondsinteger<int64>

The duration in seconds.

A failure response.

codeinteger

Response code.

messagestring

Error message.

Successjson
{
    "code": 0,
    "data": {
        "jobId": "job-xxxxxxxxxxxxxxxxxx",
        "sparkInstanceId": "sp-xxxxxxxxxxxxxxxxxx",
        "type": "SPARK",
        "jobName": "daily-vector-job",
        "status": "PENDING",
        "regionId": "aws-us-west-2",
        "projectId": "proj-xxxxxxxxxxxxxxxxxxx"
    }
}
Ctrl I