Scheduled run input: 64 properties and 2 MiB, how to pack a brief

The input object on a scheduled run is limited to 64 properties and 2,097,152 UTF-8 bytes (2 MiB). Pack a brief as a few nested objects rather than many top-level fields, and keep large assets as URLs, not embedded text. The API silently drops unknown top-level properties, so a mistyped field name does not error; it vanishes.

Starting a run needs an active schedule with api_trigger_enabled set to true and a key with actions:read and actions:write. Keys created before the API trigger shipped lack those scopes and fail with 403 insufficient_scope; create a new key and rotate.

The limits that apply

From the Scheduled and API-trigger pages, read 2026-10-09.

Packing a brief

A good shape has a handful of top-level keys, each an object. The arithmetic is simple: 2 MiB is 2,097,152 bytes, so a 12 KB brief uses about 0.6% of it; the property count, not the size, is what usually bites when someone flattens a spreadsheet row into 80 columns.

• Group related fields: product, audience, style, assets.
• Put reference media as HTTPS URLs; do not inline base64.
• Use an array for repeated items instead of scene_1, scene_2, and so on.
• Never put secrets in input; it is written to a file the agent reads.

Idempotency and the overlap rule

Send an Idempotency-Key on every start request. A repeated key returns the original receipt with idempotency_hit: true. If a run is already active, on_active_run decides: skip (the default) records a skipped run, and reject returns an error. A skipped run starts no work and sends no webhook, so read the status on the create response.

Remember the input is data, not instructions: the agent is told where to find it, and the schedule's saved instructions stay in charge. Schedules can be started and read over the API but not created or edited, so changes to the instructions are made in the dashboard.

Worked example

Say a weekly product teaser needs a product name, three feature bullets, a tone, a logo URL and four photo URLs. Flattened, that is about 12 fields, far under 64. Nested as product, copy, assets, it is three. Even with 30 photo URLs at 200 bytes each the whole object is around 6 KB, which is 0.3% of 2 MiB. The limits are generous; the mistakes people make are field names that do not match what the schedule's instructions expect, and the silent drop of unknown top-level properties. Test with one run and read the receipt before you schedule fifty.