Schedules API

Introduction

The Schedules API allows you to create and manage scheduled executions of automations and other recurring tasks. This API enables you to set up automated workflows that run at specific times or intervals, perfect for data processing pipelines, report generation, and other time-based operations.

To enable schedules you must enable the flag in metadata

In your promptql-config.hml file, add the following:

kind: PromptQlConfig
version: v2
definition:
  featureFlags:
    enable_scheduled_automations: true

Additionally, while you can currently schedule automations, you cannot yet run them. This feature is coming soon.

Base URL

Schedule endpoints use the following base URL:

https://promptql.ddn.hasura.app/schedules

Private DDN Endpoint

For Private DDN setups the endpoint will change to use the fully qualified domain name (FQDN) for the project assigned by the control plane. For example:

https://promptql.<FQDN>/schedules

You can find your API endpoint in the project's settings under PromptQL API Endpoint.

Authentication

Schedule endpoints require JWT authentication for all operations:

Authorization: Bearer <jwt-token>
Content-Type: application/json

Getting JWT Tokens

For information on obtaining JWT tokens, see the Authentication guide.

List Schedules

Retrieve all schedules for your project.

GET /schedules

Response

[
  {
    "schedule_id": "123e4567-e89b-12d3-a456-426614174000",
    "name": "Daily Report Generation",
    "description": "Generate daily analytics report",
    "cron_expression": "0 9 * * *",
    "automation_name": "generate_daily_report",
    "enabled": true,
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T10:30:00Z",
    "next_run": "2024-01-16T09:00:00Z",
    "last_run": "2024-01-15T09:00:00Z",
    "last_run_status": "success"
  }
]

Response Fields

Field	Type	Description
schedule_id	string	Unique identifier for the schedule
name	string	Human-readable name for the schedule
description	string	Optional description of what the schedule does
cron_expression	string	Cron expression defining when to run
automation_name	string	Name of the automation to execute
enabled	boolean	Whether the schedule is currently active
created_at	string	ISO 8601 timestamp of creation
updated_at	string	ISO 8601 timestamp of last update
next_run	string	ISO 8601 timestamp of next scheduled run
last_run	string	ISO 8601 timestamp of last execution
last_run_status	string	Status of the last execution

Create Schedule

Create a new scheduled task.

POST /schedules

Request Body

{
  "name": "Daily Report Generation",
  "description": "Generate daily analytics report at 9 AM",
  "cron_expression": "0 9 * * *",
  "automation_name": "generate_daily_report",
  "enabled": true,
  "input_data": {
    "report_type": "daily",
    "include_charts": true
  }
}

Request Fields

Field	Type	Required	Description
name	string	Yes	Human-readable name for the schedule
description	string	No	Optional description of what the schedule does
cron_expression	string	Yes	Cron expression defining when to run
automation_name	string	Yes	Name of the automation to execute
enabled	boolean	No	Whether the schedule should be active (default: true)
input_data	object	No	Optional input data to pass to the automation

Cron Expression Format

The cron expression follows the standard 5-field format:

* * * * *
│ │ │ │ │
│ │ │ │ └─── Day of week (0-7, Sunday = 0 or 7)
│ │ │ └───── Month (1-12)
│ │ └─────── Day of month (1-31)
│ └───────── Hour (0-23)
└─────────── Minute (0-59)

Common Examples:

• 0 9 * * * - Every day at 9:00 AM
• 0 */6 * * * - Every 6 hours
• 0 9 * * 1 - Every Monday at 9:00 AM
• 30 14 1 * * - First day of every month at 2:30 PM

Response

{
  "schedule_id": "123e4567-e89b-12d3-a456-426614174000",
  "name": "Daily Report Generation",
  "description": "Generate daily analytics report at 9 AM",
  "cron_expression": "0 9 * * *",
  "automation_name": "generate_daily_report",
  "enabled": true,
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T10:30:00Z",
  "next_run": "2024-01-16T09:00:00Z"
}

Error Responses

• 400 Bad Request - Invalid cron expression or automation name
• 404 Not Found - Referenced automation does not exist
• 422 Unprocessable Entity - Validation errors in request body

Get Schedule

Retrieve a specific schedule by its ID.

GET /schedules/{schedule_id}

Path Parameters

Parameter	Type	Required	Description
schedule_id	string	Yes	UUID of the schedule to retrieve

Response

{
  "schedule_id": "123e4567-e89b-12d3-a456-426614174000",
  "name": "Daily Report Generation",
  "description": "Generate daily analytics report at 9 AM",
  "cron_expression": "0 9 * * *",
  "automation_name": "generate_daily_report",
  "enabled": true,
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T10:30:00Z",
  "next_run": "2024-01-16T09:00:00Z",
  "last_run": "2024-01-15T09:00:00Z",
  "last_run_status": "success",
  "input_data": {
    "report_type": "daily",
    "include_charts": true
  },
  "execution_history": [
    {
      "execution_id": "exec-uuid-1",
      "started_at": "2024-01-15T09:00:00Z",
      "completed_at": "2024-01-15T09:02:30Z",
      "status": "success",
      "output": {
        "report_generated": true,
        "records_processed": 1250
      }
    }
  ]
}

Error Responses

• 404 Not Found - Schedule not found or access denied
• 422 Unprocessable Entity - Invalid schedule ID format