Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.emergence.ai/llms.txt

Use this file to discover all available pages before exploring further.

​
Schedules

The scheduling system enables time-based automation on CRAFT. Schedules are managed by the Utils service (port 8003) and support both recurring cron-based schedules and one-off timed executions. When a schedule triggers, it publishes a notification to a configured topic, which downstream systems (such as workflow orchestrators) can consume.
Schedules use pg_cron for reliable execution. Cron jobs run inside PostgreSQL, ensuring schedule triggers survive application restarts and are executed exactly by the database scheduler.

​
Schedule Types

Recurring schedules defined using standard cron expressions with timezone support.
{
  "type": "cron",
  "cron": "0 9 * * 1-5",
  "timezone": "America/New_York"
}
The cron expression above triggers at 9:00 AM Eastern Time, Monday through Friday. Internally, the expression is converted to UTC for storage and execution, then converted back to the original timezone for display.Cron expression format:
┌───────── minute (0-59)
│ ┌─────── hour (0-23)
│ │ ┌───── day of month (1-31)
│ │ │ ┌─── month (1-12)
│ │ │ │ ┌─ day of week (0-7, 0 and 7 are Sunday)
│ │ │ │ │
* * * * *

​
Notification Configuration

When a schedule triggers, it publishes a notification. Currently, the NOTIFICATION config type is supported: 
{
  "type": "NOTIFICATION",
  "topic": "data-readiness.workflow.run",
  "extra_data": {
    "workflow_config_id": "wf-abc123",
    "environment": "production"
  }
}
FieldDescription
topicTopic string for the notification (consumed by workflow orchestrators)
extra_dataOptional JSON payload included in the notification

​
Schedule Lifecycle

1

Create Schedule

Create a schedule with a name, schedule configuration (cron or one-off), a reference ID linking to the target resource, and a notification config.Schedules can be created in an enabled or disabled state.
2

Enable/Disable

Enabling a schedule registers it with pg_cron. Disabling unschedules it. Both operations are idempotent.
3

Execution

When pg_cron fires, a schedule run record is created with a snapshot of the schedule configuration at execution time. The notification is published to the configured topic.
4

Monitor Runs

Query the runs API to view execution history, including status (PENDING, SUCCESS, FAILURE) and failure reasons.

​
API Reference

All endpoints are scoped to the authenticated user’s organization. The X-Project-ID header optionally filters schedules by project.
Creates a new schedule.Access: can_manage_projects on the organization.
Request Body
{
  "schedule_name": "Daily Analytics Refresh",
  "schedule": {
    "type": "cron",
    "cron": "0 6 * * *",
    "timezone": "America/Chicago"
  },
  "reference_id": "wf-config-analytics-daily",
  "config": {
    "type": "NOTIFICATION",
    "topic": "data-readiness.workflow.run",
    "extra_data": {
      "workflow_config_id": "wf-config-analytics-daily"
    }
  },
  "enabled": true
}
Response (201 Created)
{
  "schedule_id": "sch-a1b2c3d4"
}
Lists all schedules in the organization. Optionally filter by project via the X-Project-ID header.Schedule values are returned in their original timezone for user-friendly display.
Retrieves a single schedule by ID. Must belong to the authenticated user’s organization.
Full update of a schedule. All fields are required (this is not a partial update).
Enables a schedule and registers it with pg_cron. Idempotent if already enabled.
Disables a schedule and unschedules it from pg_cron. Idempotent if already disabled.
Permanently deletes a schedule. This action cannot be undone.

​
Schedule Runs

Lists schedule runs with pagination.Query Parameters:
  • page, limit — Pagination (default: page 1, 20 per page)
  • order — Sort by created_at: desc (most recent first) or asc
  • schedule_id — Filter runs for a specific schedule
Response
{
  "data": [
    {
      "id": "run-x1y2z3",
      "schedule_id": "sch-a1b2c3d4",
      "organization_id": "acme-corp",
      "project_id": "analytics-prod",
      "status": "SUCCESS",
      "failure_reason": null,
      "created_at": "2026-04-03T06:00:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 42,
    "total_pages": 3
  }
}
Retrieves a single run with its full schedule snapshot — the exact schedule configuration at the time of execution.
Deletes a single schedule run record.

​
Timezone Handling

Timezone support is a first-class feature of the scheduling system:
All cron expressions and one-off datetimes are converted to UTC before storage. The original timezone name is preserved alongside the expression.
API responses dynamically convert UTC values back to the original timezone. A cron expression stored as 0 11 * * * (UTC) for a schedule created with timezone America/New_York is returned as 0 6 * * * (EST) or 0 7 * * * (EDT) depending on the current DST status.
Timezone values are validated against the IANA timezone database (e.g., America/New_York, Europe/London, Asia/Tokyo). Invalid timezone names are rejected with a descriptive error.
Always use IANA timezone names (e.g., America/New_York) rather than fixed offsets (e.g., UTC-5). IANA names automatically handle daylight saving time transitions.

​
Next Steps

Webhooks

Trigger actions via event-driven webhooks.

Data Connections

Connect schedules to data source workflows.

Agent Registry

Schedule automated agent tasks.

Projects

Understand how schedules are scoped to projects.