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.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.
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-.
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, datamimic_status, date_queued, date_started, date_done, eta, exception_type, traceback, worker, retries, preserve, execution_time, name, routing_key, artifacts.

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