Skip to content

Schedule Search (API v2)

DATAMIMIC exposes a typed schedule search endpoint intended for the admin Schedules table.

Endpoint

  • POST /api/v2/admin/schedules/search β€” Search schedules (admin auth).
  • POST /api/v2/projects/{project_id}/schedules/search β€” Search schedules within a project (project/user auth).

Implementation note:

  • Schedules are fetched from the Postgres schedule table. Filtering/sorting/pagination is applied in SQL using the same table-search contract.

The endpoint uses a backend-owned table-search envelope in the request body:

1
2
3
4
5
{
  "filters": { },
  "pagination": { "page": 1, "per_page": 10 },
  "sorting": { "sort_by": "schedule_id", "sort_order": "desc" }
}

Example: search by partial IDs (UUID fragments):

1
2
3
4
5
{
  "filters": { "q": "76b5aa94-" },
  "pagination": { "page": 1, "per_page": 10 },
  "sorting": { "sort_by": "schedule_id", "sort_order": "desc" }
}

Legacy note:

  • This POST .../search endpoint does not use page / per_page query parameters; clients must send pagination in the request body.

Pagination rules:

  • page is 1-based; page<=0 is clamped to 1
  • per_page<=0 uses the API default (10)
  • per_page is capped by server_settings.DB_ITEM_LIMIT (page-size cap only, no separate total-results cap)
  • page is clamped to total_pages

Substring filters:

  • All substring filters are case-insensitive (case-normalized contains match).

Request Model

TaskScope Values

Value Description
"project" Project-specific schedules
"system" System-wide schedules
"backup_infrastructure" Backup infrastructure schedules

ScheduleSearchRequest

Body shape:

  • filters β€” ScheduleSearchFilters
  • pagination β€” PaginationRequest
  • sorting β€” ScheduleSortConfig

ScheduleSearchFilters:

Field Type Match semantics
q string \| null Free-text filter. Case-insensitive substring match across supported ID and text fields (project_id, schedule_id, project_name, user_email, task_name). Supports partial UUID fragments like 76b5aa94-. Exact matches to TaskType.human_readable or TaskType.task_name also map to task_type.
project_id string \| null Exact match on schedule.project_id; invalid/empty returns 400
schedule_id string \| null Exact match on schedule.id; invalid/empty returns 400
user_email string \| null Substring match (case-insensitive) on the schedule task_args.user_email
enabled boolean \| null Exact match (==)
scope TaskScope \| null Filter by scope: "project", "system", or "backup_infrastructure"

Notes:

  • For POST /api/v2/projects/{project_id}/schedules/search, the project scope is owned by the path parameter; filters.project_id (if provided) must match {project_id}.
  • Unknown fields are rejected with 422 (request models forbid extras).

Sorting

ScheduleSortConfig:

  • sort_by: one of schedule_id, project_id, date_last_run_at, total_run_count, enabled
  • sort_order: asc or desc (default: desc)

Response Model

The endpoint returns ScheduleSearchResponse:

  • data: ScheduleSearchResult[]
  • meta:
  • pagination: total_items, total_pages, current_page, per_page, next_page_num, prev_page_num
  • sorting: the applied sorting config
  • applied_filters: normalized filters actually applied by the server

ScheduleSearchResult includes: schedule_id, project_id, project_name, folder, user_email, enabled, crontab, date_last_run_at, total_run_count, task_name, task_type, task_args, scope.

Notes:

  • task_type is the TaskType.value (e.g. system_backup); clients should map it to human-readable labels via the TaskType SPOT.
  • task_name is the full Celery task name (TaskType.task_name) and remains for compatibility.
  • task_args is returned only for non-project schedules to avoid exposing project-level secrets; it contains ScheduleTaskArgs.other for backup/housekeeping configs.

Schedule Management Endpoints

Delete Admin Schedule

DELETE /api/v2/admin/schedules/{schedule_id}?scope={scope}

Update Admin Schedule Status

PATCH /api/v2/admin/schedules/{schedule_id}?scope={scope}

Body: { "enabled": true|false }

Delete Project Schedule (Admin)

DELETE /api/v2/admin/projects/{project_id}/schedules/{schedule_id}

Update Project Schedule Status (Admin)

PATCH /api/v2/admin/projects/{project_id}/schedules/{schedule_id}

Delete Project Schedule (User)

DELETE /api/v2/projects/{project_id}/schedules/{schedule_id}

Update Project Schedule Status (User)

PATCH /api/v2/projects/{project_id}/schedules/{schedule_id}

Known Limitations (No Fake Features)

  • No date-range filters (e.g. from/to)
  • No log search (schedules do not expose a log search endpoint)