Skip to main content
Documentation for version v74

Get campaign list

Description​

Retrieve the list of campaigns — combinations of mailings and scenarios into unified marketing strategies.

Access rights

To use this method, the API token must have:

  • Campaigns — Run
  • Access to the groups where the campaigns are located

Configure permissions in Settings — Tokens.

Request URL​

Method: POST

https://example.com/api/v1.1/scampaigns/list

Request parameters​

ParameterTypeExampleRequiredDescription
tokenstring"abcdefghijklmnqrstuvwxyz"YesAPI token
formatstring"json"NoResponse format
default – "json"
from_idint1NoID of the first campaign in the response
default – 1
limitint2NoLimit on the number of returned items
default – 1000
statestring"active"NoCampaign status. One of: "cloning", "inactive", "waiting", "active", "completed", "deleted"
ui_tags[]string["tag1", "tag2"]NoTag list to filter campaigns
default – []
groups[]string["group1", "group2"]NoGroup names to filter campaigns
default – []
groups_id[]int[0, 1]NoGroup IDs to filter campaigns
default – []
attributesJSON object
"attributes": {
"season": ["spring_2025", "summer_2025"]
}
NoAttribute values to filter campaigns

Request example​

{
  "token": "abcdefghijklmnqrstuvwxyz",
  "limit": 1
}

Response example​

{
  "data": [
    {
      "id": 42,
      "is_delete": false,
      "createtime": "2025-08-22T07:15:29.711Z",
      "updatetime": "2025-08-22T09:13:24.264Z",
      "updated_user": "test",
      "name": "Seasonal sale",
      "description": "",
      "tags": [],
      "state": "inactive",
      "audience": {
        "state": "ready",
        "seg_id": 124,
        "list_id": 49,
        "extension_conf": {
          "workflows": {"ids": []},
          "triggers": {"ids": []},
          "broadcasts": {"ids": []},
          "regulars": {"ids": [556]},
          "abns": {"ids": []},
          "placements": {"ids": []}
        },
        "lcg": {
          "ignore_entities": {
            "workflows": {"ids": []},
            "triggers": {"ids": []},
            "broadcasts": {"ids": []},
            "regulars": {"ids": []},
            "abns": {"ids": []},
            "placements": {"ids": []}
          },
          "size_formation_settings": {
            "limit": 0,
            "percent": "10.00"
          }
        }
      },
      "active_period": {
        "settings": {
          "tz": "Europe/Moscow",
          "end_at": "2025-08-23T10:36:25.099+03:00"
        },
        "history": {
          "start": "2025-08-22T12:13:18.813+03:00",
          "stop": "2025-08-22T12:13:24.264+03:00"
        }
      },
      "control_group_counter": 3002,
      "marketing_activities_counter": 1,
      "refresh_data": {
        "state": "completed",
        "progress": 100,
        "task_start_date": "2025-08-22T09:13:19.926Z", 
        "task_end_date": "2025-08-22T09:13:20.048Z"
      },
      "group_id": 0,
      "groups_id": [0], 
      "groups": [
        {
          "id": 0,
          "name": "main"
        }
      ],
      "attributes": {
        "season": "spring_2025",
        "branch": "marketing"
      }
    }
  ],
  "error": 0,
  "error_text": "",
  "total_count": 5
}

Returned parameters​

Top-level fields​

ParameterTypeDescription
errorintError code. 0 – successful execution
error_textstringError description
total_countintTotal number of campaigns
next_from_idintPointer for retrieving the next batch of data
dataarrayArray of campaign objects

The data object​

Contains core campaign information.

ParameterTypeDescription
idintCampaign ID
namestringCampaign name
descriptionstringCampaign description
list_idintProfile database ID
seg_idintSegment ID
statestringCurrent campaign status
createtimestringCampaign creation date and time
updatetimestringLast update date and time
updated_userstringUser who made the last changes
is_deletebooleanIndicates whether the campaign is deleted
tagsarrayCampaign tags
groupsarrayUser groups that have access to the campaign
group_idintMain campaign group ID
groups_idarrayArray of campaign group IDs
marketing_activities_counterintNumber of marketing activities (mailings, scenarios, placements)
control_group_counterintNumber of profiles in the control group
attributesobjectCampaign attributes
refresh_dataobjectInformation about the campaign data refresh process

The active_period object​

Contains information about the campaign timeframe.

ParameterTypeDescription
settingsobjectPlanned active period settings
historyobjectActual active period data

settings — planned campaign timing

ParameterTypeDescription
tzstringCampaign time zone
start_atstringPlanned campaign start date
end_atstringPlanned campaign end date

history — actual campaign data

ParameterTypeDescription
startstringActual campaign start date
stopstringActual campaign stop date

The audience object​

Contains campaign audience settings and information.

ParameterTypeDescription
statestringAudience building status
seg_idintSegment ID
list_idintProfile database ID
extension_confobjectAudience expansion settings via marketing activities
lcgobjectLocal control group settings

extension_conf

Activities that expand the campaign audience.

ParameterTypeDescription
workflowsobjectScenarios that expand the audience
triggersobjectTriggered mailings that expand the audience
broadcastsobjectBroadcast mailings that expand the audience
regularsobjectRegular mailings that expand the audience
abnsobjectA/B tests that expand the audience
placementsobjectPlacements that expand the audience

Each of these objects contains an array of IDs of the corresponding activities.

lcg — Local control group settings

ParameterTypeDescription
ignore_entitiesobjectActivities that ignore LCG
size_formation_settingsobjectLocal control group size settings

ignore_entities — activities excluded from LCG audience building

ParameterTypeDescription
workflowsobjectScenarios that ignore LCG
triggersobjectTriggers that ignore LCG
broadcastsobjectBroadcast mailings that ignore LCG
regularsobjectRegular mailings that ignore LCG
abnsobjectA/B tests that ignore LCG
placementsobjectPlacements that ignore LCG

size_formation_settings — LCG size settings

ParameterTypeDescription
limitintMaximum number of profiles in LCG
percentstringLCG share of the total audience in percent

The refresh_data object​

Contains information about the campaign data refresh process.

ParameterTypeDescription
statestringData refresh task status
progressintTask progress in percent
task_start_datestringData refresh task start date and time
task_end_datestringData refresh task end date and time

The groups object​

Contains information about access groups for the campaign.

ParameterTypeDescription
idintUser group ID
namestringUser group name
Last updated on