dry_run, which validates and returns the would-be outcome without applying it.
Tool index
Each tool name links to its section below.Run inspection
list_runs
Read-only. Lists recent job runs (executions) in the account, most recent first. Each run is one execution of a package. Defaults to root runs only, so child retries are excluded. Filter bypackage_id or status.
integer
default:"50"
Maximum runs to return. 1 to 200.
integer
default:"0"
Number of runs to skip, for paging.
integer
Restrict to runs of a single package.
string
Filter by run status. One of
idle, pending, queued, running, completed, failed, stopped.array
Each run includes
id, package_id, status, owner_id, cluster_id, started_at, completed_at, failed_at, runtime_seconds, progress, attempts, created_at, updated_at, and last_error (present for failed or stopped runs, with sensitive values redacted).object
offset, limit, and returned (the number of runs on this page).get_run
Read-only. Returns details for a single run by id: the same fields aslist_runs, plus an output count and a redacted tail of the execution log for inline diagnosis. Run variables are deliberately not exposed.
integer
required
The run to fetch.
integer
default:"20"
How many trailing log lines to return. 1 to 200.
integer
The run id, alongside
package_id, status, owner_id, cluster_id, started_at, completed_at, failed_at, runtime_seconds, progress, attempts, created_at, updated_at, and last_error (for failed or stopped runs, redacted).integer
Number of outputs the run produced.
string
The last N lines of the execution log, redacted.
null when no log body exists.explain_job_failure
Read-only. Diagnoses a failed run without an LLM call on the server. Returns the run’s primary error, programmatically detected error patterns (FATAL, ERROR, exception, connection, auth, schema, and more), a redacted log tail, and heuristic next-step suggestions. The calling agent does the final synthesis.integer
required
The run to diagnose.
integer
default:"50"
How many trailing log lines to return. 1 to 200.
integer
The run id, with
package_id, status, and failed_at.string
The run’s primary error message (from
last_error), redacted. null for runs that did not fail or stop.array
Structured error patterns found in the log, each with a
type such as connection_failure, auth_failure, schema_error, destination_conflict, rate_limited, out_of_memory, or exception.string
The redacted trailing log lines, with
log_lines_returned and log_truncated alongside.array
Heuristic next steps tied to the detected patterns (for example, run
test_connection on a refused connection, or discover_schema on a schema mismatch).Schedules
list_schedules
Read-only. Lists schedules in the account. Each schedule fires on a cron expression or an interval. Filter bypackage_id (schedules targeting a given package) or status.
integer
default:"50"
Maximum schedules to return. 1 to 200.
integer
default:"0"
Number of schedules to skip, for paging.
string
Filter by schedule status. One of
enabled, disabled.integer
Return only schedules whose task targets this package.
array
Each schedule includes
id, name, description, status, schedule_type, schedule_expression, interval_amount, interval_unit, cron_time_zone, start_at, end_at, next_run_at, last_run_at, last_run_status, execution_count, recurrence_count, package_ids, owner_id, created_at, and updated_at.object
offset, limit, and returned.get_schedule
Read-only. Returns full details for a single schedule by id, including the packages it targets with their per-package variables, the task config, and run metadata.integer
required
The schedule to fetch.
integer
The schedule id, with
name, description, status, schedule_type, schedule_expression, interval_amount, interval_unit, cron_time_zone, start_at, end_at, owner_id, execution_count, recurrence_count, next_run_at, last_run_at, last_run_id, last_run_status, auto_retry, auto_retry_attempts, created_at, and updated_at.array
Each target package as
{ package_id, package_name, variables }.object
Task config:
nodes, terminate_on_idle, time_to_idle, and reuse_cluster_strategy.toggle_schedule
Mutation. Enables or disables an existing schedule. This is a pure metadata change: no credentials, no data writes, no cluster spin-up, and it is reversible by the same tool. The cron worker picks up the new state within about 60 seconds. Idempotent in both directions, an already-matching state returnsalready_in_target_state: true as a no-op. Supports dry_run, which returns the would-be transition without toggling.
integer
required
The schedule to toggle.
boolean
required
true to enable, false to disable.integer
The schedule id, with
previous_status, new_status, already_in_target_state, and toggled_at.create_schedule
Mutation. Creates a schedule that runs one or more packages on a cadence. It is created disabled by default, so an agent call will not silently start firing recurring jobs. Passstatus: "enabled" (or call toggle_schedule afterward) to activate it. Supports dry_run, which validates and returns the would-be schedule without creating it.
string
required
Schedule name. Max 255 characters.
string
required
Cadence type. One of
interval, cron.string
required
ISO-8601 timestamp for when the schedule starts. Interpreted as UTC unless
current_time_zone is set.array
required
At least one package. Each item may be
{ package_id, variables? } or a bare package id.integer
default:"1"
For
interval schedules: how many interval_unit between runs. Minimum 1.string
default:"hours"
For
interval schedules: minutes, hours, days, weeks, or months.string
For
cron schedules: the cron expression, for example 0 9 * * *.string
default:"disabled"
Initial status. One of
enabled, disabled.integer
The new schedule id, with
name, status, schedule_type, and next_run_at. On a dry_run, these are nested under would_create with a valid flag (and errors when invalid).update_schedule
Mutation. Updates an existing schedule’s cadence or metadata, toggles it, and/or appends packages. Only the fields you pass are changed.status goes through the proper enable/disable transition. add_packages only appends to the schedule’s package list: packages already on the schedule are skipped, and nothing is removed or reordered. To change the full package set, recreate the schedule. Supports dry_run.
integer
required
The schedule to update.
array
Packages to add. Each item may be
{ package_id, variables? } or a bare package id. Appends only.string
Change the schedule status through the enable/disable transition. One of
enabled, disabled.string
Change the cadence type. One of
interval, cron.string
New ISO-8601 start timestamp.
integer
The schedule id, with
name, status, schedule_type, next_run_at, and package_ids. On a dry_run, the response is nested under would_update with the changed fields, target status, and add_packages.Execution and recovery
run_package
Mutation. Starts a new run of a package on a given cluster and returns therun_id immediately, with the run in pending. It does not wait for completion: poll get_run for status. Compute charged for time the run was already executing on the cluster cannot be refunded, so cancel via cancel_job if needed. Supports dry_run, which returns the predicted state without creating a run.
integer
required
The package to run. Must not be archived.
integer
required
The cluster to dispatch to. Must not be terminated or terminating.
object
A map of variable name to value that overrides the package’s defaults for this run only. String literals must be wrapped in inner single quotes (pass
"'Smith'", not "Smith"), since $variable references are evaluated as Pig expressions. Numbers and booleans need no quoting, and values are matched case-sensitively.integer
The new run id, with
package_id, package_name, cluster_id, status, variables_applied (the overridden keys), and started_at. On a dry_run, the details are nested under would_create with a cluster_action hint.cancel_job
Mutation. Stops an in-flight run by sending the cancel signal through the run’s state machine. Anidle run stops synchronously; pending, queued, or running runs move to pending_stoppage and are stopped asynchronously (poll get_run to confirm). Idempotent: a run already cancelling returns already_cancelling: true, and a run already finished returns already_terminal: true. Not reversible once cancelled. Supports dry_run.
integer
required
The run to cancel.
integer
The run id, with
previous_status, new_status, already_terminal, already_cancelling, and cancel_requested_at (the time the cancel signal was sent, not when the run finished stopping). On a dry_run, the details are nested under would_cancel with a cluster_impact hint.retry_job
Mutation. Re-runs a finished (failed, cancelled, or completed) run by creating a fresh run that copies the parent’s package, cluster, and variables, then starts it. The new run is a sibling: the original run is preserved in its terminal status. By default,variables are merged onto the parent’s; pass replace_variables: true to use only the new hash. Supports dry_run, which returns the resolved variable set without creating the run.
integer
required
The parent run to re-run.
object
Variable overrides. Merged onto the parent’s variables by default (override wins on collision). Omit to retry exactly as the parent ran.
boolean
default:"false"
When
true, use only the supplied variables hash instead of merging onto the parent’s.integer
The new run id, with
parent_run_id, package_id, cluster_id, status, variables_applied, and started_at. On a dry_run, the details are nested under would_retry with the fully variables_resolved hash.