Explore documentation
  1. Welcome to Uptime 👋
  2. Frequently Asked Questions
  3. On-call scheduling and alerting
    1. Get started
    2. Slack and other integrations ↗
    3. Connecting external calendars
    4. Advanced guide
  4. Incidents
    1. Get started
    2. Post mortems
    3. Metadata & Catalog
    4. Screening alerts
    5. Reporting ↗
  5. Monitoring
    1. Get started
    2. Working with monitors
    3. Customizing monitors
    4. Monitor types
  6. Status pages
    1. Get started
    2. Advanced guide
  7. Uptime API
    1. Getting an API token
    2. Monitors
    3. Heartbeats
    4. On-call & incidents
      1. On-call schedule
      2. On-call schedule events
      3. On-call schedule rotations
        1. Get on-call schedule rotation GET
        2. Create on-call schedule rotation POST
        3. Remove on-call schedule rotation DELETE
      4. Escalation policies
      5. Escalation policy groups
      6. Severities
      7. Severity groups
      8. Incidents
      9. Comments
    5. Status pages
    6. Metadata
    7. Integrations
    8. Team members
    9. Organization roles
    10. Usage
    11. Reporting

Create an on-call schedule rotation

Creates an on-call rotation. This creates consecutive on-call events for specified users, rotating through them until reaching the end date, and removes any existing non-override events within this range. Without working_hours, this only creates events that end after 0:00 UTC today. With working_hours, it creates events from now on, only inside the given windows.

POST https://uptime.betterstack.com/api/v2/on-calls/{schedule_id}/rotation

URL parameters

schedule_id
required string

The ID of the on-call schedule you want to create the event for. Use default to refer to the default on-call schedule for the team.

Headers

Authorization
required string

Bearer $TOKEN

Body parameters

team_name
string

Required if using global API token to specify the team which should own the resource.

users
required array

List of email addresses of users to include in the on-call rotation schedule

rotation_length
required number

The length of the specified rotation period, must be an integer

rotation_interval
required string

The rotation interval, must be one of: hour, day, week

start_rotations_at
required date

Start time of the rotations

end_rotations_at
required date

End time of the rotations

timezone
string

Time zone the rotation's start time and working hours are interpreted in, for example Europe/Prague. Omit it and the rotation keeps the time zone it already had. Only a rotation that has never had one falls back to UTC.

working_hours
array

List of windows during which the rotation pages anyone, one object per day and window with day, start_time and end_time. day is one of sunday, monday, tuesday, wednesday, thursday, friday, saturday. Times are HH:MM on a 24-hour clock. An end_time that is not after start_time runs overnight, so 00:00 to 00:00 is the whole day. Several windows on one day are allowed. Omit the parameter for a rotation that is active around the clock. Omitting it on a rotation that has working hours removes them. See example below.

200

Rotation was created

Response body

{
  "rotation_length": 1,
  "rotation_interval": "day",
  "start_rotations_at": "2026-02-02T00:00:00.000Z",
  "end_rotations_at": "2028-02-02T00:00:00.000Z",
  "users": [
    "bob@betterstack.com",
    "alice@betterstack.com"
  ],
  "timezone": "Europe/Prague",
  "effective_timezone": "Europe/Prague",
  "working_hours": [
    {
      "day": "monday",
      "start_time": "09:00",
      "end_time": "17:00"
    },
    {
      "day": "tuesday",
      "start_time": "09:00",
      "end_time": "17:00"
    },
    {
      "day": "wednesday",
      "start_time": "09:00",
      "end_time": "17:00"
    },
    {
      "day": "thursday",
      "start_time": "09:00",
      "end_time": "17:00"
    },
    {
      "day": "friday",
      "start_time": "09:00",
      "end_time": "17:00"
    }
  ]
}

Example cURL

Example
curl --request POST \
  --url "https://uptime.betterstack.com/api/v2/on-calls/default/rotation" \
  --header 'Authorization: Bearer $TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "users": ["bob@betterstack.com", "alice@betterstack.com"],
    "rotation_length": 1,
    "rotation_interval": "day",
    "start_rotations_at": "2026-02-02T00:00:00Z",
    "end_rotations_at": "2028-02-02T00:00:00Z",
    "timezone": "Europe/Prague",
    "working_hours": [
      { "day": "monday", "start_time": "09:00", "end_time": "17:00" },
      { "day": "tuesday", "start_time": "09:00", "end_time": "17:00" },
      { "day": "wednesday", "start_time": "09:00", "end_time": "17:00" },
      { "day": "thursday", "start_time": "09:00", "end_time": "17:00" },
      { "day": "friday", "start_time": "09:00", "end_time": "17:00" }
    ]
  }'


Previous article

Get an on-call schedule rotation

Next article

Remove an on-call schedule rotation