Nightly UGC ad job: Agent Completion, Format run or schedule?

For a nightly UGC ad job, call a Format run when your backend supplies new inputs each night, use a schedule when only the clock should start the work, and use an Agent Completion when the task text itself changes every call. All three run the same Sume agent and return the same kind of run receipt, so the choice is about what Sume stores for you.

A schedule stores what to do. A Format stores how to do it. An Agent Completion stores nothing, and you send the task on each call.

The three surfaces

Start from the table, then read the decision rules under it.

Decision rules for the nightly job

• Same recipe, new product row each night: a Format run. The Format keeps the house style, you send input and an Idempotency-Key.
• Same instruction at 02:00 with no caller data: a schedule. It takes a five-field cron expression and an IANA timezone.
• Someone's brief arrives as free text and you do not want to save it: an Agent Completion with messages[] or instruction.
• Many rows in one night: a bulk queue over a Format (up to 100 items, concurrency 1 to 16). Schedules and Completions have no bulk endpoint.

What differs on the wire

Schedules are authored in the dashboard at the Scheduled page, and the Developer API can list, read and start runs but cannot create or edit them. A schedule can also enable the API trigger so it accepts both a cadence and your calls.

A Completion needs the new scopes agent_completions:read and agent_completions:write, and keys created before the feature do not have them. Service-account keys cannot create Completions or Format runs.

Overlap policy also differs. A schedule defaults to skip when a run is active, while Format runs default to allow. If your nightly job can overrun into the next night, that default decides whether you get a skipped run or two concurrent ones.

One receipt shape, one webhook

Every surface accepts communication.webhook_url and sends one signed POST when the run completes or fails. The event names are action.run.terminal, format.run.terminal and agent.run.terminal, so one receiver can route on event. A canceled run and a skipped run send nothing, so read the status on the response you already have.

Authentication is the same for all three. Use a Bearer key, create the key after the feature shipped, and expect service-account keys to be refused. A new scope cannot be added to an old key, so a nightly job that starts failing with 403 insufficient_scope after a feature launch just needs a new key.

A sensible default

For a recurring ad job most teams end up with a Format for the look and either a schedule or their own cron calling the Format. Reach for Completions when you are prototyping or when the task is genuinely different every time, then promote the prompt that keeps repeating into a Format.