Scheduled Actions | Documentation

Enables users to create actions that will be performed on an entity at given time in the future.

Currently supported entities and actions:

Entry: publish and unpublish
Asset: publish and unpublish
Release: publish and unpublish

Find out more regarding entry publish in entry publish docs.

Availability

Scheduled action feature is globally available for all customers.

Notifications

If an entry fails to publish at the scheduled time due to validation errors, an email will be sent to the user that created the Scheduled Action informing that it failed.

Limitations

The current limit of scheduled actions in scheduled status is 500. Once it’s reached, no additional scheduled actions can be created.

In addition there is a limit of 200 scheduled actions that can be executed in a single minute.

The scheduled date for a scheduled action when creating or updating must be between the current time and up to 5 years in the future.

There is a limit of 200 entities when publishing an entity with references, e.g. a Compose page. The scheduled action will fail if the number of entities exceeds that limit.

Scheduled action schema

The scheduled action has the following properties:

Field	Type	Required	Description
entity	Link	true	A reference to the entity object that the action is created for (Entry, Asset, Release).
environment	Link	true	A reference to the enviroment object that the action is created for.
scheduledFor	Object	true	The body of the scheduled action.
scheduledFor.datetime	String	true	The `datetime` the scheduled action is scheduled for in ISO8601 format.
scheduledFor.timezone	String	false	The `timezone` of the scheduled action. It should be a valid IANA timezone identifier.
action	String	true	Action name for action to be scheduled
sys	Object	true	System resource properties
error	Object	false	Present when the `sys.status` is `failed`. Contains more details on what caused the action to fail.
payload	Object	false	Object providing additional information about how the scheduled action will be executed

Scheduled action status

Every scheduled action has a sys.status field. It contains one of the following values:

Status	Description
canceled	The action was canceled by the user and will never be processed.
failed	The action failed to process successfully.
scheduled	The initial status of the scheduled action.
succeeded	The action has been processed successfully.

Once the scheduled action is created the status is set to scheduled. In case the scheduled action is canceled before the execution, the status is set to canceled.

Once the scheduled action was executed the status is set to succeeded in case of successful execution and to failed if any error happened during execution process.

Scheduled action payload

Payload is used to provide additional information about how the scheduled action will be executed. It supports the following properties:

Field	Description
withReferences	Filters applied to references of the entity. Note: The entity needs to belong to a content type with annotations. Note: Currently only `'sys.contentType.metadata.annotations.ContentType[nin]': ['Contentful:AggregateRoot']` filter is supported and is required.

Scheduled actions collection

For more information about scheduled actions in the web app, see our Help Center article.

Get all scheduled actions of an entry

Use this endpoint to get all the scheduled actions of an entry.

Collection filters

Scheduled actions collection supports fillowing filters:

Params	Required	Description
`?environment.sys.id="<environmentId>"`	true	Filter by the external environment ID.
`?entity.sys.id=1`	false	Filter by the list of entity ids
`?sys.status[in]=<scheduled\|canceled...>`	false	Filter by the list of the scheduled actions’ statuses
`?sys.status=<scheduled\|canceled...>`	false	Filter by single scheduled actions’ status
`?scheduledFor.datetime="ISO-time"`	false	Filter by exact match of the scheduledFor.datetime property
`?scheduledFor.datetime[lt\|lte\|gt\|gte]="ISO-time"`	false	Filter by comparison the scheduledFor.datetime property

Collection ordering

Scheduled actions collection supports fillowing ordering options:

Params	Description
?order=-scheduledFor.datetime	Descending order for scheduled actions, ascending if the parameter is absent provided.

Collection pagination

The scheduled actions collection endpoint implements cursor-based pagination. The pages object contains the next key which contains the relative URL to the next batch of items. The URL contains the same set of filters and limit as initially requested. This key is presented only if there are available elements to be fetched that weren’t returned from the current request because of the requested limit. The pages object also contains the prev key for every request after the initial request. It contains the relative URL to the batch of items requested in the previous request. The default page size if 100 and the maximum allowed limit is 1000.

Permissions

Any user can read all the scheduled actions in the entry.

Get a Scheduled Action

Get a scheduled action

Use this method to fetch a single Scheduled Action.

Permissions

Any user with read access to the supported entities can fetch a given Scheduled Action.

Errors

404 Error is returned in case:
- The sys.id is not found
- Current user doesn’t have access to space
- User doesn’t have permissions to read the entity (Release, Entry or Asset) in the Scheduled Action

Create a scheduled action

Use this endpoint to create a new scheduled action. When using this endpoint, an ID will be automatically generated for the created scheduled action and returned in the response.

There’s a limit of 200 scheduled actions in pending status per environment. An attempt to create more than 200 pending scheduled actions will result in an error.

Create a scheduled action for a compose page

Use this payload format when you want to create a scheduled action for an entry that belong to a content type with annotations. For example a Compose page.

{
  "entity": {
    "sys": {
      "type": "Link",
      "linkType": "Entry",
      "id": "5KsDBWseXY6QegucYAoacS"
    }
  },
  "environment": {
    "sys": {
      "type": "Link",
      "linkType": "Environment",
      "id": "staging"
    }
  },
  "scheduledFor": {
    "datetime": "2022-01-01T12:00:00.000Z",
    "timezone": "Europe/Berlin"
  },
  "action": "publish",
  "payload": {
    "withReferences": {
      "sys.contentType.metadata.annotations.ContentType[nin]": [
        "Contentful:AggregateRoot"
      ]
    }
  }
}

Permissions

Any user with the ability to perform the specified scheduled action to the referenced content.

Errors

400 Error is returned in case:
- Enviroment is not found
- Exceeds pending actions limit
- The payload.withReferences is included for an entity without annotations
422 Invalid request payload input return in following cases:
- The body contains invalid payload
- The scheduledFor.datetime is in the past or is not corrent ISO format
- The scheduledFor.timezone is not a valid IANA timezone identifier
- The action is unsupported
- The payload.withReferences is provided but it’s not in a valid format. Only for publish action

Update a scheduled action

Use this method to update a scheduled action’s time (at scheduledFor.datetime) or timezone (at scheduledFor.timezone). Changes to fields outside of scheduledFor are currently not supported and will result in an HTTP 400 Bad Request.

Permissions

Any user with the ability to perform the specified scheduled action to the referenced content.

Errors

400 Error is returned in case:
- The version header is not provided
- Property outside of scheduledFor.datetime and scheduledFor.timezone is changed
- Scheduled action is not in status scheduled
- An action is already scheduled for the same date and time
- entity.sys.id is invalid
- Enviroment is not found
- Exceeds pending actions limit
- The payload.withReferences is included for an entity without annotations
409 Error is returned in case:
- Version number is not a number
- The version in the X-Contentful-Version header doesn’t match the current scheduled action version
422 Invalid request payload input return in following cases:
- The body contains an invalid payload
- The scheduledFor.datetime is missing
- The scheduledFor.datetime is in the past or is not a valid ISO 8601 time
- The scheduledFor.datetime is greater than 5 years (60 months) ahead of the current time
- The scheduledFor.timezone is not a valid IANA timezone identifier
- The payload.withReferences is provided but it’s not in a valid format. Only for publish action

Cancel a scheduled action

Use this method to mark a scheduled action as canceled.

Permissions

Any user with publish access to an entry can set a scheduled action to canceled state.

Errors

400 Error is returned in case:
- The sys.status is not in a scheduled state