Schedules endpoint

Schedules are a tool that can be used to automatically run batch segmentation jobs once a day. You can use the /config/schedules endpoint to retrieve a list of schedules, create a new schedule, retrieve details of a specific schedule, update a specific schedule, or delete a specific schedule.

Getting started

The endpoints used in this guide are part of the Adobe Experience Platform Segmentation Service API. Before continuing, please review the getting started guide for important information that you need to know in order to successfully make calls to the API, including required headers and how to read example API calls.

Retrieve a list of schedules

You can retrieve a list of all schedules for your IMS Organization by making a GET request to the /config/schedules endpoint.

API format

The /config/schedules endpoint supports several query parameters to help filter your results. While these parameters are optional, their use is strongly recommended to help reduce expensive overhead. Making a call to this endpoint with no parameters will retrieve all schedules available for your organization. Multiple parameters can be included, separated by ampersands (&).

GET /config/schedules
GET /config/schedules?start={START}
GET /config/schedules?limit={LIMIT}
Parameter Description
{START} Specifies which page the offset will start from. By default, this value will be 0.
{LIMIT} Specifies the number of schedules returned. By default, this value will be 100.

Request

The following request will retrieve the last ten schedules posted within your IMS Organization.

curl -X GET https://platform.adobe.io/data/core/ups/config/schedules?limit=10 \
 -H 'Authorization: Bearer {ACCESS_TOKEN}' \
 -H 'x-gw-ims-org-id: {IMS_ORG}' \
 -H 'x-api-key: {API_KEY}' \
 -H 'x-sandbox-name: {SANDBOX_NAME}'

Response

A successful response returns HTTP status 200 with a list of schedules for the specified IMS organization as JSON.

NOTE

The following response has been truncated for space, and shows only the first schedule returned.

{
    "_page": {
        "totalCount": 10,
        "pageSize": 1
    },
    "children": [
        {
            "id": "4e538382-dbd8-449e-988a-4ac639ebe72b",
            "imsOrgId": "{IMS_ORG}",
            "sandbox": {
                "sandboxId": "28e74200-e3de-11e9-8f5d-7f27416c5f0d",
                "sandboxName": "prod",
                "type": "production",
                "default": true
            },
            "name": "Batch Segmentation",
            "state": "active",
            "type": "batch_segmentation",
            "schedule": "0 0 1 * * ?",
            "properties": {
                "segments": []
            },
            "createEpoch": 1573158851,
            "updateEpoch": 1574365202
        }
    ],
    "_links": {
        "next": {}
    }
}
Property Description
_page.totalCount The total number of schedules returned.
_page.pageSize The size of the page of schedules.
children.name The name of the schedule as a string.
children.type The type of job as a string. The two supported types are “batch_segmentation” and “export”.
children.properties An object containing additional properties related to the schedule.
children.properties.segments Using ["*"] ensures all segments are included.
children.schedule A string containing the job schedule. Jobs can only be scheduled to run once a day, meaning you cannot schedule a job to run more than once during a 24-hour period. For more information about cron schedules, please read the cron expression format documentation. In this example, “0 0 1 * *” means that this schedule will run at midnight on the first of every month.
children.state A string containing the schedule state. The two supported states are “active” and “inactive”. By default, the state is set to “inactive”.

Create a new schedule

You can create a new schedule by making a POST request to the /config/schedules endpoint.

API format

POST /config/schedules

Request

curl -X POST https://platform.adobe.io/data/core/ups/config/schedules \
 -H 'Authorization: Bearer {ACCESS_TOKEN}' \
 -H 'Content-Type: application/json' \
 -H 'x-gw-ims-org-id: {IMS_ORG}' \
 -H 'x-api-key: {API_KEY}' \
 -H 'x-sandbox-name: {SANDBOX_NAME}'
 -d '
{
    "name":"profile-default",
    "type":"batch_segmentation",
    "properties":{
        "segments":[
            "*"
        ]
    },
    "schedule":"0 0 1 * * ?",
    "state":"inactive"
}'
Property Description
name Required. The name of the schedule as a string.
type Required. The type of job as a string. The two supported types are “batch_segmentation” and “export”.
properties Required. An object containing additional properties related to the schedule.
properties.segments Required when type equals “batch_segmentation”. Using ["*"] ensures all segments are included.
schedule Optional. A string containing the job schedule. Jobs can only be scheduled to run once a day, meaning you cannot schedule a job to run more than once during a 24-hour period. For more information about cron schedules, please read the cron expression format documentation. In this example, “0 0 1 * *” means that this schedule will run at midnight on the first of every month.

If this string is not supplied, a system-generated schedule will be automatically generated.
state Optional. A string containing the schedule state. The two supported states are “active” and “inactive”. By default, the state is set to “inactive”.

Response

A successful response returns HTTP status 200 with details of your newly created schedule.

{
    "id": "4e538382-dbd8-449e-988a-4ac639ebe72b",
    "imsOrgId": "{IMS_ORG}",
    "sandbox": {
        "sandboxId": "e7e17720-c5bb-11e9-aafb-87c71c35cac8",
        "sandboxName": "prod",
        "type": "production",
        "default": true
    },
    "name": "{SCHEDULE_NAME}",
    "state": "inactive",
    "type": "batch_segmentation",
    "schedule": "0 0 1 * * ?",
    "properties": {
        "segments": [
            "*"
        ]
    },
    "createEpoch": 1568267948,
    "updateEpoch": 1568267948
}

Retrieve a specific schedule

You can retrieve detailed information about a specific schedule by making a GET request to the /config/schedules endpoint and providing the ID of the schedule you wish to retrieve in the request path.

API format

GET /config/schedules/{SCHEDULE_ID}
Parameter Description
{SCHEDULE_ID} The id value of the schedule you want to retrieve.

Request

curl -X GET https://platform.adobe.io/data/core/ups/config/schedules/4e538382-dbd8-449e-988a-4ac639ebe72b
 -H 'Authorization: Bearer {ACCESS_TOKEN}' \
 -H 'x-gw-ims-org-id: {IMS_ORG}' \
 -H 'x-api-key: {API_KEY}' \
 -H 'x-sandbox-name: {SANDBOX_NAME}'

Response

A successful response returns HTTP status 200 with detailed information about the specified schedule.

{
    "id": "4e538382-dbd8-449e-988a-4ac639ebe72b",
    "imsOrgId": "{IMS_ORG}",
    "sandbox": {
        "sandboxId": "e7e17720-c5bb-11e9-aafb-87c71c35cac8",
        "sandboxName": "prod",
        "type": "production",
        "default": true
    },
    "name": "{SCHEDULE_NAME}",
    "state": "inactive",
    "type": "batch_segmentation",
    "schedule": "0 0 1 * * ?",
    "properties": {
        "segments": [
            "*"
        ]
    },
    "createEpoch": 1568267948,
    "updateEpoch": 1568267948
}
Property Description
name The name of the schedule as a string.
type The type of job as a string. The two supported types are batch_segmentation and export.
properties An object containing additional properties related to the schedule.
properties.segments Using ["*"] ensures all segments are included.
schedule A string containing the job schedule. Jobs can only be scheduled to run once a day, meaning you cannot schedule a job to run more than once during a 24 hour period. For more information about cron schedules, please read the cron expression format documentation. In this example, “0 0 1 * *” means that this schedule will run at midnight on the first of every month.
state A string containing the schedule state. The two supported states are active and inactive. By default, the state is set to inactive.

Update details for a specific schedule

You can update a specific schedule by making a PATCH request to the /config/schedules endpoint and providing the ID of the schedule you are trying to update in the request path.

The PATCH request allows you to update either the state or the cron schedule for an individual schedule.

Update schedule state

You can use a JSON Patch operation to update the state of the schedule. To update the state, you declare the path property as /state and set the value to either active or inactive. For more information about JSON Patch, please read the JSON Patch documentation.

API format

PATCH /config/schedules/{SCHEDULE_ID}
Parameter Description
{SCHEDULE_ID} The id value of the schedule you want to update.

Request

curl -X DELETE https://platform.adobe.io/data/core/ups/config/schedules/4e538382-dbd8-449e-988a-4ac639ebe72b \
 -H 'Authorization: Bearer {ACCESS_TOKEN}' \
 -H 'x-gw-ims-org-id: {IMS_ORG}' \
 -H 'x-api-key: {API_KEY}' \
 -H 'x-sandbox-name: {SANDBOX_NAME}'
 -d '
[
    {
        "op": "add",
        "path": "/state",
        "value": "active"
    }
]'
Property Description
path The path of the value you want to patch. In this case, since you are updating the schedule’s state, you need to set the value of path to “/state”.
value The updated value of the schedule’s state. This value can either be set as “active” or “inactive” to activate or deactivate the schedule.

Response

A successful response returns HTTP status 204 (No Content).

Update cron schedule

You can use a JSON Patch operation to update the cron schedule. To update the schedule, you declare the path property as /schedule and set the value to a valid cron schedule. For more information about JSON Patch, please read the JSON Patch documentation. For more information about cron schedules, please read the cron expression format documentation.

API format

PATCH /config/schedules/{SCHEDULE_ID}
Parameter Description
{SCHEDULE_ID} The id value of the schedule you want to update.

Request

curl -X PATCH https://platform.adobe.io/data/core/ups/config/schedules/4e538382-dbd8-449e-988a-4ac639ebe72b \
 -H 'Authorization: Bearer {ACCESS_TOKEN}' \
 -H 'x-gw-ims-org-id: {IMS_ORG}' \
 -H 'x-api-key: {API_KEY}' \
 -H 'x-sandbox-name: {SANDBOX_NAME}'
 -d '
[
    {
        "op":"add",
        "path":"/schedule",
        "value":"0 0 2 * *"
    }
]'
Property Description
path The path of the value you want to updated. In this case, since you are updating the cron schedule, you need to set the value of path to /schedule.
value The updated value of the cron schedule. This value needs to be in the form of a cron schedule. In this example, the schedule will run on the second of every month.

Response

A successful response returns HTTP status 204 (No Content).

Delete a specific schedule

You can request to delete a specific schedule by making a DELETE request to the /config/schedules endpoint and providing the ID of the schedule you wish to delete in the request path.

API format

DELETE /config/schedules/{SCHEDULE_ID}
Parameter Description
{SCHEDULE_ID} The id value of the schedule you want to delete.

Request

curl -X DELETE https://platform.adobe.io/data/core/ups/config/schedules/4e538382-dbd8-449e-988a-4ac639ebe72b \
 -H 'Authorization: Bearer {ACCESS_TOKEN}' \
 -H 'x-gw-ims-org-id: {IMS_ORG}' \
 -H 'x-api-key: {API_KEY}' \
 -H 'x-sandbox-name: {SANDBOX_NAME}'

Response

A successful response returns HTTP status 204 (No Content).

Next steps

After reading this guide you now have a better understanding of how schedules work.

On this page