Skip to content

Task Search (API v2)

DATAMIMIC exposes typed task search endpoints intended for paginated task listings in the UI and other clients. This is the single source of truth for what task search supports today.

Endpoints

  • POST /api/v2/admin/tasks/search — Search tasks across project + system scope (admin auth).
  • POST /api/v2/projects/{project_id}/tasks/search — Search tasks within a single project (project/user auth).

Both endpoints use 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": "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": "id", "sort_order": "desc" }
}

Legacy note:

  • These POST .../search endpoints do 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.DM_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 (ILIKE %value%).

TaskScope Values

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

Request Models

AdminSearchTaskRequest

Used by the admin endpoint.

Body shape:

  • filters — AdminTaskSearchFilters
  • pagination — PaginationRequest
  • sorting — TaskSortConfig

AdminTaskSearchFilters:

Field Type Match semantics
q string \| null Free-text filter. Case-insensitive substring match across supported text fields and ID fields (task_id, project_id). Supports partial UUID fragments like 76b5aa94-.
task_id string \| null Exact match (==)
project_id string \| null Exact match (==); invalid/empty returns 400
project_name string \| null Substring match (ILIKE %value%) — project scope only (ignored for non-project scopes)
user_email string \| null Substring match (ILIKE %value%, case-insensitive)
scope TaskScope \| null Scope selector. When omitted, defaults to worker tasks (system + project). Use "backup_infrastructure" for backup tasks.
routing_keys string[] \| null Exact match (IN) for canonical routing keys (e.g. datamimic.system_backup). Non-canonical inputs return 400.
exclude_routing_keys string[] \| null Routing keys to exclude from results. Used to hide tasks with dedicated views (e.g. housekeeping, backup).
get_artifacts_metadata boolean When true, successful tasks include artifacts metadata

Notes:

  • Whitespace-only string values are ignored (treated as “not provided”); string filters are trimmed.
  • routing_keys entries are trimmed; blank entries are ignored.
  • routing_keys must use canonical datamimic.* values.

Unsupported / unknown fields are rejected with 422 (request models forbid extras).

400 InvalidTaskSearchRequest is still used for invalid values (e.g. an unknown routing_keys entry that cannot be mapped).

UserSearchTaskRequest

Used by the project-scoped endpoint. The {project_id} path parameter is an implicit filter.

Body shape:

  • filters — UserTaskSearchFilters (project is implicit via path)
  • pagination — PaginationRequest
  • sorting — TaskSortConfig

UserTaskSearchFilters:

Field Type Match semantics
q string \| null Free-text filter. Case-insensitive substring match across supported text fields and ID fields (task_id, project_id). Supports partial UUID fragments like 76b5aa94-.
task_id string \| null Exact match (==)
user_email string \| null Substring match (ILIKE %value%, case-insensitive)
routing_keys string[] \| null Exact match (IN) for canonical routing keys (datamimic.*)

Sorting

TaskSortConfig:

  • sort_by: one of id, date_started, date_queued, date_done
  • sort_order: asc or desc (default: desc)

Default behaviour: sort by id descending (deterministic, tie-broken by id).

Response Models

All task search endpoints return TaskSearchResponse with a stable envelope:

  • data: TaskSearchResult[]
  • 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

TaskSearchResult includes (non-exhaustive): id, task_id, project_id, project_name, folder, user_email, args, status, date_queued, date_started, date_done, eta, exception_type, traceback, worker, retries, preserve, execution_time, name, routing_key, artifacts, and an optional Class-C process summary.

status is the single canonical task state. It can be QUEUED, RUNNING, RETRY, FINALIZING, SUCCESS, SUCCESS_WITH_WARNING, WORKER_FAILURE, DISPATCH_FAILURE, FINALIZATION_FAILURE, CANCELLED, or DELETED. SUCCESS_WITH_WARNING is terminal success with non-fatal warnings. FINALIZING means worker execution succeeded and the server is still applying the result.

The three failure statuses identify the failure origin: WORKER_FAILURE means worker execution or its result failed, DISPATCH_FAILURE means the server could not dispatch the worker, and FINALIZATION_FAILURE means the worker succeeded but server-side finalization failed. The legacy datamimic_status field is not part of internal task-search responses; it is derived only at the existing external metadata compatibility boundary when required.

Notes:

  • id is an internal DB row id; task_id is the external task identifier.
  • routing_key in responses is the human-readable task type when resolvable (derived from TaskType); otherwise the raw value is returned.

Known Limitations (No Fake Features)

These endpoints intentionally do not provide:

  • Date-range filters (e.g. from/to, date_started_from, date_done_to, …)
  • Log search

Task logs are fetch-by-id only:

  • GET /api/v2/tasks/{task_id}/logs
  • GET /api/v2/projects/{project_id}/tasks/{task_id}/logs
  • GET /api/v2/admin/tasks/{task_id}/logs

Additional Task Endpoints

Cleanup Running Admin Tasks

POST /api/v2/admin/tasks/cleanup

Download Project Snapshot

GET /api/v2/tasks/{task_id}/snapshot/download

Get Task Metadata

GET /api/v2/projects/{project_id}/tasks/{task_id}/metadata

Update Preserve Flag

PUT /api/v2/projects/{project_id}/tasks/{task_id}/preserve

Body: { "preserve": true|false }

Cancel Task

POST /api/v2/tasks/{task_id}/cancel

Get Routing Keys

GET /api/v2/tasks/routing-keys