Add events to calendar API

edit

Posts scheduled events in a calendar.

Request

edit

POST _ml/calendars/<calendar_id>/events

Prerequisites

edit

Requires the manage_ml cluster privilege. This privilege is included in the machine_learning_admin built-in role.

Description

edit

This API accepts a list of scheduled events, each of which must have a start time, end time, and description.

Path parameters

edit
<calendar_id>
(Required, string) A string that uniquely identifies a calendar.

Request body

edit
events

(Required, array) A list of one of more scheduled events. The event’s start and end times may be specified as integer milliseconds since the epoch or as a string in ISO 8601 format.

Properties of events
description
(Optional, string) A description of the scheduled event.
end_time
(Required, date) The timestamp for the end of the scheduled event in milliseconds since the epoch or ISO 8601 format.
start_time
(Required, date) The timestamp for the beginning of the scheduled event in milliseconds since the epoch or ISO 8601 format.
skip_results
(Optional, Boolean) If true, the results during the scheduled event are not created. The default value is true.
skip_model_update
(Optional, Boolean) If true, the model is not updated during the scheduled event. The default value is true.
force_time_shift
(Optional, integer) Allows you to shift the time within the anomaly detector by a specified number of seconds in a specified direction. This is useful to quickly adjust to known Daylight Saving Time (DST) events. For example, to account for a one-hour backward time shift during the fall DST event, use a value of -3600. The parameter is not set by default. The time is shifted once at the beginning of the scheduled event. The shift is measured in seconds.

Examples

edit
resp = client.ml.post_calendar_events(
    calendar_id="planned-outages",
    events=[
        {
            "description": "event 1",
            "start_time": 1513641600000,
            "end_time": 1513728000000
        },
        {
            "description": "event 2",
            "start_time": 1513814400000,
            "end_time": 1513900800000
        },
        {
            "description": "event 3",
            "start_time": 1514160000000,
            "end_time": 1514246400000
        }
    ],
)
print(resp)
response = client.ml.post_calendar_events(
  calendar_id: 'planned-outages',
  body: {
    events: [
      {
        description: 'event 1',
        start_time: 1_513_641_600_000,
        end_time: 1_513_728_000_000
      },
      {
        description: 'event 2',
        start_time: 1_513_814_400_000,
        end_time: 1_513_900_800_000
      },
      {
        description: 'event 3',
        start_time: 1_514_160_000_000,
        end_time: 1_514_246_400_000
      }
    ]
  }
)
puts response
const response = await client.ml.postCalendarEvents({
  calendar_id: "planned-outages",
  events: [
    {
      description: "event 1",
      start_time: 1513641600000,
      end_time: 1513728000000,
    },
    {
      description: "event 2",
      start_time: 1513814400000,
      end_time: 1513900800000,
    },
    {
      description: "event 3",
      start_time: 1514160000000,
      end_time: 1514246400000,
    },
  ],
});
console.log(response);
POST _ml/calendars/planned-outages/events
{
  "events" : [
    {"description": "event 1", "start_time": 1513641600000, "end_time": 1513728000000},
    {"description": "event 2", "start_time": 1513814400000, "end_time": 1513900800000},
    {"description": "event 3", "start_time": 1514160000000, "end_time": 1514246400000}
  ]
}

The API returns the following results:

{
  "events": [
    {
      "description": "event 1",
      "start_time": 1513641600000,
      "end_time": 1513728000000,
      "skip_result": true,
      "skip_model_update": true,
      "calendar_id": "planned-outages"
    },
    {
      "description": "event 2",
      "start_time": 1513814400000,
      "end_time": 1513900800000,
      "skip_result": true,
      "skip_model_update": true,
      "calendar_id": "planned-outages"
    },
    {
      "description": "event 3",
      "start_time": 1514160000000,
      "end_time": 1514246400000,
      "skip_result": true,
      "skip_model_update": true,
      "calendar_id": "planned-outages"
    }
  ]
}
const response = await client.ml.postCalendarEvents({
  calendar_id: "dst-germany",
  events: [
    {
      description: "Fall 2024",
      start_time: 1729994400000,
      end_time: 1730167200000,
      skip_result: false,
      skip_model_update: false,
      force_time_shift: -3600,
    },
    {
      description: "Spring 2025",
      start_time: 1743296400000,
      end_time: 1743469200000,
      skip_result: false,
      skip_model_update: false,
      force_time_shift: 3600,
    },
  ],
});
console.log(response);
POST _ml/calendars/dst-germany/events
{
  "events" : [
    {"description": "Fall 2024", "start_time": 1729994400000, "end_time": 1730167200000, "skip_result": false, "skip_model_update": false, "force_time_shift": -3600},
    {"description": "Spring 2025", "start_time": 1743296400000, "end_time": 1743469200000, "skip_result": false, "skip_model_update": false, "force_time_shift": 3600}
  ]
}

The API returns the following results:

{
  "events": [
    {
      "description": "Fall 2024",
      "start_time": 1729994400000,
      "end_time": 1730167200000,
      "skip_result": false,
      "skip_model_update": false,
      "force_time_shift": -3600,
      "calendar_id": "dst-germany"
    },
    {
      "description": "Spring 2025",
      "start_time": 1743296400000,
      "end_time": 1743469200000,
      "skip_result": false,
      "skip_model_update": false,
      "force_time_shift": 3600,
      "calendar_id": "dst-germany"
    }
  ]
}