---
title: Understanding Serverless Jobs API v1alpha2
description: Discover the new features and changes introduced in the Serverless Jobs API v1alpha2, including updated command definitions and troubleshooting tools.
tags: jobs serverless-jobs api v1alpha2 command startup-command
dates:
  validation: 2025-12-16
  posted: 2025-12-16
---

The Serverless Jobs API `v1alpha2` is now available. This version introduces improvements to how you define job execution commands and provides better context for debugging failed job runs.

We recommend using `v1alpha2` for all new integrations via the API, SDK, Terraform, and CLI.

<Message type="note">
  The `v1alpha1` and `v1alpha2` versions currently coexist. You can continue to use `v1alpha1`, but we encourage migrating to `v1alpha2` to benefit from the latest features.
</Message>

## Key changes

### Job definition command

In `v1alpha2`, the `command` field for Job definitions is **deprecated**.

It is replaced by two new fields, designed to give you more control and align with the [Serverless Containers](/serverless-containers/concepts/#serverless-containers) experience:

* **`startup_command`**: A list of commands to start the application.
* **`args`**: A list of arguments passed to the startup command.

This separation allows for a cleaner definition of entry points and arguments, mirroring standard container practices.

Refer to the [dedicated documentation](/serverless-jobs/how-to/migrate-command-to-startup-command/) for more information on how to migrate from the legacy **command** to **startup command and arguments**.

### Job run troubleshooting

To assist with debugging, `v1alpha2` adds a **Job Run Reason** field.

This field is automatically populated when a Job Run enters a **failed** or **interrupted** state. It provides specific context regarding why the run did not complete successfully, helping you identify and resolve issues faster.

## Migration steps

If you currently use `v1alpha1` in your automation tools, we recommend updating your configuration to support `v1alpha2`.

### Terraform and CLI

Ensure you update your [Scaleway Provider](/terraform/quickstart/) or [Scaleway CLI](/scaleway-cli/quickstart/) to the latest version to access `v1alpha2` fields.

When defining Jobs, replace the deprecated `command` field with the new structure.

**Example configuration (Terraform-style pseudocode):**

```hcl
# Old (v1alpha1)
resource "scaleway_job_definition" "main" {
  command = "python app.py --verbose"
}

# New (v1alpha2)
resource "scaleway_job_definition" "main" {
  startup_command = ["python"]
  args    = ["app.py", "--verbose"]
}