Manage job execution in TypeScript

Use the Blaxel TypeScript SDK to start, monitor, retry, and cancel batch job executions, with examples for input data and execution state.

You can programmatically execute and manage batch jobs using the Blaxel API and TypeScript SDK.

The code examples in this section assume that your batch job has already been successfully deployed on Blaxel.

Dispatch job execution

Dispatch a job and wait for execution to start:

import { blJob } from "@blaxel/core";

const job = blJob("my-job");
const executionId = await job.createExecution({
  tasks: [{ duration: 60 }]
});
const result = await job.waitForExecution(executionId);

Time units in the TypeScript SDK are specified in milliseconds.

Dispatch job execution with tasks

Dispatch a new job with tasks:

const executionId = await job.createExecution({
  tasks: [
    { duration: 30 },
    { duration: 60 },
  ]
});

Get execution details

Get full execution details:

const execution = await job.getExecution(executionId);
console.log(execution.status, execution.metadata);

Get status

The possible job states are:

pending → running → completed
                 ↘ failed

Get only the job status (faster than retrieving full execution details):

const status = await job.getExecutionStatus(executionId);
// Returns: "pending" | "running" | "completed" | "failed"

List executions

List all executions for a job:

const executions = await job.listExecutions();
console.log(`Found ${executions.length} executions`);

Wait for completion

Poll until execution completes:

const result = await job.waitForExecution(executionId, {
  maxWait: 300000,  // 5 minutes (milliseconds)
  interval: 2000,   // Poll every 2 seconds (milliseconds)
});

When polling:

• adjust the interval based on the expected task duration
• set the maxWait timeout longer than the expected total task duration

Override environment and memory for a single job execution

Override memory and/or environment variables for a single job execution, without modifying the deployed job configuration:

import { blJob } from "@blaxel/core"

const job = blJob("my-job")

const executionId = await job.createExecution({
  tasks: [{ name: "Combined" }],
  memory: 1024, // MB (must be <= deployed job memory)
  env: {
    TEST_MODE: "true",
    LOG_LEVEL: "debug",
  },
})

const execution = await job.getExecution(executionId)

console.log(execution.status)

• Memory overrides are expressed in MB and are downward-only: the value must be <= the memory configured at deployment time. For example, if the job is deployed with 4096 MB, execution overrides must be <= 4096 MB.
• env supports multiple environment variables
• memory and env can be set independently or together
• Overrides apply only to the current execution

Reject immediately when capacity is unavailable

By default, when your workspace is at its capacity limit, a new execution is accepted, queued, and retried in the background until capacity frees up. Set allowQueue: false to instead check capacity synchronously at creation time and get an immediate error if the execution cannot start right now:

const executionId = await job.createExecution({
  tasks: [{}],
  allowQueue: false,
});

• allowQueue omitted or true: the execution is queued and retried in the background (default behavior)
• allowQueue: false: the request returns a 429 error if capacity is unavailable right now, or a 400 error if the request can never fit within the workspace quota
• On rejection, no execution is created and nothing is queued, so there is nothing to poll or clean up

Complete example

Here is a complete example:

import { blJob } from "@blaxel/core";

const job = blJob("data-processing");

// create execution
const executionId = await job.createExecution({
  tasks: [{"name": "John"}, {"name": "Jane"}]
});

// monitor
let status = await job.getExecutionStatus(executionId);
console.log(`Status: ${status}`);

// wait
try {
  const result = await job.waitForExecution(executionId, {
    maxWait: 180000,
    interval: 5000,
  });
  console.log(`Completed: ${result.status}`);
} catch (error) {
  console.log(`Timeout: ${error.message}`);
}

Deploy a job

Learn how to deploy your AI batch jobs on Blaxel as a serverless auto-scalable endpoint.