> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wherobots.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Scripts and processing windows

> Read processing windows, pass arguments, and manage script locations and execution settings.

Configure the script inputs for a [task schedule](https://docs.wherobots.com/develop/task-schedules/create-a-schedule.md), and use its supplied window to select the data to process.

## Environment variables

Wherobots sets these environment variables for a scheduled script:

| Variable | Set for | Format |
| - | - | - |
| `WBC_TASK_RUN_ID` | Every task run | The task run ID, for example `r4hz6m2pc9yvqe`. |
| `WBC_WINDOW_START` | Every run of a schedule, scheduled or run-now | Inclusive window start, in UTC at whole-second precision: `YYYY-MM-DDTHH:MM:SSZ`, for example `2026-10-25T00:00:00Z`. |
| `WBC_WINDOW_END` | Every run of a schedule, scheduled or run-now | Exclusive window end, in the same format. |

Read the supplied window rather than computing it from the clock. See [Processing windows](#processing-windows) for how Wherobots sets the bounds.

You can't set your own environment variables on a schedule, and the `WBC_` prefix is reserved. Pass configuration to the script in **Arguments** (`args` in the API).

## Script inputs

Configure these settings in the schedule form. API requests supply them in `task.inputs` and `triggerInputs`, using the same settings as a [Job Run](https://docs.wherobots.com/reference/runs.md):

| API input | Schedule form label | Default | Description |
| - | - | - | - |
| `runtime` | Runtime | Organization default | The runtime size, for example `tiny`, `small` or `x-large`. See [Runtimes](https://docs.wherobots.com/develop/runtimes.md). Use the lowercase IDs; the uppercase IDs, such as `TINY` and `XLARGE`, are legacy and will be deprecated. |
| `version` | Runtime version | Organization default | The WherobotsDB version. |
| `timeoutSeconds` | Timeout (seconds) | `3600` | The execution time limit, in seconds, measured from when execution starts. Queue and startup time are excluded. A run that exceeds it ends as `TIMED_OUT`. |
| `args` | Arguments | `[]` | A list of strings passed to the script as command-line arguments. The total size is limited to 64 KiB. |
| `environment` | Advanced execution settings | `{}` | Spark settings: `sparkConfigs`, `dependencies`, `sparkDriverDiskGB` and `sparkExecutorDiskGB`, as for [Job Runs](https://docs.wherobots.com/reference/runs.md). These configure Spark; they don't set environment variables. |

> [!WARNING]
>
> Arguments and other inputs are visible to everyone in your Organization, and arguments also appear in each run's logs. Pass configuration paths or non-sensitive settings in **Arguments** (`args` in the API).

## Script location and changes

* The script you select is stored as `definition.uri` in the API. Its location must be an `s3://` URI with a bucket and object key. Whitespace, query strings and fragments aren't supported.
* Choose a location using [Store the script](https://docs.wherobots.com/develop/task-schedules/create-a-schedule.md#store-the-script). The task run must be able to read it using the schedule's **Run as** identity (`runAs` in the API).
* The schedule doesn't copy or pin the script. Each task run reads the selected file when it starts, so overwriting the file changes every later run. To keep a version fixed, upload it under a new name and select that file in the schedule, or update `definition.uri` through the API.
* Choose the region when you create the schedule. To run the script in another region, create another schedule.

## Write repeatable outputs

Use the supplied window to select input records and name outputs. Write outputs so repeating the same window replaces or deduplicates its results. An attempt is one try at processing a window. A task run ID identifies an attempt; use the window bounds when identifying the data being processed.

## Nominal time and actual start

A tick is the nominal scheduled time. Wherobots submits the run and starts its compute afterward. Your script's window stays tied to the nominal times even when execution starts late.

For an interval shorter than a day, the first run is scheduled about two minutes after Wherobots applies the new schedule or a changed interval. It can occur before a full interval has elapsed since creation. Resuming normally keeps the existing timing. Allow additional time for Wherobots to apply changes and start compute.

Observed run submission delays are about a minute, with compute startup taking another 20 seconds to a few minutes. These are observations, not a service-level agreement or guaranteed start times. Check the displayed next scheduled time after creating, editing, or resuming a schedule.

## Processing windows

A processing window is the time range a run processes. Each run receives `[windowStart, windowEnd)`: include records at the start and exclude records at the end. Scheduled windows end at the current tick and begin at the previous tick. After creation, resume, or an execution-affecting edit, the next window starts no earlier than that change. Read the supplied [environment variables](#environment-variables).

The journal is the schedule's record of ticks, gaps, and their outcomes. A gap records uncovered time between windows. Manual runs appear separately in history.

Coverage begins with the first tick. An edit before that tick does not create a recoverable gap for the earlier active span.

An **execution-affecting edit** changes the script definition, arguments or runtime settings, **Run as** identity, or timing configuration. These changes start a new epoch, a period with one execution configuration. Creation also starts an epoch. For resume behavior, see [Edit or stop scheduling](https://docs.wherobots.com/develop/task-schedules/monitor-and-recover.md#edit-or-stop-scheduling). Renaming a schedule or changing notification emails does not start a new epoch.

The next window can be shorter than the cadence. Already-submitted execution requests retain their captured settings. After coverage begins, uncovered active time across an epoch boundary can become a recoverable gap. Pausing can record the uncovered active time up to the pause as a recoverable gap. The deliberately paused period is excluded.

## Overlap

If the previous scheduled run is still active, the next scheduled tick is recorded as `SKIPPED` because of overlap. Its window stays unprocessed. The following window does not expand to include it. [Rerun the skipped entry](https://docs.wherobots.com/develop/task-schedules/monitor-and-recover.md#recover-a-window) to process that window.

## Timezones and daylight saving time

All intervals measure elapsed time. A one-day interval means 24 hours, so its local clock time can shift when daylight saving time changes. The timezone on a daily or weekly interval helps specify the initial start time; it does not convert the interval into a calendar recurrence.

Cron follows the selected timezone's calendar. For `0 6 * * *` in `America/Los_Angeles`, ticks occur at 06:00 local time. During the spring clock change, a cron time in the missing hour does not occur. During the autumn clock change, a time in the repeated hour occurs twice at distinct Coordinated Universal Time (UTC) instants. Processing windows can therefore have different elapsed lengths.

## Run now and backfill

**Run now** starts a manual execution with explicit **Window start** (inclusive) and **Window end** (exclusive) bounds. Review the editable defaults. Select **Use most recent scheduled window** when available, or **Use past 24 hours** to select a recent window. The Cloud UI shows the bounds in the time zone from your [Settings preferences](https://cloud.wherobots.com/settings#preferences). The start must precede the end. The API requires timezone-aware timestamps for both bounds, including for scripts that ignore the window. Wherobots converts them to UTC without aligning them to the schedule or clamping them.

Run now works before the scheduler has applied a new configuration and while a schedule is paused or auto-disabled. Manual runs can overlap scheduled runs, reruns, or other manual runs. Quota and billing still apply.

Manual runs aren't linked to a scheduled time, so they don't fill journal gaps, even if their bounds match a missing window. For historical backfill, [recover the recorded tick or gap](https://docs.wherobots.com/develop/task-schedules/monitor-and-recover.md#recover-a-window).

## Next steps

> [card] [Create a schedule](https://docs.wherobots.com/develop/task-schedules/create-a-schedule.md)
>
> Configure and verify recurring execution.

> [card] [Monitor and recover](https://docs.wherobots.com/develop/task-schedules/monitor-and-recover.md)
>
> Inspect attempts and recover unprocessed windows.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.