Start

Agents

App store purchases

Auth

Builds

Credits

Database

Flags

Generated Assets

Hosting

Jobs and cron

Knowledge

Localization

Monitoring

Network

Notifications

Organizations

Queues

Realtime

Runners

Sandboxes

Storage

Webhooks

Workflows

Getting Started

Installation

Authentication

AI Services

KV Store

Overview

Webhooks

Deploy & Infrastructure

Reference

On this page

run
get
list
cancel
add-shards
read-shards
read-workers

Reference

sylphx workflows distributed_runs

Every sylphx workflows distributed_runs command: its argument, its flags and a run line.

Checked 2026-09-28

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.

The distributed_runs commands of Sylphx Workflows, as the CLI spells them: the same calls as the distributed_runs API page, typed for the shell. Install, sign in and the grammar are on the CLI index.

#run

Starts a run of a distributed job. The same Idempotency-Key returns the same run for 24h.

ID — The id segment of the new Resource's name; the server assigns one when omitted.

CLI

Shell

sylphx workflows distributed-runs run --parent orgs/acme/projects/shop/envs/production/distributed_jobs/distributed-job

POST https://api.sylphx.com/v1/orgs/acme/projects/shop/envs/production/distributed_jobs/distributed-job/distributed_runs · scope workflows:run · effect write · Request, response and examples

Flags

Flag	Type	What it does
`--parent`	`string`	The parent to create in; defaults to the linked project or the key's scope.
`--meta.labels`	`key=value`	Caller-writable, indexed labels (AIP-122 label rules). Repeat the flag for each value.
`--meta.annotations`	`key=value`	Caller-writable, unindexed annotations. Repeat the flag for each value.
`--meta.display-name`	`string`	Caller-writable human-readable name.
`--args`	`string`	Arguments of every worker of this run (the job's when empty). Repeat the flag for each value.
`--env`	`key=value`	Environment overrides of this run. Repeat the flag for each value.
`--shards`	`json`	The run's own shards (the customer's planner output); without them the job's `shard_count` makes index-only shards. Repeat the flag for each value.
`--open-manifest`	`bool`	Keep the manifest open: `:addShards` appends until it is closed.
`--dry-run`	`bool`	Validate and print the result without writing (validate_only).

#get

Gets a distributed run: its state, shard and worker counts, and usage.

NAME — the resource's name; a bare id is enough below the linked project.

CLI

Shell

sylphx workflows distributed-runs get orgs/acme/projects/shop/envs/production/distributed_jobs/distributed-job/distributed_runs/distributed-run

GET https://api.sylphx.com/v1/orgs/acme/projects/shop/envs/production/distributed_jobs/distributed-job/distributed_runs/distributed-run · scope workflows:read · effect read · Request, response and examples

#list

Lists a distributed job's runs, newest first.

PARENT — optional: the CLI fills it from the linked project or the key's scope when it is left out.

CLI

Shell

sylphx workflows distributed-runs list orgs/acme/projects/shop/envs/production/distributed_jobs/distributed-job

GET https://api.sylphx.com/v1/orgs/acme/projects/shop/envs/production/distributed_jobs/distributed-job/distributed_runs · scope workflows:read · effect read · Request, response and examples

Flags

Flag	Type	What it does
`--page-size`	`int`	At most this many; default 50, clamped to 1000.
`--page-token`	`string`	`next_page_token` of the previous page.
`--filter`	`string`	AIP-160 filter over labels and filterable fields.
`--order-by`	`string`	AIP-132 ordering over filterable fields.

#cancel

Cancels a distributed run: workers get SIGTERM and 30s, then leases are released; finished shards are kept. A closed run fails with INVALID_STATE.

NAME — the resource's name; a bare id is enough below the linked project.

CLI

Shell

sylphx workflows distributed-runs cancel orgs/acme/projects/shop/envs/production/distributed_jobs/distributed-job/distributed_runs/distributed-run --yes

POST https://api.sylphx.com/v1/orgs/acme/projects/shop/envs/production/distributed_jobs/distributed-job/distributed_runs/distributed-run:cancel · scope workflows:run · effect destructive · Request, response and examples

Flags

Flag	Type	What it does
`--reason`	`string`	Why the run is cancelled.
`--yes`	`bool`	Do not ask before this destructive call.

#add-shards

Appends shards to a run started with an open manifest; close ends the manifest, and the run ends once those shards are done.

NAME — the resource's name; a bare id is enough below the linked project.

CLI

Shell

sylphx workflows distributed-runs add-shards orgs/acme/projects/shop/envs/production/distributed_jobs/distributed-job/distributed_runs/distributed-run

POST https://api.sylphx.com/v1/orgs/acme/projects/shop/envs/production/distributed_jobs/distributed-job/distributed_runs/distributed-run:addShards · scope workflows:run · effect write · Request, response and examples

Flags

Flag	Type	What it does
`--shards`	`json`	The shards to append. Repeat the flag for each value.
`--close`	`bool`	Close the manifest: the run ends once its shards are done.

#read-shards

Reads a page of the run's shards, in queue order.

NAME — the resource's name; a bare id is enough below the linked project.

CLI

Shell

sylphx workflows distributed-runs read-shards orgs/acme/projects/shop/envs/production/distributed_jobs/distributed-job/distributed_runs/distributed-run

GET https://api.sylphx.com/v1/orgs/acme/projects/shop/envs/production/distributed_jobs/distributed-job/distributed_runs/distributed-run:readShards · scope workflows:read · effect read · Request, response and examples

Flags

Flag	Type	What it does
`--page-size`	`int`	At most this many; default 100, clamped to 1000.
`--page-token`	`string`	`next_page_token` of the previous page.
`--state-filter`	`enum`	Only shards in this state; unset reads every shard. One of `pending`, `leased`, `succeeded`, `failed`.

#read-workers

Reads a page of the run's workers.

NAME — the resource's name; a bare id is enough below the linked project.

CLI

Shell

sylphx workflows distributed-runs read-workers orgs/acme/projects/shop/envs/production/distributed_jobs/distributed-job/distributed_runs/distributed-run

GET https://api.sylphx.com/v1/orgs/acme/projects/shop/envs/production/distributed_jobs/distributed-job/distributed_runs/distributed-run:readWorkers · scope workflows:read · effect read · Request, response and examples

Flags

Flag	Type	What it does
`--page-size`	`int`	At most this many; default 100, clamped to 1000.
`--page-token`	`string`	`next_page_token` of the previous page.

Was this page helpful?

Tell us what is missing, wrong, or unclear — this opens a real inbox.

Send feedback

Platform links