Schedules

Manage AWX job schedules via the API

Overview

Schedules enable automatic execution of job templates and workflow templates at specified times using recurrence rules (rrules).

Endpoints

Method	Endpoint	Description
GET	/api/v2/schedules/	List all schedules
POST	/api/v2/schedules/	Create schedule
GET	/api/v2/schedules/{id}/	Retrieve schedule
PATCH	/api/v2/schedules/{id}/	Update schedule
DELETE	/api/v2/schedules/{id}/	Delete schedule
GET	/api/v2/schedules/preview/	Preview rrule occurrences
GET	/api/v2/schedules/zoneinfo/	Get available timezones

List Schedules

curl -X GET \
  https://awx.example.com/api/v2/schedules/ \
  -H "Authorization: Bearer YOUR_TOKEN"

Create Schedule

curl -X POST \
  https://awx.example.com/api/v2/schedules/ \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Daily Backup",
    "description": "Run backup every day at 2 AM",
    "unified_job_template": 10,
    "rrule": "DTSTART:20240101T020000Z RRULE:FREQ=DAILY;INTERVAL=1",
    "enabled": true
  }'

name · string · required

Schedule name

description · string

Schedule description

unified_job_template · integer · required

Job template or workflow template ID

rrule · string · required

iCal recurrence rule (RFC 5545)

enabled · boolean · default: "true"

Whether schedule is active

extra_data · object

Additional variables for job launch

inventory · integer

Override inventory

limit · string

Host limit

scm_branch · string

SCM branch override

job_type · string

Job type override: run or check

job_tags · string

Ansible tags

skip_tags · string

Skip tags

verbosity · integer

Verbosity level (0-5)

diff_mode · boolean

Enable diff mode

execution_environment · integer

Execution environment override

forks · integer

Number of forks

job_slice_count · integer

Job slice count

timeout · integer

Timeout override

Retrieve Schedule

curl -X GET \
  https://awx.example.com/api/v2/schedules/15/ \
  -H "Authorization: Bearer YOUR_TOKEN"

id · integer

Schedule ID

name · string

Schedule name

rrule · string

Recurrence rule

enabled · boolean

Whether schedule is enabled

dtstart · string

Start datetime from rrule

dtend · string

End datetime from rrule

next_run · string

Next scheduled execution

timezone · string

Timezone for schedule

until · string

Schedule end date

unified_job_template · integer

Template ID

related · object

Links to related resources:

• unified_job_template - Template details
• jobs - Jobs created by this schedule
• credentials - Credential overrides
• labels - Associated labels
• instance_groups - Instance group overrides

Update Schedule

curl -X PATCH \
  https://awx.example.com/api/v2/schedules/15/ \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": false,
    "description": "Disabled temporarily"
  }'

Delete Schedule

curl -X DELETE \
  https://awx.example.com/api/v2/schedules/15/ \
  -H "Authorization: Bearer YOUR_TOKEN"

Recurrence Rules (rrule)

Schedules use iCalendar recurrence rules (RFC 5545).

Daily Schedule

DTSTART:20240101T020000Z RRULE:FREQ=DAILY;INTERVAL=1

Runs every day at 2:00 AM UTC.

Weekly Schedule

DTSTART:20240101T100000Z RRULE:FREQ=WEEKLY;INTERVAL=1;BYDAY=MO,WE,FR

Runs every Monday, Wednesday, and Friday at 10:00 AM UTC.

Monthly Schedule

DTSTART:20240101T000000Z RRULE:FREQ=MONTHLY;INTERVAL=1;BYMONTHDAY=1

Runs on the 1st of each month at midnight UTC.

With End Date

DTSTART:20240101T120000Z RRULE:FREQ=DAILY;UNTIL=20241231T235959Z

Runs daily until December 31, 2024.

Limited Occurrences

DTSTART:20240101T150000Z RRULE:FREQ=HOURLY;INTERVAL=6;COUNT=10

Runs every 6 hours for 10 occurrences.

Preview Schedule

Preview when a schedule will run:

curl -X GET \
  "https://awx.example.com/api/v2/schedules/preview/?rrule=DTSTART:20240101T020000Z%20RRULE:FREQ=DAILY;INTERVAL=1" \
  -H "Authorization: Bearer YOUR_TOKEN"

rrule · string · required

Recurrence rule to preview

Returns array of next execution times.

Available Timezones

curl -X GET \
  https://awx.example.com/api/v2/schedules/zoneinfo/ \
  -H "Authorization: Bearer YOUR_TOKEN"

Returns list of valid timezone names (e.g., America/New_York, Europe/London).

Jobs from Schedule

List jobs created by a schedule:

curl -X GET \
  https://awx.example.com/api/v2/schedules/15/jobs/ \
  -H "Authorization: Bearer YOUR_TOKEN"

Credentials

Override credentials for scheduled runs:

curl -X GET \
  https://awx.example.com/api/v2/schedules/15/credentials/ \
  -H "Authorization: Bearer YOUR_TOKEN"

Labels

curl -X GET \
  https://awx.example.com/api/v2/schedules/15/labels/ \
  -H "Authorization: Bearer YOUR_TOKEN"

Instance Groups

curl -X GET \
  https://awx.example.com/api/v2/schedules/15/instance_groups/ \
  -H "Authorization: Bearer YOUR_TOKEN"

Filtering

# By name
?name__icontains=backup

# By template
?unified_job_template=10

# Enabled only
?enabled=true

# By next run time
?next_run__gte=2024-01-01T00:00:00Z

Ordering

# By next run
?order_by=next_run

# By name
?order_by=name

# By creation date
?order_by=-created

Complete Example

import requests
import json
from datetime import datetime, timedelta

base_url = "https://awx.example.com/api/v2"
token = "YOUR_TOKEN"
headers = {
    "Authorization": f"Bearer {token}",
    "Content-Type": "application/json"
}

# Create daily schedule at 3 AM UTC
start_date = datetime.utcnow().replace(hour=3, minute=0, second=0)
rrule = f"DTSTART:{start_date.strftime('%Y%m%dT%H%M%SZ')} RRULE:FREQ=DAILY;INTERVAL=1"

schedule_data = {
    "name": "Daily Database Backup",
    "description": "Automated daily backup at 3 AM",
    "unified_job_template": 10,
    "rrule": rrule,
    "enabled": True,
    "extra_data": {
        "backup_type": "full"
    }
}

# Preview schedule
preview_response = requests.get(
    f"{base_url}/schedules/preview/",
    params={"rrule": rrule},
    headers=headers
)
print("Next 5 runs:")
for run_time in preview_response.json()[:5]:
    print(f"  {run_time}")

# Create schedule
response = requests.post(
    f"{base_url}/schedules/",
    headers=headers,
    data=json.dumps(schedule_data)
)

if response.status_code == 201:
    schedule = response.json()
    print(f"\nCreated schedule {schedule['id']}")
    print(f"Next run: {schedule['next_run']}")
else:
    print(f"Error: {response.status_code}")
    print(response.json())