Note: PHP 5 has reached end of support on January 30, 2024. Your existing PHP 5 applications will continue to run and receive traffic. However, App Engine might block re-deployment of applications that use runtimes after their end of support date. We recommend that you migrate to the latest supported version of PHP.

cron.yaml Reference

Use the cron.yaml file to define scheduled tasks for your application.

To learn more about scheduling tasks, including how to test, deploy, or delete Cron jobs, see Scheduling Tasks with Cron.

Example

The following is an example cron.yaml file:

cron:
- description: "daily summary job"
  url: /tasks/summary
  schedule: every 24 hours
- description: "monday morning mailout"
  url: /mail/weekly
  schedule: every monday 09:00
  timezone: Australia/NSW
- description: "new daily summary job"
  url: /tasks/summary
  schedule: every 24 hours
  target: beta

Syntax

The cron.yaml file should reside in the root directory of your application alongside app.yaml : cron.yaml configures scheduled tasks for your PHP 5 application.

For more information about the YAML format, see the YAML website.

Cron job definitions

Element	Description
`description`	Optional. The description is visible in the Google Cloud console and the development server's admin interface. Surround the description value in quotes.
`retry_parameters`	Optional. If a cron job's request handler returns a HTTP status code that is not in the range 200–299 (inclusive) App Engine considers the job to have failed. By default, failed jobs are not retried. You can cause failed jobs to be retried by including a retry-parameters block in your configuration file. See the Cron retries section for more information.
`schedule`	Required. Defines the schedule of when the cron job runs, see the syntax below.
`target`	The `target` string is prepended to your app's hostname. It is usually the name of a service. The cron job will be routed to the version of the named service that is configured for traffic. Warning: Be careful if you run a cron job with traffic splitting enabled. The request from the cron job is always sent from the same IP address, so if you've specified IP address splitting, the logic will route the request to the same version every time. If you've specified cookie splitting, the request will not be split at all, because there is no cookie accompanying the request. If the service name that is specified for `target` is not found, then the Cron request is routed to either the `default` service, or to the version of your app that is configured to receive traffic.For more information about routing, see How Requests are Routed. If you use a dispatch file, your job might be re-routed. For example, given the following `cron.yaml` and `dispatch.yaml` files, the job will run in `service2`, even though its target is `service1`: # cron.yaml cron: - description: "test dispatch vs target" url: /tasks/hello_service2 schedule: every 1 mins target: service1 # dispatch.yaml: dispatch: - url: '*/tasks/hello_service2' service: service2
`timezone`	The `timezone` should be the name of a standard zoneinfo time zone name. If you don't specify a timezone, the schedule will be in UTC (also known as GMT).
`url`	Required. The `url` field specifies a URL in your application that will be invoked by the Cron Service. See Securing URLs for Cron for more information.

Defining the cron job `schedule`

Cron jobs are scheduled on reoccurring intervals and are specified using a simple English-like format. You can define a schedule so that your job runs multiple times a day, or runs on specific days and months.

Sub-daily intervals

Use a sub-daily interval to run a job multiple times a day on a repetitive schedule. You can define either an end-time interval, or a start-time interval:

End-time interval: Defines the time between the "end time" of a job and when the next job starts, where the "end time" is either the time at which the job completes or times out . The Cron service runs jobs in this type of interval throughout the 24 hour day, starting at 00:00, and waits for the specified duration of time between each job.
Example: For the every 5 minutes schedule, the job is run daily using a 5-minute interval. If one instance of a job that is running on this schedule complete at 02:01, then the next job waits 5 minute and starts again at 02:06.
Start-time interval: Defines a regular time interval for the Cron service to start each job. Unlike the end-time interval, the start-time interval runs each job independent of when the prior job completes or times-out. You can set a time range within which you want your job to run, or run jobs 24 hours a day, starting at 00:00.
Because the start time of a job is strict, if an instance of a job runs longer than the defined time interval, then the Cron service can skip a job. An individual start time in the interval can be skipped if the prior job has not completed or times out .

Example: For the every 5 minutes from 10:00 to 14:00 schedule, the first job starts running at 10:00, and then every 5 minutes thereafter. If that first job runs for 7 minutes, then the 10:05 job is skipped, and therefore, the Cron service does not run another instance of this job until 10:10.

Custom interval

You can use a custom interval to define a schedule where your job can run once per day on one or more select days, and in one or more select months. Jobs that run on a custom schedule run year-round, only at the specific time on the select days and months.

Example: For the 1,2,3 of month 07:00 schedule, the job runs one time at 07:00 on the first three days of each month.

Important considerations for schedule:

You must decide if you want to use either a sub-daily interval or a custom interval. You cannot mix and use elements from the various interval types. The following is an example of an invalid schedule definition: schedule: every 6 hours mon,wed,fri.
Only a single instance of a job should run at any time. The Cron service is designed to provide "at least once" delivery; that is, if a job is scheduled, App Engine sends the job request at least one time. In some rare circumstances, it is possible for multiple instances of the same job to be requested, therefore, your request handler should be idempotent, and your code should ensure that there are no harmful side-effects if this occurs.

Formatting the `schedule`

To specify when your job runs, you must define the schedule element using the following syntax:

schedule: [TYPE] [INTERVAL_VALUE] [INTERVAL_SCOPE]

Choose an interval type to define your schedule element:

End-time interval

[TYPE]: Daily intervals must include the every prefix.
Example: schedule: every 12 hours
[INTERVAL_VALUE]: An integer value and the corresponding unit of time. Valid values for the unit of time:
- minutes or mins
- hours
[INTERVAL_SCOPE]: Not applicable. To set a specific start time or range within which you want your jobs to run, see the syntax for either the Start-time interval or Custom interval.

End-time interval examples

Use the following examples to help you understand how to define job schedules that use an end-time interval:

Starts running every day at 00:00 and waits 5 minutes in between each job. After each job ends, the Cron service waits 5 minutes before running the next job:
```
schedule: every 5 minutes
```
Starts running every day at 00:00 and waits 30 minute in between each job. After each job ends, the Cron service waits 30 minutes before running the next job:
```
schedule: every 30 mins
```

Start-time interval

[TYPE]: Daily intervals must include the every prefix.
Example: schedule: every 12 hours
[INTERVAL_VALUE]: An integer value and the corresponding unit of time. Valid values for the unit of time:
- minutes or mins
- hours
[INTERVAL_SCOPE] Specifies a clause that corresponds with the [INTERVAL_VALUE]. You can define a custom time range or use the 24 hr synchronized option.
- Include the from [HH:MM] to [HH:MM] clause to define a specific start time and range within which you want to run jobs.
  You must specify the time values in the 24 hour format, HH:MM, where:
  - HH are integers from 00 to 23.
  - MM are integers from 00 to 59.
- Use synchronized to specify a 24 hour time range (from 00:00 to 23:59) that is evenly divided by the [INTERVAL_VALUE] value.
  Important: The [INTERVAL_VALUE] must divide 24 into an integer, otherwise the an error occurs. Valid values for [INTERVAL_VALUE] include: 1, 2, 3, 4, 6, 8, 12, or 24.

Start-time interval examples

Use the following examples to help you understand how to define job schedules that use a start-time interval:

Runs every 5 minutes from 10:00 to 14:00, every day:
```
schedule: every 5 minutes from 10:00 to 14:00
```
Runs once every hour from 08:00 to 16:00, every day:
```
schedule: every 1 hours from 08:00 to 16:00
```
Runs once every two hours, every day starting at 00:00:
```
schedule: every 2 hours synchronized
```

Custom interval

[TYPE]: Custom intervals can include the every prefix to define a repetitive interval, or you can define a specific list of days in a month:
- To define a repetitive interval you can use the every prefix.
  Examples:
```
schedule: every day 00:00
schedule: every monday 09:00
```
- To define specific days, you must use ordinal numbers. Valid values are from the 1st day of a month, through to the maximum number of days in that month, for example:
  - 1st or first
  - 2nd or second
  - 3rd or third
  - And up to: 31st or thirtyfirst
  Example:
```
schedule: 1st,3rd tuesday
schedule: 2nd,third wednesday of month 09:00
```
[INTERVAL_VALUE]: Custom intervals include a list of the specific days that you want the job to run. The list must be defined in a comma-separated list and can include either of the following values:
- The integer value of the day in the month through to a maximum of 31 days, for example:
  - 1
  - 2
  - 3
  - And up to: 31
- The name of the day in a mix of any of the following long or abbreviated values:
  - monday or mon
  - tuesday or tue
  - wednesday or wed
  - thursday or thu
  - friday or fri
  - saturday or sat
  - sunday or sun
  - Use day to specify all days of the week.
Examples:
```
schedule: 2nd monday,thu
schedule: 1,8,15,22 of month 09:00
schedule: 1st mon,wednesday,thu of sep,oct,nov 17:00
```
[INTERVAL_SCOPE]: Specifies a clause that corresponds with the specified [INTERVAL_VALUE]. Custom intervals can include the of [MONTH] clause, which specifies a single month in a year, or a comma-separated list of multiple months. You must also define a specific time for when you want the job to run, for example: of [MONTH] [HH:MM].
By default, if the of clause is excluded, the custom interval is run every month.
- [MONTH]: You must specify the months in a comma-separated list and can include a mix of the following long or abbreviated values:
  - january or jan
  - february or feb
  - march or mar
  - april or apr
  - may
  - june or jun
  - july or jul
  - august or aug
  - september or sep
  - october or oct
  - november or nov
  - december or dec
  - Use month to specify all months in the year.
- [HH:MM]: You must specify the time values in the 24 hour format, HH:MM, where:
  - HH are integers from 00 to 23.
  - MM are integers from 00 to 59.

Custom interval examples

Use the following examples to help you understand how to define job schedules that use a custom interval:

Runs every day at 00:00:
```
schedule: every day 00:00
```
Runs every Monday at 09:00:
```
schedule: every monday 09:00
```
Runs one time on the second Wednesday in March at 17:00:
```
schedule: 2nd wednesday of march 17:00
```
Runs six times in May. During the first two weeks, it runs one time on each Monday, Wednesday, and Friday at 10:00:
```
schedule: 1st,second mon,wed,fri of may 10:00
```
Runs once a week. Every seven days starting of the first day of every month, it runs once at 09:00:
```
schedule: 1,8,15,22 of month 09:00
```
Runs every other week. On the first and third Monday every month, it runs one time at 04:00:
```
schedule: 1st,third monday of month 04:00
```
Runs three times each year. On the first Monday of September, October, and November, it runs one time at 09:00:
```
schedule: 1st monday of sep,oct,nov 09:00
```
Runs one time each quarter. On the first day of January, April, July, and October, it runs one time at 00:00:
```
schedule: 1 of jan,april,july,oct 00:00
```

Cron retries

If a cron job's request handler returns a status code that is not in the range 200–299 (inclusive) App Engine considers the job to have failed. By default, failed jobs are not retried. You can cause failed jobs to be retried by including a retry_parameters block in your configuration file.

Here is a sample cron.yaml file that contains a single cron job configured to retry up to five times (the default) with a starting backoff of 2.5 seconds that doubles each time.

cron:
- description: "retry demo"
  url: /retry
  schedule: every 10 mins
  retry_parameters:
    min_backoff_seconds: 2.5
    max_doublings: 5

Cron retries syntax

The retry parameters are described in the table below.

Element	Description
`job_retry_limit`	The maximum number of retry attempts for a failed cron job not to exceed 5. If specified with `job_age_limit`, App Engine retries the cron job until both limits are reached. When omitted from the parameters, the limit is set to 5 by default.
`job_age_limit`	The time limit for retrying a failed cron job, measured from when the cron job was first run. The value is a number followed by a unit of time, where the unit is `s` for seconds, `m` for minutes, `h` for hours, or `d` for days. For example, the value `5d` specifies a limit of five days after the cron job's first execution attempt. If specified with `job_retry_limit`, App Engine retries the cron job until both limits are reached.
`min_backoff_seconds`	The minimum number of seconds to wait before retrying a cron job after it fails.
`max_backoff_seconds`	The maximum number of seconds to wait before retrying a cron job after it fails.
`max_doublings`	The maximum number of times that the interval between failed cron job retries will be doubled before the increase becomes constant. The constant is: 2*(`max_doublings` - 1) `min_backoff`.

Cron requests

Request headers

Requests from the Cron Service will contain a HTTP header:

X-Appengine-Cron: true

This and other headers are set internally by App Engine. If a client sends these headers, they are removed from the request. The exception being requests from logged in administrators of legacy apps, who are allowed to set the header for testing purposes.

Originating IP address

App Engine issues Cron requests from the IP address 0.1.0.2. For Cron jobs created with older gcloud versions (earlier than 326.0.0), Cron requests will come from 0.1.0.1.

Request timeout

The cron request timeout depends on the scaling type that is configured for your app:

Automatic scaling: Request timeout of 10 minutes.
Basic scaling and manual scaling: Request timeout of 24 hours.

For more information, see How instances are managed.

Limits

Free applications can have up to 20 scheduled tasks. Paid applications can have up to 250 scheduled tasks.