Skip to main content

Super Marketing Script Configuration

This page documents the API endpoints for the Super Marketing script. Unlike the other scripts, super marketing is not created through the generic POST /api/v1/task endpoint — it runs off a reusable dataset of targets and has its own dedicated endpoints.

Overview​

A super marketing campaign combines several growth actions (follow, unfollow, report, DM, boost, mass comment) into a single run over a pool of targets. The pool of targets is stored as a dataset:

  • Data type — the dataset holds either usernames (TikTok/Instagram handles) or post_links (post URLs).
  • Strategy — controls how targets are distributed across your devices:
    • shared_pool — every selected device/account processes all targets.
    • consume_once — targets are split across devices and each is consumed once.

The typical flow is:

  1. Import targets into a dataset → get a dataset_id.
  2. Run a campaign that references that dataset_id on one or more devices.

Feature toggles (follow / DM / comment, etc.) and their detailed settings are read from the desktop app's saved configuration (super_marketing_settings.json). You can override any of those per run by passing script_config in the run request.

License Requirement

All super marketing endpoints require a Pro, Team, or Business plan, like the rest of the Local API.

Import Dataset​

Create a new dataset or add targets to an existing one.

  • Endpoint: POST /api/v1/super-marketing/dataset

Request Body​

FieldTypeRequiredDefaultDescription
dataset_idintegerNo—Existing dataset id to append to / replace. Omit or use 0 to create a new dataset.
data_typestringYes—usernames or post_links
strategystringYes—shared_pool or consume_once
entriesstring[]Yes*[]Targets as a JSON array. Takes priority over raw_text.
raw_textstringYes*—Targets as a newline-separated string (alternative to entries).
modestringNoappendappend adds to existing entries; replace clears existing entries first.
labelstringNo—Optional human-readable label for the dataset.
note

Provide targets via either entries or raw_text. Duplicate and empty entries are ignored. A single import is capped at 100,000 entries.

Example​

curl -X POST http://localhost:50809/api/v1/super-marketing/dataset \
  -H "Content-Type: application/json" \
  -d '{
    "data_type": "usernames",
    "strategy": "shared_pool",
    "label": "Campaign A targets",
    "entries": ["@user_one", "@user_two", "@user_three"]
  }'

Append more targets to an existing dataset using newline-separated text:

curl -X POST http://localhost:50809/api/v1/super-marketing/dataset \
  -H "Content-Type: application/json" \
  -d '{
    "dataset_id": 7,
    "data_type": "usernames",
    "strategy": "shared_pool",
    "mode": "append",
    "raw_text": "@user_four\n@user_five\n@user_six"
  }'

Sample Response​

{
  "code": 0,
  "message": "success",
  "data": {
    "dataset": {
      "stats": {
        "id": 7,
        "data_type": "usernames",
        "strategy": "shared_pool",
        "label": "Campaign A targets",
        "total": 3,
        "consumed": 0,
        "remaining": 3,
        "created_at": "2026-06-22 09:00:00",
        "updated_at": "2026-06-22 09:00:00"
      },
      "entries": [
        { "id": 1, "value": "@user_one", "consumed": false, "consumed_by": null, "consumed_at": null, "created_at": "2026-06-22 09:00:00", "updated_at": "2026-06-22 09:00:00" }
      ]
    },
    "summary": {
      "inserted": 3,
      "duplicates": 0,
      "skipped_empty": 0,
      "removed": 0,
      "truncated": 0
    }
  }
}

List Datasets​

Retrieve all datasets with consumption stats.

  • Endpoint: GET /api/v1/super-marketing/datasets

Query Parameters​

ParameterTypeDefaultDescription
data_typestring—Optional filter: usernames or post_links

Example​

curl "http://localhost:50809/api/v1/super-marketing/datasets?data_type=usernames"

Sample Response​

{
  "code": 0,
  "message": "success",
  "data": [
    {
      "id": 7,
      "data_type": "usernames",
      "strategy": "shared_pool",
      "label": "Campaign A targets",
      "total": 6,
      "consumed": 0,
      "remaining": 6,
      "created_at": "2026-06-22 09:00:00",
      "updated_at": "2026-06-22 09:05:00"
    }
  ]
}

Get Dataset​

Fetch a dataset's stats and a page of its entries.

  • Endpoint: GET /api/v1/super-marketing/dataset/{id}

Query Parameters​

ParameterTypeDefaultDescription
limitinteger50Entries per page (max 500)
offsetinteger0Number of entries to skip

Example​

curl "http://localhost:50809/api/v1/super-marketing/dataset/7?limit=100&offset=0"

Clear Dataset​

Remove all entries from a dataset. The dataset record itself is kept (and its dataset_id stays valid for future imports).

  • Endpoint: DELETE /api/v1/super-marketing/dataset/{id}

Example​

curl -X DELETE http://localhost:50809/api/v1/super-marketing/dataset/7

Sample Response​

{
  "code": 0,
  "message": "success",
  "data": { "cleared": true, "dataset_id": 7 }
}

Run Campaign​

Launch a super marketing campaign on the given devices, using a dataset's targets.

  • Endpoint: POST /api/v1/super-marketing/run

Request Body​

FieldTypeRequiredDefaultDescription
serialsstring[]Yes[]Device serial numbers to run on
dataset_idintegerYes—Dataset whose targets drive the campaign
enable_multi_accountbooleanNofalseCreate one task per account on each device
merge_same_username_tasksbooleanNofalsePack all of a device's targets into one task instead of one task per target
platformstringNo—Platform override (tiktok / instagram). Honored only on multi-platform builds; single-platform builds always use their fixed platform
min_intervalintegerNo0Minimum minutes between staggered task start times
max_intervalintegerNo0Maximum minutes between staggered task start times
start_timestringNo—First task start time in HH:MM
rotate_proxybooleanNofalseRotate the device proxy before running
switch_account_methodstringNo—How to switch accounts in multi-account mode (e.g. profile)
official_packagesstring[]No[]Restrict execution to these official packages (multi-account mode)
clone_package_prefixstringNo—Restrict execution to clone apps whose package name starts with this prefix
script_configobjectNo—Feature toggles / per-feature settings that override the desktop-saved config (see below)
Data type is taken from the dataset

You do not pass data_source_type in the run request — the campaign automatically uses the dataset's data_type (usernames or post_links). Post-link datasets only support the boost_posts and mass_comment features.

script_config overrides​

script_config is optional. When omitted, the campaign uses the feature toggles and settings you configured in the desktop app. Provide it to run a fully self-contained campaign or to override specific fields. Keys accept both camelCase and snake_case.

FieldTypeDescription
access_methodstringHow to reach username targets: search or direct
features.follow_usersbooleanFollow each target
features.unfollow_usersbooleanUnfollow each target
features.report_accountbooleanReport each target account
features.send_dmbooleanSend a direct message to each target
features.boost_postsbooleanLike / favorite / repost / share the target's posts
features.mass_commentbooleanComment on the target's posts
follow_settings.boost_typestringfollow or unfollow
dm_settings.message_contentsstringDM text (newline-separated for multiple variants)
dm_settings.message_orderstringrandom or sequential
dm_settings.insert_emojibooleanInsert random emoji into the DM
dm_settings.generate_by_chatgptbooleanGenerate the DM with ChatGPT
dm_settings.chatgpt_promptstringPrompt used when generating the DM
dm_settings.chatgpt_settingsobject{ url, api_key, model, system_prompt }
post_settings.skip_posts_countintegerPosts to skip before acting (0–8, username source only)
post_settings.max_posts_countintegerMax posts to process per target
post_settings.enable_likebooleanLike posts
post_settings.enable_favoritebooleanAdd posts to favorites
post_settings.enable_repostbooleanRepost posts
post_settings.enable_sharebooleanShare posts
post_settings.repeat_timesintegerTimes to repeat the post actions
post_settings.view_durationsinteger[][min, max] seconds to watch each post
comment_settings.comment_contentstringComment text (newline-separated for multiple variants)
comment_settings.comment_orderstringrandom or sequential
comment_settings.insert_emojibooleanInsert random emoji into the comment
comment_settings.generate_by_chatgptbooleanGenerate the comment with ChatGPT
comment_settings.chatgpt_settingsobject{ url, api_key, model, system_prompt }
task_finish_wait_timeintegerSeconds to wait before finishing (prevents data loss)

Examples​

Minimal run (use desktop-saved settings)​

curl -X POST http://localhost:50809/api/v1/super-marketing/run \
  -H "Content-Type: application/json" \
  -d '{
    "serials": ["device_serial_1", "device_serial_2"],
    "dataset_id": 7
  }'

Self-contained follow + DM campaign​

curl -X POST http://localhost:50809/api/v1/super-marketing/run \
  -H "Content-Type: application/json" \
  -d '{
    "serials": ["device_serial_1"],
    "dataset_id": 7,
    "enable_multi_account": true,
    "min_interval": 1,
    "max_interval": 3,
    "script_config": {
      "access_method": "search",
      "features": {
        "follow_users": true,
        "send_dm": true
      },
      "follow_settings": { "boost_type": "follow" },
      "dm_settings": {
        "message_contents": "Hey! Love your content 🙌\nGreat posts, keep it up!",
        "message_order": "random",
        "insert_emoji": true
      }
    }
  }'

Mass comment on a post-link dataset​

curl -X POST http://localhost:50809/api/v1/super-marketing/run \
  -H "Content-Type: application/json" \
  -d '{
    "serials": ["device_serial_1"],
    "dataset_id": 9,
    "merge_same_username_tasks": true,
    "script_config": {
      "features": { "mass_comment": true },
      "comment_settings": {
        "comment_content": "🔥🔥🔥\nAmazing!\nLove this",
        "comment_order": "random"
      }
    }
  }'

Sample Response​

{
  "code": 0,
  "message": "success",
  "data": { "created_count": 6 }
}

created_count is the number of tasks that were created. The pending tasks then run on their assigned devices like any other task — track them via the Task Management API.

Error Responses​

HTTP StatusCodeDescription
40040001Invalid parameters (bad data_type/strategy, empty serials, non-positive dataset_id, non-object script_config, or no tasks created)
40340301Forbidden — API access requires Pro+ plan
40440401Dataset not found
50050001Internal server error
No tasks created

If the run returns code 40001 with a "No tasks created" message, verify that the dataset still has remaining targets (for consume_once strategy) and that the selected devices are online.

See Also​