> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xenia.team/llms.txt
> Use this file to discover all available pages before exploring further.

# Task Scheduling

> Create and manage recurring tasks with flexible scheduling options

## Overview

Recurring tasks (schedules) automatically generate task instances based on defined patterns. This enables consistent execution of routine operations like daily inspections, weekly maintenance, or monthly audits.

**Key Concepts:**

* **Parent Task**: The template that defines the recurring pattern
* **Task Instance**: Individual tasks generated from the parent
* **Schedule**: The recurrence configuration (daily, weekly, monthly, etc.)
* **Series**: All instances belonging to a parent task

***

## Create a Recurring Task

Create a task with a recurrence pattern.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://api.xenia.team/api/v1/ops/workspaces/{workspaceId}/tasks" \
    -H "x-client-key: YOUR_CLIENT_KEY" \
    -H "x-client-secret: YOUR_CLIENT_SECRET" \
    -H "workspace-id: {workspaceId}" \
    -H "Content-Type: application/json" \
    -d '{
      "title": "Daily Safety Walkthrough",
      "description": "Complete morning safety inspection",
      "startDate": "2024-12-20T08:00:00Z",
      "dueTime": "10:00",
      "assignees": ["user-uuid"],
      "locationIds": ["location-uuid"],
      "recurringTask": true,
      "recurringByEvery": "daily",
      "timezone": "America/New_York",
      "notification": {
        "email": true,
        "push": true
      }
    }'
  ```
</CodeGroup>

**Recurrence Fields:**

| Field              | Type      | Description                                                    |
| ------------------ | --------- | -------------------------------------------------------------- |
| `recurringTask`    | boolean   | Set `true` for recurring tasks                                 |
| `recurringByEvery` | string    | Frequency: `daily`, `weekly`, `monthly`, `quarterly`, `yearly` |
| `recurringOnDay`   | number    | Day of week (1-7) or day of month (1-31)                       |
| `intervalWeek`     | number\[] | Days of week for weekly recurrence (1=Mon, 7=Sun)              |
| `timezone`         | string    | Timezone for schedule (e.g., `America/New_York`)               |
| `endDate`          | datetime  | When the schedule should stop generating instances             |

**Response:**

```json theme={null}
{
  "status": "success",
  "code": 200,
  "data": {
    "id": "parent-task-uuid",
    "title": "Daily Safety Walkthrough",
    "taskStatus": "Open",
    "recurringTask": true,
    "recurringByEvery": "daily",
    "isParent": true,
    "scheduleStatus": "active",
    "nextInstanceDate": "2024-12-21T08:00:00Z",
    "createdAt": "2024-12-19T10:00:00Z"
  }
}
```

### Daily Schedule

Runs every day at the specified time.

```json theme={null}
{
  "recurringTask": true,
  "recurringByEvery": "daily",
  "startTime": "08:00",
  "dueTime": "10:00",
  "timezone": "America/New_York"
}
```

### Weekly Schedule

Runs on specific days of the week.

```json theme={null}
{
  "recurringTask": true,
  "recurringByEvery": "weekly",
  "intervalWeek": [1, 3, 5],
  "startTime": "09:00",
  "dueTime": "17:00",
  "timezone": "America/New_York"
}
```

This creates tasks every Monday (1), Wednesday (3), and Friday (5).

### Monthly Schedule

Runs on a specific day of each month.

```json theme={null}
{
  "recurringTask": true,
  "recurringByEvery": "monthly",
  "recurringOnDay": 15,
  "startTime": "08:00",
  "timezone": "America/New_York"
}
```

This creates tasks on the 15th of every month.

### Quarterly Schedule

Runs every three months.

```json theme={null}
{
  "recurringTask": true,
  "recurringByEvery": "quarterly",
  "recurringOnDay": 1,
  "timezone": "America/New_York"
}
```

***

## Get Scheduled Tasks

### List All Schedules (Parent Tasks)

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://api.xenia.team/api/v1/ops/workspaces/{workspaceId}/parent-schedules/list" \
    -H "x-client-key: YOUR_CLIENT_KEY" \
    -H "x-client-secret: YOUR_CLIENT_SECRET" \
    -H "workspace-id: {workspaceId}" \
    -H "Content-Type: application/json" \
    -d '{
      "page": 1,
      "pageSize": 20,
      "sort": {
        "field": "createdAt",
        "direction": "DESC"
      },
      "filters": {
        "scheduleStatus": ["active", "paused"]
      }
    }'
  ```
</CodeGroup>

**Response:**

```json theme={null}
{
  "status": "success",
  "code": 200,
  "data": {
    "schedules": [
      {
        "id": "parent-task-uuid",
        "title": "Daily Safety Walkthrough",
        "recurringByEvery": "daily",
        "scheduleStatus": "active",
        "isPaused": false,
        "nextInstanceDate": "2024-12-21T08:00:00Z",
        "instancesCount": 45,
        "completedCount": 42,
        "missedCount": 3,
        "Assignees": [...],
        "Location": {...}
      }
    ],
    "meta": {
      "total": 15,
      "page": 1,
      "pageSize": 20
    }
  }
}
```

### List Active Schedule Instances

Get all active (upcoming and current) task instances.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://api.xenia.team/api/v1/ops/workspaces/{workspaceId}/all-schedules" \
    -H "x-client-key: YOUR_CLIENT_KEY" \
    -H "x-client-secret: YOUR_CLIENT_SECRET" \
    -H "workspace-id: {workspaceId}" \
    -H "Content-Type: application/json" \
    -d '{
      "page": 1,
      "pageSize": 20,
      "filters": {
        "dateFrom": "2024-12-01",
        "dateTo": "2024-12-31"
      }
    }'
  ```
</CodeGroup>

### List Overdue Schedule Instances

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://api.xenia.team/api/v1/ops/workspaces/{workspaceId}/overdue-schedules" \
    -H "x-client-key: YOUR_CLIENT_KEY" \
    -H "x-client-secret: YOUR_CLIENT_SECRET" \
    -H "workspace-id: {workspaceId}" \
    -H "Content-Type: application/json" \
    -d '{
      "page": 1,
      "pageSize": 20
    }'
  ```
</CodeGroup>

### List Completed Schedule Instances

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://api.xenia.team/api/v1/ops/workspaces/{workspaceId}/completed-schedules" \
    -H "x-client-key: YOUR_CLIENT_KEY" \
    -H "x-client-secret: YOUR_CLIENT_SECRET" \
    -H "workspace-id: {workspaceId}" \
    -H "Content-Type: application/json" \
    -d '{
      "page": 1,
      "pageSize": 20,
      "filters": {
        "dateFrom": "2024-12-01",
        "dateTo": "2024-12-31"
      }
    }'
  ```
</CodeGroup>

### Get Schedule History

Get all instances generated from a parent task.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://api.xenia.team/api/v1/ops/workspaces/{workspaceId}/scheduled-tasks/{parentTaskId}/history" \
    -H "x-client-key: YOUR_CLIENT_KEY" \
    -H "x-client-secret: YOUR_CLIENT_SECRET" \
    -H "workspace-id: {workspaceId}"
  ```
</CodeGroup>

**Response:**

```json theme={null}
{
  "status": "success",
  "code": 200,
  "data": {
    "parentTask": {
      "id": "parent-task-uuid",
      "title": "Daily Safety Walkthrough",
      "recurringByEvery": "daily"
    },
    "instances": [
      {
        "id": "instance-uuid-1",
        "taskNumber": "T-2024-001250",
        "taskStatus": "Completed",
        "startDate": "2024-12-20T08:00:00Z",
        "completedAt": "2024-12-20T09:45:00Z"
      },
      {
        "id": "instance-uuid-2",
        "taskNumber": "T-2024-001249",
        "taskStatus": "Completed",
        "startDate": "2024-12-19T08:00:00Z",
        "completedAt": "2024-12-19T09:30:00Z"
      }
    ],
    "statistics": {
      "total": 45,
      "completed": 42,
      "missed": 3,
      "completionRate": 93.3
    }
  }
}
```

***

## Manage Schedules

### Pause a Schedule

Temporarily stop generating new instances.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://api.xenia.team/api/v1/ops/workspaces/{workspaceId}/schedules/{scheduleId}/toggle-pause" \
    -H "x-client-key: YOUR_CLIENT_KEY" \
    -H "x-client-secret: YOUR_CLIENT_SECRET" \
    -H "workspace-id: {workspaceId}"
  ```
</CodeGroup>

**Response (Paused):**

```json theme={null}
{
  "status": "success",
  "code": 200,
  "data": {
    "id": "schedule-uuid",
    "isPaused": true,
    "scheduleStatus": "paused",
    "message": "Schedule has been paused"
  }
}
```

**Response (Resumed):**

```json theme={null}
{
  "status": "success",
  "code": 200,
  "data": {
    "id": "schedule-uuid",
    "isPaused": false,
    "scheduleStatus": "active",
    "message": "Schedule has been resumed"
  }
}
```

<Note>
  This endpoint toggles the pause state. Call it once to pause, call again to resume.
</Note>

### End a Schedule

Permanently stop a schedule from generating new instances.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X PUT "https://api.xenia.team/api/v1/ops/workspaces/{workspaceId}/schedules/{scheduleId}/end" \
    -H "x-client-key: YOUR_CLIENT_KEY" \
    -H "x-client-secret: YOUR_CLIENT_SECRET" \
    -H "workspace-id: {workspaceId}"
  ```
</CodeGroup>

**Response:**

```json theme={null}
{
  "status": "success",
  "code": 200,
  "data": {
    "id": "schedule-uuid",
    "scheduleStatus": "ended",
    "endedAt": "2024-12-20T10:00:00Z"
  }
}
```

<Warning>
  Ending a schedule is permanent. Existing instances remain but no new ones will be created. To temporarily stop, use pause instead.
</Warning>

### Archive a Task Series

Archive all tasks in a recurring series.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X PATCH "https://api.xenia.team/api/v1/ops/workspaces/{workspaceId}/tasks/{parentTaskId}/archive-series" \
    -H "x-client-key: YOUR_CLIENT_KEY" \
    -H "x-client-secret: YOUR_CLIENT_SECRET" \
    -H "workspace-id: {workspaceId}"
  ```
</CodeGroup>

***

## Edit a Schedule

Update the schedule template. Changes apply to future instances.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://api.xenia.team/api/v1/ops/workspaces/{workspaceId}/tasks/{parentTaskId}/edit" \
    -H "x-client-key: YOUR_CLIENT_KEY" \
    -H "x-client-secret: YOUR_CLIENT_SECRET" \
    -H "workspace-id: {workspaceId}" \
    -H "Content-Type: application/json" \
    -d '{
      "title": "Updated Daily Safety Walkthrough",
      "description": "Updated inspection procedure",
      "dueTime": "11:00",
      "assignees": ["new-user-uuid"],
      "priority": "High"
    }'
  ```
</CodeGroup>

**Editable Schedule Fields:**

* `title`, `description`, `additionalDescription`
* `startTime`, `dueTime`
* `priority`
* `assignees`
* `locationIds`, `AssetId`
* `ChecklistId`, `isChecklistRequired`
* `notification`
* `endDate` (to set when schedule should stop)

<Note>
  You cannot change the recurrence pattern (`recurringByEvery`, `intervalWeek`) after creation. Create a new schedule instead.
</Note>

***

## Statistics

### Get Overdue Count

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://api.xenia.team/api/v1/ops/workspaces/{workspaceId}/scheduled-tasks/overdue-count" \
    -H "x-client-key: YOUR_CLIENT_KEY" \
    -H "x-client-secret: YOUR_CLIENT_SECRET" \
    -H "workspace-id: {workspaceId}" \
    -H "Content-Type: application/json" \
    -d '{}'
  ```
</CodeGroup>

**Response:**

```json theme={null}
{
  "status": "success",
  "code": 200,
  "data": {
    "overdueCount": 12,
    "bySchedule": [
      {
        "scheduleId": "parent-uuid-1",
        "title": "Daily Safety Walkthrough",
        "overdueCount": 5
      },
      {
        "scheduleId": "parent-uuid-2",
        "title": "Weekly Equipment Check",
        "overdueCount": 7
      }
    ]
  }
}
```

### Get Due Stats

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://api.xenia.team/api/v1/ops/workspaces/{workspaceId}/tasks/due-stats" \
    -H "x-client-key: YOUR_CLIENT_KEY" \
    -H "x-client-secret: YOUR_CLIENT_SECRET" \
    -H "workspace-id: {workspaceId}"
  ```
</CodeGroup>

**Response:**

```json theme={null}
{
  "status": "success",
  "code": 200,
  "data": {
    "overdue": 12,
    "dueToday": 8,
    "dueThisWeek": 25,
    "dueThisMonth": 95
  }
}
```

***

## Common Workflows

### Create Daily Inspection Schedule

```mermaid theme={null}
sequenceDiagram
    participant Client as Your System
    participant API as Xenia API
    participant Cron as Scheduler

    Client->>API: 1. POST /tasks
    Note right of Client: recurringTask: true<br/>recurringByEvery: "daily"
    API-->>Client: Parent task created

    Cron->>API: 2. Generate instances (automatic)
    Note right of Cron: Runs daily based on<br/>schedule configuration

    Client->>API: 3. GET /scheduled-tasks/{id}/history
    API-->>Client: List of instances

    Client->>API: 4. PATCH /tasks/{instanceId}/status
    Note right of Client: Complete individual instances
```

### Weekly Multi-Day Schedule

Create a task that runs Monday, Wednesday, and Friday.

```bash theme={null}
curl -X POST "https://api.xenia.team/api/v1/ops/workspaces/{workspaceId}/tasks" \
  -H "x-client-key: YOUR_CLIENT_KEY" \
  -H "x-client-secret: YOUR_CLIENT_SECRET" \
  -H "workspace-id: {workspaceId}" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "MWF Equipment Inspection",
    "startDate": "2024-12-23T08:00:00Z",
    "dueTime": "12:00",
    "recurringTask": true,
    "recurringByEvery": "weekly",
    "intervalWeek": [1, 3, 5],
    "assignees": ["user-uuid"],
    "locationIds": ["location-uuid"],
    "ChecklistId": "inspection-checklist-uuid",
    "isChecklistRequired": true,
    "timezone": "America/New_York"
  }'
```

### Monitor Schedule Compliance

```bash theme={null}
#!/bin/bash
# Check schedule compliance

WORKSPACE_ID="your-workspace-uuid"

# Get overdue scheduled tasks
OVERDUE=$(curl -s -X POST "https://api.xenia.team/api/v1/ops/workspaces/${WORKSPACE_ID}/overdue-schedules" \
  -H "x-client-key: YOUR_KEY" \
  -H "x-client-secret: YOUR_SECRET" \
  -H "workspace-id: ${WORKSPACE_ID}" \
  -H "Content-Type: application/json" \
  -d '{"page": 1, "pageSize": 100}')

# Count and report
OVERDUE_COUNT=$(echo $OVERDUE | jq '.data.tasks | length')
echo "Overdue scheduled tasks: ${OVERDUE_COUNT}"

# Get completion rates by schedule
curl -s -X POST "https://api.xenia.team/api/v1/ops/workspaces/${WORKSPACE_ID}/parent-schedules/list" \
  -H "x-client-key: YOUR_KEY" \
  -H "x-client-secret: YOUR_SECRET" \
  -H "workspace-id: ${WORKSPACE_ID}" \
  -H "Content-Type: application/json" \
  -d '{"page": 1, "pageSize": 50}' | \
  jq '.data.schedules[] | {title: .title, completionRate: (.completedCount / .instancesCount * 100)}'
```

***

## Best Practices

<AccordionGroup>
  <Accordion title="Set appropriate timezones">
    Always specify the `timezone` field for recurring tasks. This ensures instances are created at the correct local time, especially important for multi-location organizations.
  </Accordion>

  <Accordion title="Use end dates for temporary schedules">
    For schedules that should run for a limited time (e.g., during a project), set an `endDate` to automatically stop instance generation.
  </Accordion>

  <Accordion title="Monitor overdue instances">
    Regularly check overdue scheduled tasks. High overdue counts may indicate staffing issues, unrealistic schedules, or process problems.
  </Accordion>

  <Accordion title="Pause instead of delete">
    If you need to temporarily stop a schedule, use pause instead of ending it. This preserves the configuration and allows easy resumption.
  </Accordion>

  <Accordion title="Attach checklists for consistency">
    Recurring tasks benefit greatly from attached checklists. This ensures each instance follows the same procedure and generates comparable data.
  </Accordion>

  <Accordion title="Review and adjust schedules periodically">
    Business needs change. Periodically review active schedules to ensure they still align with operational requirements.
  </Accordion>
</AccordionGroup>

***

## Schedule Status Reference

| Status    | Description                                  |
| --------- | -------------------------------------------- |
| `active`  | Schedule is running and generating instances |
| `paused`  | Schedule is temporarily stopped              |
| `ended`   | Schedule has been permanently stopped        |
| `expired` | Schedule reached its end date                |

***

## Related Guides

* [Task Management](/guides/workflows/task-management) - One-off task operations
* [Work Orders](/guides/workflows/work-orders) - Facility request management
* [Project Management](/guides/workflows/project-management) - Organize recurring work
* [Template Management](/guides/workflows/template-management) - Create checklists for scheduled tasks