A schedule trigger invokes a Stacktape Lambda function on a recurring time-based schedule — cron jobs, periodic data processing, cache warming, report generation, or any task that runs at fixed intervals. Schedule triggers use AWS rate and cron expressions to invoke the target function on a recurring schedule.
When to use
- Periodic background work — database cleanup, report generation, cache invalidation, digest emails, data aggregation.
- Polling external systems — check an API, scrape a page, or sync data on a fixed interval.
- Scheduled health checks — ping endpoints or third-party services every few minutes.
- Cost-efficient recurring compute — a Lambda function triggered on a schedule costs nothing between invocations, unlike an always-on container running a cron daemon.
When NOT to use
- Real-time event processing — if the trigger is an incoming message, file upload, or database change, use SQS, S3, or DynamoDB Streams triggers instead.
- Sub-minute granularity — the minimum interval is one minute. For higher-frequency processing, use a stream-based trigger like Kinesis or a long-running container with an internal timer.
- Complex multi-step orchestration — for branching, retries, or parallel steps, use a state machine. This page only documents schedule triggers for Lambda functions.
Basic example
A schedule trigger is added to a Lambda function's events array using ScheduleIntegration. The scheduleRate property accepts either a rate expression or a cron expression.
The handler at ./src/cleanup.ts runs once every 24 hours. memory and timeout are Lambda function settings shown here to make the example realistic — the schedule trigger itself is configured entirely by the ScheduleIntegration entry. ScheduleIntegrationProps does not expose batching settings; if you add multiple schedule events to one Lambda function, configure a distinct scheduleRate and optional payload for each entry.
Schedule formats
Schedule triggers support two expression formats: rate and cron. Both use the AWS EventBridge schedule syntax.
Rate expressions
Rate expressions define a fixed interval. The syntax is rate(value unit) where unit is minute, minutes, hour, hours, day, or days. Use the singular form when the value is 1.
| Expression | Fires |
|---|---|
rate(1 minute) | Every minute |
rate(5 minutes) | Every 5 minutes |
rate(1 hour) | Every hour |
rate(12 hours) | Every 12 hours |
rate(1 day) | Once per day |
rate(7 days) | Once per week |
Rate expressions are the simplest option. Use them when you need a fixed interval and don't need to control the exact wall-clock time.
Cron expressions
Cron expressions give precise control over when the function fires. AWS EventBridge uses a 6-field format — not the 5-field Unix format. All times are in UTC.
| Field | Values | Wildcards |
|---|---|---|
| Minutes | 0–59 | , - * / |
| Hours | 0–23 | , - * / |
| Day of month | 1–31 | , - * ? / L W |
| Month | 1–12 or JAN–DEC | , - * / |
| Day of week | 1–7 or SUN–SAT | , - * ? L # |
| Year | 1970–2199 | , - * / |
Use ? in either the day-of-month or day-of-week field when you want to leave one unspecified. You cannot use * in both day fields simultaneously.
| Expression | Fires |
|---|---|
cron(0 9 * * ? *) | Every day at 9:00 AM UTC |
cron(0 18 ? * MON-FRI *) | Weekdays at 6:00 PM UTC |
cron(0 0 1 * ? *) | First day of every month at midnight UTC |
cron(0/15 * * * ? *) | Every 15 minutes |
cron(0 12 ? * 2#1 *) | First Monday of every month at noon UTC |
cron(0 */2 * * ? *) | Every 2 hours |
This function generates a report every weekday at 6:00 PM UTC. Use cron when the exact time matters — business-hour reporting, nightly batch processing, or monthly billing runs.
Rate vs cron: Use rate() for simple intervals where wall-clock time doesn't matter (polling every 5 minutes, syncing every hour). Use cron() when you need specific times (3 AM daily cleanup, weekday-only reports, first-of-month billing).
Invalid expressions
The scheduleRate property must be a valid AWS rate or cron expression. Common mistakes include using the 5-field Unix cron format (AWS requires 6 fields) and using * in both the day-of-month and day-of-week fields simultaneously (one must be ?).
Multiple schedules
A single Lambda function can have multiple schedule triggers. Add multiple ScheduleIntegration entries to the events array, each with its own scheduleRate and optional payload.
This pattern is useful when the same function handles different modes — an incremental sync every 5 minutes and a full sync at 3:00 AM UTC daily. The input property passes a fixed JSON payload so the handler can distinguish which schedule triggered the invocation.
Pausing a schedule
Set enabled: false on a schedule to deploy it without running it. The rule stays in your stack with its expression and payload, and setting enabled back to true (the default) resumes it from the next scheduled time.
Event payload customization
ScheduleIntegrationProps only defines custom payload behavior when you set input, inputPath, or inputTransformer. If you need a stable handler shape, set input or inputTransformer explicitly. You can customize what the function receives using one of three mutually exclusive options.
Set only one of input, inputPath, or inputTransformer on a schedule trigger. They are mutually exclusive.
Fixed input
The input property passes a fixed JSON object as the event payload. Use this when your handler needs simple, static context — like distinguishing between multiple schedules or passing configuration values.
The handler receives { task: 'expire-sessions', ttlHours: 24 } as the event, which is useful when the handler only needs static context. The input property passes a fixed JSON object as the event payload.
Input path
The inputPath property uses a JSONPath expression to extract a specific portion of the EventBridge event and pass only that portion to the function. For schedule triggers this is rarely needed because the default event payload is small and predictable. It becomes more useful when reusing the same pattern across event types where the original event is richer — for schedule events, input or inputTransformer are almost always a better fit.
In this example, the function receives only the time field from the EventBridge event as its payload, rather than the full event object.
Input transformer
The inputTransformer property lets you extract values from the event using inputPathsMap and construct a custom payload with inputTemplate. This is the most flexible option — use it when you need to reshape the event rather than replace it entirely.
The inputPathsMap maps variable names to JSONPath expressions that extract values from the original EventBridge event. The inputTemplate defines the shape of the payload your function receives, using <variableName> placeholders for the extracted values. This gives you full control over the payload structure while still incorporating dynamic event data like the invocation timestamp.
Handler example
The Lambda handler receives the event payload — either the default EventBridge scheduled event or your customized input. A typical handler for a schedule-triggered function:
When using a fixed input, the event parameter contains exactly the JSON value you specified. You can use the ScheduledHandler type from aws-lambda for type-safe handling of the default EventBridge event, or use any when passing custom input shapes.
Monitoring scheduled functions
View logs from schedule-triggered functions using stacktape logs with the --resource-name flag pointing to your scheduled function.
Set up alarms on your scheduled functions to catch failures early. A scheduled function that fails silently (no errors, but no useful work) is harder to notice than a broken API endpoint.
API reference
ScheduleIntegrationPropsSchedule Triggers FAQ
What is the minimum schedule interval?
One minute — rate(1 minute) is the smallest interval, and cron expressions cannot fire more often than once per minute either. There is no sub-minute scheduling; if you need higher frequency, use a stream-based trigger like Kinesis or run a long-lived container with an internal loop.
Are schedule times in UTC or local time?
For Stacktape schedule triggers, cron expressions are UTC. If you need to run at 9:00 AM Eastern, calculate the UTC offset and account for daylight saving time changes — or handle the timezone logic in your function code.
What happens if my function is still running when the next schedule fires?
AWS Lambda can run concurrent invocations, so if the previous invocation hasn't finished when the next schedule fires, a new invocation starts in parallel. Design scheduled jobs to tolerate overlap, or implement a distributed lock using DynamoDB or a similar mechanism in your handler if concurrent execution would be unsafe.
How do I pass different payloads for different schedules on the same function?
Add multiple ScheduleIntegration entries to the function's events array, each with its own scheduleRate and input (or inputTransformer). The function receives the payload associated with whichever schedule fired. See the Multiple schedules section.
How much does a scheduled Lambda function cost?
Lambda pricing is pay-per-use: you pay per invocation and per millisecond of runtime, with nothing billed between invocations. Because a scheduled function costs nothing while idle, Lambda-based cron jobs are dramatically cheaper than running an always-on container solely for periodic tasks.
When should I use a schedule trigger vs a Step Functions state machine?
Use a schedule trigger for simple, single-step periodic tasks — cleanup, polling, report generation, health checks. If the job involves branching logic, parallel execution, retries with exponential backoff, or chaining multiple steps together, a state machine is the better fit. This page only documents schedule triggers for Lambda functions.