Skip to main content

Create a scheduled job

Section ID: Guide/jc16vrh0rg#create-a-scheduled-job

Deliver a weekday digest at 9 a.m. in the user’s chosen timezone. Prepare a receiver that turns the scheduled firing into the digest, create the calendar schedule, and show the returned next delivery time in the app.

Before enabling the schedule, implement callback verification and retry handling. Use the scheduled agent recipe when an agent writes the digest.

Recipe: deliver a weekday digest​

Section ID: Guide/jc16vrh0rg#creating-jobs

You need an authenticated user, a backend secret key and an HTTPS receiver that implements signature verification and durable acceptance.

  1. Choose the digest’s calendar time and IANA timezone with the user.

  2. Register your receiver and the payload that identifies the intended work using the cron example below.

  3. Save the returned schedule ID and show its nextTriggerAt to the user.

  4. After the first firing, check execution history and the digest result produced by your receiver.

For a single reminder use the one-shot variant; for cache maintenance use the interval variant. All three use the same receiver and recovery contract.

Schedule the weekday digest​

Section ID: Guide/jc16vrh0rg#cron-job

Use the user’s chosen timezone and weekday time in this request. See timing fields and defaults for other schedule forms.

Schedule a weekday digest while acting on behalf of its owner; replace the target URL with your endpoint.

Request example: Create a scheduled job. Example identifiers and values are illustrative; substitute authorized values.

Example request headers: X-API-Key: sk_your_key_here; X-On-Behalf-Of: user_123; Content-Type: application/json. Replace the credential and user placeholders with your own authorized values.

Use the cron expression reference when the customer needs a different calendar pattern.

Confirm and save the next scheduled time​

Section ID: Guide/jc16vrh0rg#response

Persist the returned scheduleId with your application’s reminder or digest record. Display the next trigger time in the intended timezone. If it is wrong, correct the timing through Manage jobs before relying on the schedule.

Save the returned schedule with the reminder:

Response example: Create a scheduled job. Example identifiers and values are illustrative; substitute authorized values.

Use the counter representation when displaying the reminder’s history.

Choose how long failed delivery may retry​

Section ID: Guide/jc16vrh0rg#retry-policy-defaults

Choose a delivery window appropriate for the reminder, using the retry policy. Let the same accepted firing recover within that window before considering a replacement.

Recover when repeated failures pause the job​

Section ID: Guide/jc16vrh0rg#auto-pause-threshold

Repair the receiver before resuming a paused reminder. The auto-pause contract defines the threshold and supported overrides.

Variant: remind the user once at a chosen time​

Section ID: Guide/jc16vrh0rg#one-shot-job

Creates one scheduled firing at the given timestamp. Delivery can be retried, so your receiver must deduplicate acceptance and its business effects. Use a future RFC 3339 timestamp.

Request example: Create a scheduled job. Example identifiers and values are illustrative; substitute authorized values.

Example request headers: X-API-Key: sk_your_key_here; X-On-Behalf-Of: user_123; Content-Type: application/json. Replace the credential and user placeholders with your own authorized values.

Variant: refresh application data every few minutes​

Section ID: Guide/jc16vrh0rg#recurring-interval-job

Use a recurring interval to refresh a cache or perform routine maintenance every N seconds without tying it to a clock time. The minimum interval is 60 seconds.

Request example: Create a scheduled job. Example identifiers and values are illustrative; substitute authorized values.

Example request headers: X-API-Key: sk_your_key_here; X-On-Behalf-Of: user_123; Content-Type: application/json. Replace the credential and user placeholders with your own authorized values.

Document ID: Guide/jc16vrh0rg