---
# @generated by sylphx-gen 0.1.0 from contracts@e145cc7cf1bc9605f2b27439e5e17ed76a1a2fd7e7021906a013f7565e4a0cd5. Do not edit.
title: "Distributed jobs"
description: "The `distributed_jobs` collection of Sylphx Workflows: A DistributedJob runs one container image on many workers at once."
type: reference
product: jobs
summary: "A DistributedJob runs one container image on many workers at once."
updated: 2026-09-28
order: 900
---

> **This method is not served on the public API.** `api.sylphx.com` does not route this call: its backend is not deployed behind the public API, or does not implement the call. This page documents the contract. It is kept out of the sidebar and of search engines.

A DistributedJob runs one container image on many workers at once. A run splits its work into shards that workers lease from a queue; the worker pool grows and shrinks with the capacity Kueue admits, and a preempted shard goes back to the queue.

**Service** Sylphx Workflows · **Resource type** `workflows.sylphx.com/DistributedJob` · **Name pattern** `orgs/{org}/projects/{project}/envs/{env}/distributed_jobs/{distributed_job}` · **Shape** `spec_status`

## Fields

| Field | Type | What it is |
| --- | --- | --- |
| `name` | `string` | `orgs/{org}/projects/{project}/envs/{env}/distributed_jobs/{distributed_job}`. |
| `uid` | `string` | `djob_<cell><ulid>`; never reused. Output only. |
| `meta` | `ResourceMeta` | Resource metadata. |
| `spec` | `DistributedJobSpec` | Desired state. Required. |
| `status` | `DistributedJobStatus` | Observed state. Output only. |

## Methods

Every method of the collection, in the registry's order, with the scope it
needs. The full request, response and examples are one link away.

| Method | Call | What it does |
| --- | --- | --- |
| `GET` | [`get`](/docs/api/distributed_jobs#get) | Gets a distributed job. |
| `GET` | [`list`](/docs/api/distributed_jobs#list) | Lists distributed jobs. |
| `POST` | [`create`](/docs/api/distributed_jobs#create) | Creates a distributed job. |
| `PATCH` | [`update`](/docs/api/distributed_jobs#update) | Updates a distributed job. Runs already started keep the generation they pinned. |
| `DELETE` | [`delete`](/docs/api/distributed_jobs#delete) | Deletes a distributed job. |

## get

Gets a distributed job.

`GET https://api.sylphx.com/v1/orgs/acme/projects/shop/envs/production/distributed_jobs/distributed-job` · scope `workflows:read` · effect `read` · [Request, response and examples](/docs/api/distributed_jobs/get)

## list

Lists distributed jobs.

`GET https://api.sylphx.com/v1/orgs/acme/projects/shop/envs/production/distributed_jobs` · scope `workflows:read` · effect `read` · paginated · [Request, response and examples](/docs/api/distributed_jobs/list)

## create

Creates a distributed job.

`POST https://api.sylphx.com/v1/orgs/acme/projects/shop/envs/production/distributed_jobs` · scope `workflows:write` · effect `write` · long-running · [Request, response and examples](/docs/api/distributed_jobs/create)

## update

Updates a distributed job. Runs already started keep the generation they pinned.

`PATCH https://api.sylphx.com/v1/orgs/acme/projects/shop/envs/production/distributed_jobs/distributed-job` · scope `workflows:write` · effect `write` · long-running · [Request, response and examples](/docs/api/distributed_jobs/update)

## delete

Deletes a distributed job.

`DELETE https://api.sylphx.com/v1/orgs/acme/projects/shop/envs/production/distributed_jobs/distributed-job` · scope `workflows:write` · effect `destructive` · long-running · [Request, response and examples](/docs/api/distributed_jobs/delete)