Task Management API

This page documents all available API endpoints for managing tasks in TikMatrix.

Create Task

Create a new task for one or more devices or usernames.

• Endpoint: POST /api/v1/task
• Content-Type: application/json

Request Parameters

The API supports two modes for creating tasks:

Mode 1: Device-based - Use serials to create tasks for devices Mode 2: Username-based - Use usernames to create tasks directly for specific accounts

Parameter	Type	Required	Description
serials	string[]	Conditional	Array of device serial numbers (required if usernames is not provided)
usernames	string[]	Conditional	Array of usernames to create tasks for (required if serials is not provided). When provided, tasks are created directly for these accounts.
script_name	string	Yes	Name of the script to execute
script_config	object	Yes	Configuration parameters for the script (see script-specific documentation)
enable_multi_account	boolean	No	Enable multi-account mode (default: false). Only applicable in device-based mode.
start_time	string	No	Scheduled start time in "HH:MM" format
close_app	boolean	No	Whether to close (force-stop) the target app after the task finishes (default: true). Set to false to leave the app running once the task completes.
platform	string	No	Target platform (tiktok or instagram). Only used by TikMatrix Pro; ignored by single-platform builds.

Supported Scripts

Script Name	Description	Documentation
post	Publish videos or images to TikTok/Instagram	Post Script Configuration
follow	Follow or unfollow users	Follow Script Configuration
unfollow	Unfollow users	Unfollow Script Configuration
account_warmup	Warm up accounts	Account Warmup Script Configuration
comment	Post a new comment on posts	Comment Script Configuration
boost_comment	Like / reply to existing comments	Boost Comment (Reply) Script Configuration
login	Login to account	Login Script Configuration
profile	Update profile	Profile Script Configuration
match_account	Match accounts on device	Match Account Script Configuration
like	Like posts	Like Script Configuration
view	Watch a post for a duration	View Script Configuration
favorite	Save a post to Favorites	Favorite Script Configuration
repost	Repost TikTok videos	Repost Script Configuration
message	Send direct messages	Message Script Configuration
follow_suggested	Follow suggested accounts	Follow Suggested Script Configuration

Example

curl -X POST http://localhost:50809/api/v1/task \
  -H "Content-Type: application/json" \
  -d '{
    "serials": ["device_serial_1"],
    "script_name": "post",
    "script_config": {
      "content_type": 0,
      "captions": "Check out my new video! #viral #fyp",
      "material_list": ["C:/Videos/video1.mp4"],
      "upload_wait_time": 60
    }
  }'

For detailed script_config parameters and more examples, see Post Script Configuration and Follow Script Configuration.

Keeping the app open after a task

By default the target app is force-stopped once a task finishes, both to mirror the in-app behavior and to free device resources. Pass "close_app": false to leave the app running after the task completes — useful when chaining tasks or inspecting the result on the device:

curl -X POST http://localhost:50809/api/v1/task \
  -H "Content-Type: application/json" \
  -d '{
    "serials": ["device_serial_1"],
    "script_name": "like",
    "script_config": {
      "target_post_url": "https://www.tiktok.com/@user/video/123"
    },
    "close_app": false
  }'

Response

{
  "code": 0,
  "message": "success",
  "data": {
    "task_ids": [101, 102],
    "created_count": 2
  }
}

List Tasks

Query tasks with optional filters.

• Endpoint: GET /api/v1/task

Parameter	Type	Required	Description
status	integer	No	Filter by status (0=pending, 1=running, 2=completed, 3=failed)
serial	string	No	Filter by device serial
script_name	string	No	Filter by script name
source	string	No	Filter by source ("ui" or "api")
page	integer	No	Page number (default: 1)
page_size	integer	No	Items per page (default: 20, max: 100)

Get Task Details

Get detailed information about a specific task.

• Endpoint: GET /api/v1/task/{task_id}

Delete Task

Delete a task. If the task is running, it will be stopped first.

• Endpoint: DELETE /api/v1/task/{task_id}

Batch Delete Tasks

Delete multiple tasks at once. Running tasks will be stopped first.

• Endpoint: DELETE /api/v1/task/batch
• Body: { "task_ids": [1, 2, 3] }

Stop Task

Stop a running task.

• Endpoint: POST /api/v1/task/{task_id}/stop

Retry Failed Task

Retry a failed task.

• Endpoint: POST /api/v1/task/{task_id}/retry

Retry All Failed Tasks

Retry all failed tasks at once.

• Endpoint: POST /api/v1/task/retry-all

Get Task Statistics

Get statistics about all tasks.

• Endpoint: GET /api/v1/task/stats
• Response: Returns total, pending, running, completed, and failed counts.

Check API License

Check if your license supports API access.

• Endpoint: GET /api/v1/license/check
• Note: Starter plan returns error code 40301. Pro, Team, and Business plans have API access.