Skip to main content

Task Scheduler docs

Overview​

The Task Scheduler API allows users create task to be scheduled to run at a specific time and track their progress with per component breakdown. These tasks can represent background jobs, operational processes, or workflow triggers.

URL & API spec​

API is reachable at https://task-scheduler.retailsvc.com, OpenAPI docs are also available.

Authorization​

You'll need to have tss.admin role to interact with the system.

Use Cases​

⏲️ Create a New Task​

Use this to schedule a task to run at a future point in time.

When to use:

  • You want to trigger a job later (e.g., "purge items at midnight").
  • You want to track progress and results of a background job.

How to do it:

  • Endpoint: POST /tasks

  • Input:

    • taskType: What kind of task this is.
    • payload: Any custom data needed by the task.
    • triggeredAt: When to trigger the task.

Example use:

{
  "taskType": "purge-all",
  "payload": {
    "businessUnitId": "001",
    "entities": ["complete-item", "promotion"]
  },
  "triggeredAt": "2025-08-01T00:00:00.000Z"
}

📋 List All Tasks​

Retrieve tasks scheduled, running, or completed.

When to use:

  • To display a dashboard of tasks.
  • To paginate through task history.
  • To filter tasks by status (e.g., only “SCHEDULED”).

How to do it:

  • Endpoint: GET /tasks

  • Query Parameters:

    • limit – max number to return
    • offset – pagination offset
    • status – (optional) filter by SCHEDULED, TRIGGERED, COMPLETED, etc.

🔍 Get Task Details​

Check the status, history, or breakdown of a specific task.

When to use:

  • You want to monitor a task’s progress.
  • You need diagnostic details, like latency per component.

How to do it:

  • Endpoint: GET /tasks/{taskId}

Returns:

  • Task metadata
  • Trigger/finish times
  • Component-wise breakdown
  • All events (start, progress, fail, etc.)

⏰ Manually Trigger a Task​

Run a task immediately, before its scheduled time.

When to use:

  • You want to override the schedule and start now.

How to do it:

  • Endpoint: POST /tasks/{taskId}/trigger

⛔ Cancel a Task​

Stop a task before it runs.

When to use:

  • You no longer need the task to run.
  • You want to prevent a scheduled job from executing.

How to do it:

  • Endpoint: POST /tasks/{taskId}/cancel
  • Only works if the task hasn’t started yet.