Run job

POST 
/metalakes/:metalake/jobs/runs

Starts a job from a job template and returns the new job in the queued status. Values in jobConf replace the matching {{name}} placeholders in the template.

Sign in with a bearer token or a local user's password; see Authentication.

Request

Path Parameters

metalake stringrequired

The name of the metalake

application/json

Body

jobTemplateName stringrequired

The name of the job template to run

jobConf

object

The job configuration for the job run

property name* string

Responses

200

The new job in the queued status, with its ID, template name, queue time and the resolved template that will be submitted.

application/vnd.gravitino.v1+json

Schema

Schema

code int32

Possible values: [0]

Status code of the response

job

object

A job object

jobId stringrequired

The unique identifier of the job

jobTemplateName stringrequired

The name of the job template used to create the job

status stringrequired

Possible values: [queued, started, failed, succeeded, cancelling, cancelled]

The status of the job

audit

object

required

Audit information for a Gravitino resource.

creator string

The user who created the resource

createTime date-time

The time the resource was created

lastModifier string

The user who last modified the resource

lastModifiedTime date-time

The time the resource was last modified

queuedAt date-timerequired

The time when the job was queued for execution, same as the job's creation time

startedAt date-timenullable

The time when the job started execution, or null if the job has not started execution yet

finishedAt date-timenullable

The time when the job finished execution, or null if the job has not finished execution yet

runtimeJobTemplate

object

nullable

oneOf

ShellJobTemplate

A job template object for shell jobs

name stringrequired

The name of the job template

jobType stringrequired

Possible values: [shell]

The type of the job template

comment stringnullable

A comment about the job template

executable stringrequired

The executable command of the job template

arguments string[]nullable

The arguments of the job template

environments

object

Configured string to string map of environment variables for the job template

property name* string

customFields

object

Configured string to string map of custom fields for the job template

property name* string

scripts string[]nullable

The scripts of the job template

audit

object

Audit information for a Gravitino resource.

creator string

The user who created the resource

createTime date-time

The time the resource was created

lastModifier string

The user who last modified the resource

lastModifiedTime date-time

The time the resource was last modified

SparkJobTemplate

A job template object for Spark jobs

name stringrequired

The name of the job template

jobType stringrequired

Possible values: [spark]

The type of the job template

comment stringnullable

A comment about the job template

executable stringrequired

The executable command of the job template

arguments string[]nullable

The arguments of the job template

environments

object

Configured string to string map of environment variables for the job template

property name* string

customFields

object

Configured string to string map of custom fields for the job template

property name* string

className stringnullable

The main class of the Spark job template. Required for Java/Scala Spark applications, optional for PySpark applications

jars string[]nullable

The JAR files of the Spark job template

files string[]nullable

The files of the Spark job template

archives string[]nullable

The archives of the Spark job template

configs

object

Configured string to string map of Spark configurations for the job template

property name* string

audit

object

Audit information for a Gravitino resource.

creator string

The user who created the resource

createTime date-time

The time the resource was created

lastModifier string

The user who last modified the resource

lastModifiedTime date-time

The time the resource was last modified

Example (from schema)

{
  "code": 0,
  "job": {
    "jobId": "string",
    "jobTemplateName": "string",
    "status": "queued",
    "audit": {
      "creator": "string",
      "createTime": "2024-07-29T15:51:28.071Z",
      "lastModifier": "string",
      "lastModifiedTime": "2024-07-29T15:51:28.071Z"
    },
    "queuedAt": "2024-07-29T15:51:28.071Z",
    "startedAt": "2024-07-29T15:51:28.071Z",
    "finishedAt": "2024-07-29T15:51:28.071Z",
    "runtimeJobTemplate": {
      "name": "string",
      "jobType": "shell",
      "comment": "string",
      "executable": "string",
      "arguments": [
        "string"
      ],
      "environments": {},
      "customFields": {},
      "scripts": [
        "string"
      ],
      "audit": {
        "creator": "string",
        "createTime": "2024-07-29T15:51:28.071Z",
        "lastModifier": "string",
        "lastModifiedTime": "2024-07-29T15:51:28.071Z"
      }
    }
  }
}

JobRunResponse

{
  "code": 0,
  "job": {
    "jobId": "job-12345",
    "jobTemplateName": "test_run_get",
    "status": "queued",
    "audit": {
      "createTime": "2025-08-12T02:14:28.205023Z",
      "creator": "anonymous"
    },
    "queuedAt": "2025-08-12T02:14:28.205023Z",
    "runtimeJobTemplate": {
      "name": "test_run_get",
      "jobType": "shell",
      "comment": "Test shell job template",
      "executable": "/tmp/gravitino-job-staging/job-12345/test-job.sh",
      "arguments": [
        "value1",
        "value2"
      ],
      "environments": {},
      "customFields": {},
      "scripts": [
        "/tmp/gravitino-job-staging/job-12345/common.sh"
      ],
      "audit": {
        "createTime": "2025-08-12T02:00:00.000000Z",
        "creator": "anonymous"
      }
    }
  }
}

400

The job executor cannot start the job, for example because a required executor setting such as the Spark home is not configured.

application/vnd.gravitino.v1+json

Schema

Schema

code integerrequired

Possible values: >= 1000 and <= 1100

HTTP response code

type stringrequired

Internal type definition of the error

message stringrequired

A human-readable message

stack string[]deprecated

Deprecated diagnostic stack trace. Enterprise omits it by default because it can expose internal implementation details. Operators can opt in for controlled diagnostics with gravitino.server.webserver.includeErrorStackTrace=true. See OWASP REST Security: Error handling and CWE-209.

Example (from schema)

{
  "code": 1002,
  "type": "string",
  "message": "string"
}

JobRunIllegalArgumentException

{
  "code": 1001,
  "type": "IllegalArgumentException",
  "message": "Failed to operate job(s) operation [RUN] under object [my_test_metalake], reason [gravitino.jobExecutor.local.sparkHome or SPARK_HOME environment variable must be set for Spark jobs]",
  "stack": [
    "java.lang.IllegalArgumentException: gravitino.jobExecutor.local.sparkHome or SPARK_HOME environment variable must be set for Spark jobs",
    "..."
  ]
}

404

The metalake or job template does not exist.

application/vnd.gravitino.v1+json

Schema

Schema

code integerrequired

Possible values: >= 1000 and <= 1100

HTTP response code

type stringrequired

Internal type definition of the error

message stringrequired

A human-readable message

stack string[]deprecated

Deprecated diagnostic stack trace. Enterprise omits it by default because it can expose internal implementation details. Operators can opt in for controlled diagnostics with gravitino.server.webserver.includeErrorStackTrace=true. See OWASP REST Security: Error handling and CWE-209.

Example (from schema)

{
  "code": 1002,
  "type": "string",
  "message": "string"
}

NoSuchJobTemplateException

{
  "code": 1003,
  "type": "NoSuchJobTemplateException",
  "message": "Failed to operate job template(s) [my_job] operation [GET] under metalake [my_test_metalake], reason [NoSuchJobTemplateException]",
  "stack": [
    "org.apache.gravitino.exceptions.NoSuchJobTemplateException: Job template xxx does not exist",
    "..."
  ]
}

5xx

The server hit an internal error that the client usually cannot fix by changing the request.

application/vnd.gravitino.v1+json

Schema

Schema

code integerrequired

Possible values: >= 1000 and <= 1100

HTTP response code

type stringrequired

Internal type definition of the error

message stringrequired

A human-readable message

stack string[]deprecated

Deprecated diagnostic stack trace. Enterprise omits it by default because it can expose internal implementation details. Operators can opt in for controlled diagnostics with gravitino.server.webserver.includeErrorStackTrace=true. See OWASP REST Security: Error handling and CWE-209.

Example (from schema)

{
  "code": 1002,
  "type": "string",
  "message": "string"
}

Example

{
  "code": 1002,
  "type": "RuntimeException",
  "message": "Internal Server Error",
  "stack": [
    "java.lang.RuntimeException: Internal Server Error"
  ]
}

Loading...