SEMSTORM - Monitoring

Monitoring API

This document contains basic information how to use SEMSTORM Monitoring API v3.

SEMSTORM PHP SDK library is under Apache License 2.0, This means that library is distributed without any warranties. What is more, support is not included. If you encounter any problems, please leave us a ticket.

Introduction

Tags are obsolete. Tags functionality is disabled, their endpoint is closed and any usage of them is impossible.

Advanced filters. Some of the requests have optional "advanced filters" parameter. Those filters allow users to create advanced and precise reports/queries. Those filters are sent in a request as a simple array, which must be build properly. For details about usage of filters see this documentation. Currently requests using advanced filters are: Campaign get data.

Documentation

Every functionality contains examples in curl and PHP. In PHP case, it is assumed that user have properly installed SEMSTORM PHP SDK library which can be fount here. For curl -as any other than prepared sdk library- remember that SEMSTORM API guarantee compatibility only for JSON formatted data.

Monitoring Campaign

MonitoringCampaign class instance

MonitoringCampaign class is used to perform operations on SEMSTORM Campaigns, which includes creating, retrieving, and modification of campaigns.
PHP example code:
include_once __DIR__ . '/autoload.php';
use SemstormApi\Semstorm;
use SemstormApi\Monitoring\MonitoringCampaign;
Semstorm::init( __ACCESS_TOKEN__ );
$monitoringCampaign = new MonitoringCampaign();

Create campaign

Endpoint:
http://api.semstorm.com/api-v3/monitoring/monitoring-campaign [POST]

Parameters   PHP  CURL 
parameter method type required default  description
domain POST string yes - Campaign domain value.
title POST string no Campaign title. Default: domain value.
type POST string yes - Campaign type. Possible values: "seo", "ads".
data POST array no Campaign additional data. Default: empty array.
Data array
parameter type required default  description
company_map_title string no Company map title property. Default: no parameter.
domains* array no Website addresses (strings) if multiple exists. Default: no parameter. * - this value is available only for "ads" type.
trademarks* array no Trademarks list (strings). Default: no parameter. * - this value is available only for "ads" type.
include_subdomains array no Whether include subdomains or not. Default: not included.
Output   RESULT 
method type description
result["id"] integer Id of newly created campaign.

Description:
Creates new campaign.

Error:
Request: "domain", or "type" field is empty.
Limit: creating campaign require at least one free campaign limit.

PHP example code:

examples/Monitoring/CampaignCreate.php

Curl:

curl -X POST -d '{ "domain": "example.com" }' http://api.semstorm.com/api-v3/monitoring/monitoring-campaign.json?services_token=__ACCESS_TOKEN__

Output:

{ "id": __ID__ }

Retrieve campaign data

Endpoint:
http://api.semstorm.com/api-v3/monitoring/monitoring-campaign/{_CAMPAIGN_ID_} [GET]

Parameters   PHP  CURL 
parameter method type required default  description
_CAMPAIGN_ID_ url integer yes - Campaign id to retrieve.
Output   RESULT 
method type description
result["id"] integer Campaign id.
result["title"] string Campaign title.
result["domain"] string Campaign domain.
result["status"] string Campaign status.
result["access"] string User access type.
result["type"] string Campaign type.
result["created_time"] string Campaign create timestamp.
result["changed_time"] string Campaign last modification timestamp.
result["groups"] array Campaign groups ids.

Description:
Get data about campaign.

Error:
Request: campaign with given id not exist for current user.

PHP example code:

examples/Monitoring/CampaignRetrieve.php

Curl:

curl http://api.semstorm.com/api-v3/monitoring/monitoring-campaign/_CAMPAIGN_ID_.json?services_token=__ACCESS_TOKEN__

Output:

{"id": _CAMPAIGN_ID_, "domain":"example.com", "status":"active", "access_type":"owner", "created_time":"1460375898", "changed_time":"1460375898", "groups":[__GROUP_ID__, __GROUP_ID__ (...) ]}

Update campaign data

Endpoint:
http://api.semstorm.com/api-v3/monitoring/monitoring-campaign/{_CAMPAIGN_ID_} [PUT]

Parameters   PHP  CURL 
parameter method type required default  description
_CAMPAIGN_ID_ url integer yes - Campaign id to update.
domain POST string no Campaign domain value. Default: current domain.
title POST string no Campaign title. Default: current title.
data POST array no Campaign additional data. Default: current array.
Data array
parameter type required default  description
company_map_title string no Company map title property.
Output   RESULT 
method type description
result bool Value is true on success.

Description:
Change data of campaign.
This call is in critical section, which means it locks access to entity it operates on for the execution time. When locked no other critical actions may take place. Also this call may fail if anything else locked current entity before it.

Error:
Request: campaign with given id not exist for current user.

PHP example code:

examples/Monitoring/CampaignUpdate.php

Curl:

curl -X PUT -d '{ "domain": "example.com" }' http://api.semstorm.com/api-v3/monitoring/monitoring-campaign/_ID_.json?services_token=__ACCESS_TOKEN__

Output:

[ true ]

Start campaign

Endpoint:
http://api.semstorm.com/api-v3/monitoring/monitoring-campaign/start [POST]

Parameters   PHP  CURL 
parameter method type required default  description
id POST mixed yes - Array with campaign ids. For backwards compatibility works also as integer for one campaign.
Output   RESULT 
method type description
result array Array with results and/or error messages, keyed by campaigns ids.
result[_CAMPAIGN_ID_] mixed True if change status for given campaign was success, or error message if failed.

Description:
Change status of campaign to active.
This call is in critical section, which means it locks access to entity it operates on for the execution time. When locked no other critical actions may take place. Also this call may fail if anything else locked current entity before it.

Error:
Request: campaign with given id not exist for current user.
Limit: activating campaign require at least one free campaign limit, and that much keywords as it have.

PHP example code:

examples/Monitoring/CampaignStart.php

Curl:

curl -X POST -d '{ "id": [ __CAMPAIGN_ID_1__, __CAMPAIGN_ID_2__, (...) ] }' http://api.semstorm.com/api-v3/monitoring/monitoring-campaign/start.json?services_token=__ACCESS_TOKEN__

Output:

{ __CAMPAIGN_ID_1__: 1, __CAMPAIGN_ID_2__: 1, (...) }

Stop campaign

Endpoint:
http://api.semstorm.com/api-v3/monitoring/monitoring-campaign/stop [POST]

Parameters   PHP  CURL 
parameter method type required default  description
id POST mixed yes - Array with campaign ids. For backwards compatibility works also as integer for one campaign.
Output   RESULT 
method type description
result array Array with results and/or error messages, keyed by campaigns ids.
result[_CAMPAIGN_ID_] mixed True if change status for given campaign was success, or error message if failed.

Description:
Change status of campaign to stop.
This call is in critical section, which means it locks access to entity it operates on for the execution time. When locked no other critical actions may take place. Also this call may fail if anything else locked current entity before it.

Error:
Request: campaign with given id not exist for current user.

PHP example code:

examples/Monitoring/CampaignStop.php

Curl:

curl -X POST -d '{ "id": [ __CAMPAIGN_ID_1__, __CAMPAIGN_ID_2__, (...) ] }' http://api.semstorm.com/api-v3/monitoring/monitoring-campaign/stop.json?services_token=__ACCESS_TOKEN__

Output:

{ __CAMPAIGN_ID_1__: 1, __CAMPAIGN_ID_2__: 1, (...) }

Delete campaign

Endpoint:
http://api.semstorm.com/api-v3/monitoring/monitoring-campaign/delete [POST]

Parameters   PHP  CURL 
parameter method type required default  description
id POST mixed yes - Array with campaign ids. For backwards compatibility works also as integer for one campaign.
Output   RESULT 
method type description
result array Array with results and/or error messages, keyed by campaigns ids.
result[_CAMPAIGN_ID_] mixed True if change status for given campaign was success, or error message if failed.

Description:
Change status of campaign to delete.
This call is in critical section, which means it locks access to entity it operates on for the execution time. When locked no other critical actions may take place. Also this call may fail if anything else locked current entity before it.

Error:
Campaign with given id not exist for current user.

PHP example code:

examples/Monitoring/CampaignDelete.php

Curl:

curl -X POST -d '{ "id": [ __CAMPAIGN_ID_1__, __CAMPAIGN_ID_2__, (...) ] }' http://api.semstorm.com/api-v3/monitoring/monitoring-campaign/delete.json?services_token=__ACCESS_TOKEN__

Output:

{ __CAMPAIGN_ID_1__: 1, __CAMPAIGN_ID_2__: 1, (...) }

Restore campaign

Endpoint:
http://api.semstorm.com/api-v3/monitoring/monitoring-campaign/restore [POST]

Parameters   PHP  CURL 
parameter method type required default  description
id POST mixed yes - Array with campaign ids. For backwards compatibility works also as integer for one campaign.
Output   RESULT 
method type description
result array Array with results and/or error messages, keyed by campaigns ids.
result[_CAMPAIGN_ID_] mixed True if change status for given campaign was success, or error message if failed.

Description:
Change status of campaign from delete to stop.
This call is in critical section, which means it locks access to entity it operates on for the execution time. When locked no other critical actions may take place. Also this call may fail if anything else locked current entity before it.

Error:
Campaign with given id not exist for current user.

PHP example code:

examples/Monitoring/CampaignRestore.php

Curl:

curl -X POST -d '{ "id": [ __CAMPAIGN_ID_1__, __CAMPAIGN_ID_2__, (...) ] }' http://api.semstorm.com/api-v3/monitoring/monitoring-campaign/restore.json?services_token=__ACCESS_TOKEN__

Output:

{ __CAMPAIGN_ID_1__: 1, __CAMPAIGN_ID_2__: 1, (...) }

Get list of campaigns

Endpoint:
http://api.semstorm.com/api-v3/monitoring/monitoring-campaign/get-list [POST]

Parameters   PHP  CURL 
parameter method type required default  description
type POST array no seo Array with types of campaigns to retrieve. Proper values are "seo", "ads". Works also for string as one type.
pager POST array no Pager settings. See below for structure details.
filters POST array no Filters. See below for structure details.
Pager array
parameter type required default  description
items_per_page integer no 25 Page size (how many campaigns are in one page). Possible values are: 1, 5, 10, 25, 50, 100, 500, 1000.
page integer no 0 Page number to retrieve, starting from 0.
Fitlers array
parameter type required default  description
engine mixed no All Engine id (int) or "All" (string) for all engines.
status array no Array with statuses (strings), possible values: "active", "stop", "delete". Default: all statuses.
bookmark mixed no All 0 - non bookmarked campaigns. 1 - bookmarked campaigns. 'All' - both.
title string no Title or part of title to filter. Default: empty string.
Output   RESULT 
method type description
result["count"] int Number of all campaigns (for better pagination).
result["campaigns"] array Array with campaigns.
result["campaigns"][]["id"] int Campaign id.
result["campaigns"][]["access"] string User access type.
result["campaigns"][]["status"] string Campaign status, possible values: "active", "stop", "delete".
result["campaigns"][]["domain"] string Campaign domain.
result["campaigns"][]["type"] string Campaign type, possible values: "seo", "ads", "trash".

Description:
Get campaigns set selected by pager.

Error:
Throttling: Possible throttle prevention.

PHP example code:

examples/Monitoring/CampaignList.php

Curl:

curl -X POST -d '{ "pager": { "items_per_page":10, "page":1 } }' http://api.semstorm.com/api-v3/monitoring/monitoring-campaign/get-list.json?services_token=__ACCESS_TOKEN__

Output:

{ "campaigns"[ (...) ], "count":27 }

Get overview data about multiple campaigns

Endpoint:
http://api.semstorm.com/api-v3/monitoring/monitoring-campaign/get-overview-data [POST]

Parameters   PHP  CURL 
parameter method type required default  description
gap POST string no daily Date gap to aggregate data by, possible values are "daily", "weekly", "monthly".
datemin POST string no Report start date in format YYYYmmdd eg. 20160901. Default: day 2 weeks ago.
datemax POST string no daily Report end date in format YYYYmmdd eg. 20170530. Default: yesterday.
device POST array no all Devices array to filter by. If not defined all devices will be included.
engine POST string no 0 Engine id to filter by. To know what engines are possible and their ids see monitoring-tables/engines section.
pager POST array no Pager settings.
Pager array
parameter type required default  description
page int no 0 Page number to retrieve counted from 0.
Output   RESULT 
method type description
result array Array with campaigns data keyed by campaign ids.
result[_CAMPAIGN_ID_] array Array with campaign data.
result[_CAMPAIGN_ID_]["id"] array Campaign id.
result[_CAMPAIGN_ID_]["name"] array Campaign name.
result[_CAMPAIGN_ID_]["domain"] array Campaign domain.
result[_CAMPAIGN_ID_]["status"] array Campaign status.
result[_CAMPAIGN_ID_]["keywords_count"] array Campaign keywords count.
result[_CAMPAIGN_ID_]["keywords_count_up"] array Campaign keywords with position rise (in comparison to previous time period).
result[_CAMPAIGN_ID_]["keywords_count_no_change"] array Campaign keywords with unchanged position (in comparison to previous time period).
result[_CAMPAIGN_ID_]["keywords_count_down"] array Campaign keywords with position fall (in comparison to previous time period).
result[_CAMPAIGN_ID_]["keywords_top10_count"] array Campaign top 10 keywords count.
result[_CAMPAIGN_ID_]["visibility"] array Campaign visibility.
result[_CAMPAIGN_ID_]["visibility_change"] array Campaign visibility change (in comparison to previous time period).

Description:
Get information about campaigns, similar to data in monitoring dashboard.

Error:
Throttling: Possible throttle prevention.

Curl:

curl -X POST -d '{"gap": "monthly", "engine": 272 }' http://api.semstorm.com/api-v3/monitoring/monitoring-campaign/get-overview-data.json?services_token=__ACCESS_TOKEN__

Output:

(see php example for example result)

Get detailed data about campaigns

Endpoint:
http://api.semstorm.com/api-v3/monitoring/monitoring-campaign/get-data [POST]

Parameters   PHP  CURL 
parameter method type required default  description
id POST integer yes - Campaign id to retrieve.
domains POST mixed no Array of domains or string with one domain. Default: campaign domain.
type POST string no organic Type of data to retrieve, valid values are "organic", "paid" and "maps".
datemin POST string no Report start date in format YYYYmmdd eg. 20160901. Default: day 2 weeks ago.
datemax POST string no Report end date in format YYYYmmdd eg. 20170530. Default: yesterday.
gap POST string no daily Date gap to aggregate data by, possible values are "daily", "weekly", "monthly".
filters POST array no Advanced filters, for more details see "Advanced filters" section here. Default: empty array.
Output   RESULT 
method type description
result array Array with query results divided by groups ids.
result[_GROUP_ID_] array Array with group data divided by domains.
result[_GROUP_ID_][_DOMAIN_] array Array with domain data divided by keywords ids.
result[_GROUP_ID_][_DOMAIN_][_KEYWORD_ID_] array Keyword data and info.
result[_GROUP_ID_][_DOMAIN_][_KEYWORD_ID_]["keyword"] array Array with keyword info.
result[_GROUP_ID_][_DOMAIN_][_KEYWORD_ID_]["keyword"]["title"] string Keyword title.
result[_GROUP_ID_][_DOMAIN_][_KEYWORD_ID_]["keyword"]["volume"] integer Keyword volume.
result[_GROUP_ID_][_DOMAIN_][_KEYWORD_ID_]["keyword"]["cpc"] string Keyword CPC.
result[_GROUP_ID_][_DOMAIN_][_KEYWORD_ID_]["data"] array Array with keyword data divided by date (date format depends on date gap).
result[_GROUP_ID_][_DOMAIN_][_KEYWORD_ID_]["data"][_DATE_] array Array with keyword data divided by engine.
result[_GROUP_ID_][_DOMAIN_][_KEYWORD_ID_]["data"][_DATE_][_ENGINE_] array Array with keyword data divided by device.
result[_GROUP_ID_][_DOMAIN_][_KEYWORD_ID_]["data"][_DATE_][_ENGINE_][_DEVICE_] array Array with keyword data divided by location.
result[_GROUP_ID_][_DOMAIN_][_KEYWORD_ID_]["data"][_DATE_][_ENGINE_][_DEVICE_][_LOCATION_] array Array with keyword data.
result[_GROUP_ID_][_DOMAIN_][_KEYWORD_ID_]["data"][_DATE_][_ENGINE_][_DEVICE_][_LOCATION_]["position"] number Domain position on given keyword with parameters and date specified in result keys. If date gap is set to daily it will be integer, otherwise it is average.
result[_GROUP_ID_][_DOMAIN_][_KEYWORD_ID_]["data"][_DATE_][_ENGINE_][_DEVICE_][_LOCATION_]["url"] string Domain destination url on given keyword with parameters and date specified in result keys.

Description:
Get details about campaign keywords. It is data from "Daily rank tracking" tab in Monitoring/Keywords page in system.
In filters array you (optionally) specify your filters. It should be exact filters which are set in url when browsing monitoring page. Try this in system to see proper syntax.
For PHP library users: filters in input can be set using SemstormFilters class, which makes it a lot simplier. For details about SemstormFilters class see examples/Explorer/FiltersExplain.php and examples/Explorer/FiltersUsage.php files.

Error:
Throttling: Possible throttle prevention.

PHP example code:

examples/Monitoring/CampaignData.php

Curl:

curl -X POST -d '{"id": _ID_, "datemin": "20160901", "datemax": "20170530", "gap": "monthly", "domains": ["example.com", "example2.pl"] }' http://api.semstorm.com/api-v3/monitoring/monitoring-campaign/get-data.json?services_token=__ACCESS_TOKEN__

Output:

(see php example for example result)

Get campaigns access

Endpoint:
http://api.semstorm.com/api-v3/monitoring/monitoring-campaign/get-access [POST]

Input
parameter method type required default  description
Output   RESULT 
method type description
result array Array with campaigns access informations, keyed by campaigns ids.
result[_CAMPAIGN_ID_]["access"] string Your access level, possible values are: "owner", "manager", "readonly".
result[_CAMPAIGN_ID_]["owner"] string Owner e-mail address.

Endpoint: /monitoring/monitoring-campaign/get-access [POST]

Description:
Returns information about campaigns you have access to, with type of access and infrmation about owner (e-mail address).
Existing permissions are:
"owner" - this account can modify everything in campaign, add and remove roles. Its reserved for account which created campaign, and is persistent.
"manager" - this account can do everything as "owner" but this role can be removed.
"readonly" - account with that permission can only see campaign and its statistics, and cannot do any changes.

Error:
none.

PHP example code:

examples/Monitoring/CampaignGetAccess.php

Curl:

curl -X POST http://api.semstorm.com/api-v3/monitoring/monitoring-campaign/get-access.json?services_token=__ACCESS_TOKEN__

Output:

(see php example for example result)

Set campaigns access

Endpoint:
http://api.semstorm.com/api-v3/monitoring/monitoring-campaign/set-access [POST]

Parameters   PHP  CURL 
parameter method type required default  description
__CAMPAIGN_ID__ POST array yes - Array with access modifications for given campaign.
Campaign array
parameter type required default  description
set array no Array with accesses to set for given campaign (add or modify existing). Default: empty array.
remove array no Array with accesses to remove for given campaign. Default: empty array.
Set array
parameter type required default  description
mail string yes - User e-mail for whom access will be set.
permission string yes - Permission level to set, possible values are: "readonly", "manager".
Remove array
parameter type required default  description
mail string yes - User e-mail for whom access will be removed.
Output   RESULT 
method type description
result array Array with access modifications results, keyed by campaigns ids.
result[_CAMPAIGN_ID_]["set"][_USER_MAIL_] bool True if change was successful, false otherwise.
result[_CAMPAIGN_ID_]["remove"][_USER_MAIL_] bool True if removal was successful, false otherwise.

Description:
Set access to campaigns, you need to have proper access level to modify permissions in campaigns.
This api endpoint is limited to one request per 10 seconds.
By this api call you can alter maximum 3 accounts at once. That means "set" array shouldn't have more than 3 records. There is no limit in removing access.
Proper permissions to give and take are "readonly" and "manager". One more permission named "owner" is reserved for account which created campaign and cannot be modified.
If you will try to grant permission by entering e-mail on which there is no registered account in SEMSTORM system, then the invitation e-mail to craete account will be send.

Error:
Request: too fast requesting, if any campaign id invalid (user might not have permissions) or if access updating failed. Access updating will fail if: you try to modify permissions in campaign you have "readonly" access, you try to remove or change permission level of the owner of campaign, one or more e-mail address is invalid.
Throttling: this request is specially limited to one per 10 seconds.

PHP example code:

examples/Monitoring/CampaignSetAccess.php

Curl:

curl -X POST -d '{ "__CAMPAIGN_ID__": { "set": [ (...) ], "remove": [ (...) ] }}' http://api.semstorm.com/api-v3/monitoring/monitoring-campaign/set-access.json?services_token=__ACCESS_TOKEN__

Output:

{ "result": { "__CAMPAIGN_ID__": { "set": [ (...) ], "remove": [ (...) ] } } }

Monitoring Group

Create group

Endpoint:
http://api.semstorm.com/api-v3/monitoring/monitoring-group [POST]

Parameters   PHP  CURL 
parameter method type required default  description
campaign_id POST integer yes - Campaign id in which create group.
title POST string yes - Group title.
engine POST integer yes - Engine id - it must be set in pair with proper country id (see here).
country POST integer yes - Country id - it must be set in pair with proper engine id (see here).
location POST string no Location name. If not specified then location will be saved as empty and not used.
devices POST array yes - Array with at least one device name (strings).
Output   RESULT 
method type description
result array Array with results and/or error messages.
result["id"] string Id of newly created group.

Description:
Create new group in specified campaign.

Error:
Request: any of required fields missing, campaign id invalid (user might not have permissions), engine-country invalid combination, devices array invalid.

PHP example code:

examples/Monitoring/GroupCreate.php

Curl:

curl -X POST -d '{ "campaign_id":__ID__, "title":"New group", "engine": 2, "country": 168, "location": "warszawa", "devices": ["mobile"] }' http://api.semstorm.com/api-v3/monitoring/monitoring-group.json?services_token=__ACCESS_TOKEN__

Output:

{ "id": "12345" }

Retrieve group data

Endpoint:
http://api.semstorm.com/api-v3/monitoring/monitoring-group/{_GROUP_ID_} [GET]

Parameters   PHP  CURL 
parameter method type required default  description
_GROUP_ID_ url integer yes - Group id to retrieve.
Output   RESULT 
method type description
result["id"] integer Group id.
result["title"] string Group title.
result["status"] string Group status.
result["created_time"] string Group create timestamp.
result["changed_time"] string Group last modification timestamp.
result["keywords"] array Group keywords ids.
result["engine"] integer Engine id.
result["country"] integer Country id.
result["location"] string Location name.
result["devices"] array Array of devices (strings).

Description:
Get data about group.

Error:
Request: group id invalid (user might not have permissions).

PHP example code:

examples/Monitoring/GroupRetrieve.php

Curl:

curl http://api.semstorm.com/api-v3/monitoring/monitoring-group/_GROUP_ID_.json?services_token=__ACCESS_TOKEN__

Output:

{"id": _ID_, "title": "Group title", "status": "active", "created_time": "1415794727", "changed_time": "1415794727", "keywords": [ __KEYWORD_ID__, __KEYWORD_ID__, __KEYWORD_ID__, (...) ], "engine": "2", "country": "168","location": "warszawa","devices": ["desktop"]}

Update group data

Endpoint:
http://api.semstorm.com/api-v3/monitoring/monitoring-group/{_GROUP_ID_} [PUT]

Parameters   PHP  CURL 
parameter method type required default  description
_GROUP_ID_ url integer yes - Group id to update.
title POST string no Group title. Default: current title.
engine POST integer no Country id - it must be set in pair with proper engine id (see here). Default: current engine.
country POST integer no Country id - it must be set in pair with proper engine id (see here). Default: current country.
location POST string no Location name. When not specified location will be saved as empty and not used. Default: current location.
devices POST array no Array with at least one device name (strings). Default: current devices.
Output   RESULT 
method type description
result bool Value is true on success.

Description:
Change data of group
This call is in critical section, which means it locks access to entity it operates on for the execution time. When locked no other critical actions may take place. Also this call may fail if anything else locked current entity before it..
To set "location" parameter to empty pass there empty string. This will be interpreted as no location specified.

Error:
Request: group with given id not exist for current user, engine-country invalid combination, devices array invalid.
Limit: updating group can change keywords usage. Eg. when changing from one device to both all keywords in group will be counted twice.

PHP example code:

examples/Monitoring/GroupUpdate.php

Curl:

curl -X PUT -d '{"title": "new name", "engine": 2, "country": 168, "location": "łódź", "devices": ["mobile", "desktop"]}' http://api.semstorm.com/api-v3/monitoring/monitoring-group/_ID_.json?services_token=__ACCESS_TOKEN__

Output:

[ true ]

Start group

Endpoint:
http://api.semstorm.com/api-v3/monitoring/monitoring-group/start [POST]

Parameters   PHP  CURL 
parameter method type required default  description
id POST mixed yes - Array with group ids. For backwards compatibility works also as integer for one group.
Output   RESULT 
method type description
result array Array with results and/or error messages, keyed by groups ids.
result[_GROUP_ID_] mixed True if change status for given group was success, or error message if failed.

Description:
Change status of group to active.
This call is in critical section, which means it locks access to entity it operates on for the execution time. When locked no other critical actions may take place. Also this call may fail if anything else locked current entity before it.

Error:
Request: group with given id not exist for current user.
Limit: activating group require that much keywords as it have.

PHP example code:

examples/Monitoring/GroupStart.php

Curl:

curl -X POST -d '{ "id": [ __GROUP_ID_1__, __GROUP_ID_2__, (...) ] }' http://api.semstorm.com/api-v3/monitoring/monitoring-group/start.json?services_token=__ACCESS_TOKEN__

Output:

{ __GROUP_ID_1__: 1, __GROUP_ID_2__: 1, (...) }

Stop group

Endpoint:
http://api.semstorm.com/api-v3/monitoring/monitoring-group/stop [POST]

Parameters   PHP  CURL 
parameter method type required default  description
id POST mixed yes - Array with group ids. For backwards compatibility works also as integer for one group.
Output   RESULT 
method type description
result array Array with results and/or error messages, keyed by groups ids.
result[_GROUP_ID_] mixed True if change status for given group was success, or error message if failed.

Description:
Change status of group to stop.
This call is in critical section, which means it locks access to entity it operates on for the execution time. When locked no other critical actions may take place. Also this call may fail if anything else locked current entity before it.

Error:
Request: group with given id not exist for current user.

PHP example code:

examples/Monitoring/GroupStop.php

Curl:

curl -X POST -d '{ "id": [ __GROUP_ID_1__, __GROUP_ID_2__, (...) ] }' http://api.semstorm.com/api-v3/monitoring/monitoring-group/stop.json?services_token=__ACCESS_TOKEN__

Output:

{ __GROUP_ID_1__: 1, __GROUP_ID_2__: 1, (...) }

Delete group

Endpoint:
http://api.semstorm.com/api-v3/monitoring/monitoring-group/delete [POST]

Parameters   PHP  CURL 
parameter method type required default  description
id POST mixed yes - Array with group ids. For backwards compatibility works also as integer for one group.
Output   RESULT 
method type description
result array Array with results and/or error messages, keyed by groups ids.
result[_GROUP_ID_] mixed True if change status for given group was success, or error message if failed.

Description:
Change status of group to delete.
This call is in critical section, which means it locks access to entity it operates on for the execution time. When locked no other critical actions may take place. Also this call may fail if anything else locked current entity before it.

Error:
Request: group with given id not exist for current user.

PHP example code:

examples/Monitoring/GroupDelete.php

Curl:

curl -X POST -d '{ "id": [ __GROUP_ID_1__, __GROUP_ID_2__, (...) ] }' http://api.semstorm.com/api-v3/monitoring/monitoring-group/delete.json?services_token=__ACCESS_TOKEN__

Output:

{ __GROUP_ID_1__: 1, __GROUP_ID_2__: 1, (...) }

Restore group

Endpoint:
http://api.semstorm.com/api-v3/monitoring/monitoring-group/restore [POST]

Parameters   PHP  CURL 
parameter method type required default  description
id POST mixed yes - Array with group ids. For backwards compatibility works also as integer for one group.
Output   RESULT 
method type description
result array Array with results and/or error messages, keyed by groups ids.
result[_GROUP_ID_] mixed True if change status for given group was success, or error message if failed.

Description:
Change status of group to stop.
This call is in critical section, which means it locks access to entity it operates on for the execution time. When locked no other critical actions may take place. Also this call may fail if anything else locked current entity before it.

Error:
Request: group with given id not exist for current user.

PHP example code:

examples/Monitoring/GroupRestore.php

Curl:

curl -X POST -d '{ "id": [ __GROUP_ID_1__, __GROUP_ID_2__, (...) ] }' http://api.semstorm.com/api-v3/monitoring/monitoring-group/restore.json?services_token=__ACCESS_TOKEN__

Output:

{ __GROUP_ID_1__: 1, __GROUP_ID_2__: 1, (...) }

Get list of groups

Endpoint:
http://api.semstorm.com/api-v3/monitoring/monitoring-group/get-list [POST]

Parameters   PHP  CURL 
parameter method type required default  description
campaign_id POST integer yes - Campaign id from which retrieve groups.
pager POST array no Pager settings. See below for structure details.
Pager array
parameter type required default  description
items_per_page integer no 25 Page size (how many campaigns are in one page). Possible values are: 1, 5, 10, 25, 50, 100, 500, 1000.
page integer no 0 Page number to retrieve, starting from 0.
Output   RESULT 
method type description
result["count"] int Number of all groups (for better pagination).
result["groups"] array Array with groups.
result["groups"][]["id"] integer Group id.
result["groups"][]["title"] string Group title.
result["groups"][]["keywords_count"] integer Group keywords count (important its not number of keywords in group but evaluated 'cost' counted in limit, so if you have two devices set in group keywords_count will be doubled beacuse each keyword will be scanned twice).
result["groups"][]["status"] string Group status.
result["groups"][]["engine"] integer Engine id.
result["groups"][]["country"] integer Country id.
result["groups"][]["location"] string Array with groups.
result["groups"][]["devices"] array Array of devices (strings).

Description:
Gets list of campaign groups.

Error:
Request: campaign with given id not exist for current user.

PHP example code:

examples/Monitoring/GroupList.php

Curl:

curl -X POST -d '{ "campaign_id": 7189, "pager": { "items_per_page": 10, "page": 1 } }' http://api.semstorm.com/api-v3/monitoring/monitoring-group/get-list.json?services_token=__ACCESS_TOKEN__

Output:

(see php example for example result)

Get group data

Endpoint:
http://api.semstorm.com/api-v3/monitoring/monitoring-campaign/get-data [POST]

Description:
Simpliest way to retrieve keywords data is by using "group"-"entity" filter with group id. See example for details.

Error:
Throttling: Possible throttle prevention.

PHP example code:

examples/Monitoring/GroupData.php

Curl:

curl -X POST -d '{ "id": __CAMPAIGN_ID_1__, "filters": {"type": "include", "field": "group_nid_mv", "op": "entity", "value": [ [__GROUP_ID_1__: __GROUP_ID_1__] ]}, (...) }' http://api.semstorm.com/api-v3/monitoring/monitoring-keyword/get-data.json?services_token=__ACCESS_TOKEN__

Output:

(see php example for example result)

Create multiple

Endpoint:
http://api.semstorm.com/api-v3/monitoring/monitoring-group/create-multiple [POST]

Parameters   PHP  CURL 
parameter method type required default  description
campaign_id POST string yes - Campaign id in which create groups.
groups POST array yes - Array with groups data to create. It can be assoc array, then keys will be preserved in results for easiest results reading.
Groups array
parameter type required default  description
<group-distinguisher> array yes - Array with single group data to create.
Group array
parameter type required default  description
title string yes - Group title.
engine integer yes - Engine id - it must be set in pair with proper country id (see here).
country integer yes - Country id - it must be set in pair with proper engine id (see here).
location string no Location name. If not specified then location will be saved as empty and not used.
devices array yes - Array with at least one device name (strings).
Output   RESULT 
method type description
result["id"] array Array with information about creating each group, indexed same way as input.
result["id"][<group-distinguisher>] mixed True if creation of group was success, or error message if failed.

Description:
Create multiple groups in campaign. Its behavior is very similar to creating one group, except it takes array with groups params to create multiple groups.
"Groups" variable can be assoc array, instead of normal array - in that case returning information about each group creation will preserve keys so you can easily determine which output is for which group.

Error:
Request: campaign with given id not exist for current user, any groups data invalid.

PHP example code:

examples/Monitoring/GroupCreateMultiple.php

Curl:

curl -X POST -d '{ "campaign_id": 1234, "groups": { "new group 1": (...), "new group 2": (...) } }' http://api.semstorm.com/api-v3/monitoring/monitoring-group/create-multiple.json?services_token=__ACCESS_TOKEN__

Output:

{ "id":{ "new group 1": 123456, "new group 2": 123457 } }

Update multiple

Endpoint:
http://api.semstorm.com/api-v3/monitoring/monitoring-group/update-multiple [POST]

Parameters   PHP  CURL 
parameter method type required default  description
groups POST array yes - Array with groups data, keyed by groups ids.
Groups array
parameter type required default  description
_GROUP_ID_ array yes - Array with single group data to update.
Group array
parameter type required default  description
title string no Group title.
engine integer no Country id - it must be set in pair with proper engine id (see here). Default: current engine.
country integer no Country id - it must be set in pair with proper engine id (see here). Default: current country.
location string no Location name. When not specified location will be saved as empty and not used. Default: current location.
devices array no Array with at least one device name (strings). Default: current devices.
Output   RESULT 
method type description
result["id"] array Array with information about creating each group, keyed by groups ids.
result["id"][_GROUP_ID_] mixed True if updating of group was success, or error message if failed.

Description:
Update multiple groups in campaign. Its behavior is very similar to updating one group, except it takes array with groups params to update multiple groups.

Error:
Request: group with given id not exist for current user, any group data invalid.

PHP example code:

examples/Monitoring/GroupUpdateMultiple.php

Curl:

curl -X POST -d '{ "groups": { "__GROUP_ID_1__": {(...)}, "__GROUP_ID_2__": {(...)} } }' http://api.semstorm.com/api-v3/monitoring/monitoring-group/update-multiple.json?services_token=__ACCESS_TOKEN__

Output:

{ "id":{ __GROUP_ID_1__: true, __GROUP_ID_2__: true } }

Monitoring Keyword

Create keyword

Endpoint:
http://api.semstorm.com/api-v3/monitoring/monitoring-keyword [POST]

Parameters   PHP  CURL 
parameter method type required default  description
group_id POST integer yes - Group id in which create keywords.
keywords POST array yes - Array of keywords to add (strings). It can be assoc array, then keys will be preserved in results for easiest results reading.
Output   RESULT 
method type description
result["id"] array Array with information about creating each keyword, indexed same way as input.
result["id"][] mixed True if creation of keyword was success, or error message if failed.

Description:
Create new keywords in group.

Error:
Request: group with given id not exist for current user.

PHP example code:

examples/Monitoring/KeywordCreate.php

Output:

curl -X POST -d '{ "group_id": _ID_, "keywords": [ "keyword 1", "keyword 2", "keyword 3", (...)] }' http://api.semstorm.com/api-v3/monitoring/monitoring-keyword.json?services_token=__ACCESS_TOKEN__

Output:

{ "id": [ "12345", "12346", "12347", (...) ] }

Retrieve keyword data

Endpoint:
http://api.semstorm.com/api-v3/monitoring/monitoring-keyword/{_KEYWORD_ID_} [GET]

Parameters   PHP  CURL 
parameter method type required default  description
_KEYWORD_ID_ url integer yes - Keyword id to retrieve.
Output   RESULT 
method type description
result["id"] string Keyword id.
result["title"] string Keyword title.
result["status"] string Keyword status.
result["group_id"] string Group id in which keyword is.

Description:
Get data about keyword.

Error:
Request: keyword with given id not exist for current user.

PHP example code:

examples/Monitoring/KeywordCreate.php

Curl:

curlhttp://api.semstorm.com/api-v3/monitoring/monitoring-keyword/_KEYWORD_ID_.json?services_token=__ACCESS_TOKEN__

Output:

{ "id": "_ID_", "title": "keyword 1", "status": "active", "group_id": "_GROUP_ID_" }

Start keyword

Endpoint:
http://api.semstorm.com/api-v3/monitoring/monitoring-keyword/start [POST]

Parameters   PHP  CURL 
parameter method type required default  description
id POST mixed yes - Array with keyword ids. For backwards compatibility works also as integer for one keyword.
Output   RESULT 
method type description
result array Array with results and/or error messages, keyed by keywords ids.
result[_KEYWORD_ID_] mixed True if change status for given keyword was success, or error message if failed.

Description:
Change status of keywords to active.
This call is in critical section, which means it locks access to entity it operates on for the execution time. When locked no other critical actions may take place. Also this call may fail if anything else locked current entity before it.

Error:
Request: keyword with given id not exist for current user.
Limit: activating keyword require at least one free keyword limit.

PHP example code:

examples/Monitoring/KeywordCreate.php

Curl:

curl -X POST -d '{ "id": [ __KEYWORD_ID_1__, __KEYWORD_ID_2__, (...) ] }' http://api.semstorm.com/api-v3/monitoring/monitoring-keyword/start.json?services_token=__ACCESS_TOKEN__

Output:

{ __KEYWORD_ID_1__: 1, __KEYWORD_ID_2__: 1, (...) }

Stop keyword

Endpoint:
http://api.semstorm.com/api-v3/monitoring/monitoring-keyword/stop [POST]

Parameters   PHP  CURL 
parameter method type required default  description
id POST mixed yes - Array with keyword ids. For backwards compatibility works also as integer for one keyword.
Output   RESULT 
method type description
result array Array with results and/or error messages, keyed by keywords ids.
result[_KEYWORD_ID_] mixed True if change status for given keyword was success, or error message if failed.

Description:
Change status of keywords to stop.
This call is in critical section, which means it locks access to entity it operates on for the execution time. When locked no other critical actions may take place. Also this call may fail if anything else locked current entity before it.

Error:
Request: keyword with given id not exist for current user.

PHP example code:

examples/Monitoring/KeywordStop.php

Curl:

curl -X POST -d '{ "id": [ __KEYWORD_ID_1__, __KEYWORD_ID_2__, (...) ] }' http://api.semstorm.com/api-v3/monitoring/monitoring-keyword/stop.json?services_token=__ACCESS_TOKEN__

Output:

{ __KEYWORD_ID_1__: 1, __KEYWORD_ID_2__: 1, (...) }

Delete keyword

Endpoint:
http://api.semstorm.com/api-v3/monitoring/monitoring-keyword/delete [POST]

Parameters   PHP  CURL 
parameter method type required default  description
id POST mixed yes - Array with keyword ids. For backwards compatibility works also as integer for one keyword.
Output   RESULT 
method type description
result array Array with results and/or error messages, keyed by keywords ids.
result[_KEYWORD_ID_] mixed True if change status for given keyword was success, or error message if failed.

Description:
Change status of keywords to delete.
This call is in critical section, which means it locks access to entity it operates on for the execution time. When locked no other critical actions may take place. Also this call may fail if anything else locked current entity before it.

Error:
Request: keyword with given id not exist for current user.

PHP example code:

examples/Monitoring/KeywordDelete.php

Curl:

curl -X POST -d '{ "id": [ __KEYWORD_ID_1__, __KEYWORD_ID_2__, (...) ] }' http://api.semstorm.com/api-v3/monitoring/monitoring-keyword/delete.json?services_token=__ACCESS_TOKEN__

Output:

{ __KEYWORD_ID_1__: 1, __KEYWORD_ID_2__: 1, (...) }

Restore keyword

Endpoint:
http://api.semstorm.com/api-v3/monitoring/monitoring-keyword/restore [POST]

Parameters   PHP  CURL 
parameter method type required default  description
id POST mixed yes - Array with keyword ids. For backwards compatibility works also as integer for one keyword.
Output   RESULT 
method type description
result array Array with results and/or error messages, keyed by keywords ids.
result[_KEYWORD_ID_] mixed True if change status for given keyword was success, or error message if failed.

Description:
Change status of keywords from deleted to stoped.
This call is in critical section, which means it locks access to entity it operates on for the execution time. When locked no other critical actions may take place. Also this call may fail if anything else locked current entity before it.

Error:
Request: keyword with given id not exist for current user.

PHP example code:

examples/Monitoring/KeywordRestore.php

Curl:

curl -X POST -d '{ "id": [ __KEYWORD_ID_1__, __KEYWORD_ID_2__, (...) ] }' http://api.semstorm.com/api-v3/monitoring/monitoring-keyword/restore.json?services_token=__ACCESS_TOKEN__

Output:

{ __KEYWORD_ID_1__: 1, __KEYWORD_ID_2__: 1, (...) }

Change group of keywords

Endpoint:
http://api.semstorm.com/api-v3/monitoring/monitoring-keyword/change-group [POST]

Parameters   PHP  CURL 
parameter method type required default  description
group_id POST integer yes - Destined group id to where keywords will be moved.
id POST array yes - Array with keywords ids.
Output   RESULT 
method type description
result array Array with results and/or error messages, keyed by keywords ids.
result[_KEYWORD_ID_] mixed True if moving of keyword was success, or error message if failed.

Description:
Takes keywords and move them to specified group. Each keyword can be from different group/campaign as long as you have access to edit those.

Error:
Request: group with given id not exist for current user. Any of keyword id is invalid. Limits exceeded - this is possible eg. if you move keywords from group with one device to other with two.

PHP example code:

examples/Monitoring/KeywordChangeGroup.php

Curl:

curl -X POST -d '{ "group_id": __GROUP_ID__, "id": [ __KEYWORD_ID__, __KEYWORD_ID__, (...) ] }' http://api.semstorm.com/api-v3/monitoring/monitoring-keyword/change-group.json?services_token=__ACCESS_TOKEN__

Output:

{ __KEYWORD_ID__: 1, __KEYWORD_ID__: 1, (...) }

Get list of keywords

Endpoint:
http://api.semstorm.com/api-v3/monitoring/monitoring-keyword/get-list [POST]

Parameters   PHP  CURL 
parameter method type required default  description
campaign_id POST integer yes - Array with group ids. For backwards compatibility works also as integer for one group.
pager POST array no Pager settings. See below for structure details.
filters POST array no Filters. See below for structure details.
Pager array
parameter type required default  description
items_per_page integer no 25 Page size (how many campaigns are in one page). Possible values are: 1, 5, 10, 25, 50, 100, 500, 1000.
page integer no 0 Page number to retrieve, starting from 0.
Fitlers array
parameter type required default  description
keyword string no Keyword title or part of keyword title to filter. Default: empty string.
group_name string no Group name or part of group name to filter. Default: empty string.
status array no Array with statuses (strings), possible values: "active", "stop"". Default: empty array.
Output   RESULT 
method type description
result array Array with results and/or error messages, keyed by groups ids.
result["count"] integer Number of all keywords (for better pagination).
result["keywords"] array Array with keywords.
result["keywords"][]["id"] integer Keyword id.
result["keywords"][]["title"] string Keyword title.
result["keywords"][]["status"] string Keyword status, possible values: "active", "stop", "delete".
result["keywords"][]["group_id"] integer Group id in which keyword is.
result["keywords"][]["group_status"] string Group status in which keyword is.

Description:
Gets list of campaign keywords.
Important! If you put "delete" into status filter, you will see only deleted keywords, and other statuses will be ignored.
Use "active" and "stop" separately from "delete" filter.

Error:
Request: campaign with given id not exist for current user.

PHP example code:

examples/Monitoring/KeywordList.php

Curl:

curl -X POST -d '{ "campaign_id": _ID_, "pager": { "items_per_page": 25, "page": 1 } }' http://api.semstorm.com/api-v3/monitoring/monitoring-keyword/get-list.json?services_token=__ACCESS_TOKEN__

Output:

{ "count": 123, "keywords": [ (...)] }

Get keyword data

Endpoint:
http://api.semstorm.com/api-v3/monitoring/monitoring-campaign/get-data [POST]

Description:
Simpliest way to retrieve keywords data is by using "keyword"-"equals" filter with keyword full name. See example for details.

Error:
Throttling: Possible throttle prevention.

PHP example code:

examples/Monitoring/KeywordData.php

Curl:

curl -X POST -d '{ "id": __CAMPAIGN_ID_1__, "filters": {"type": "include", "field": "keyword", "op": "equal", "value": [ "kredyt" ]}, (...) }' http://api.semstorm.com/api-v3/monitoring/monitoring-keyword/get-data.json?services_token=__ACCESS_TOKEN__

Output:

(see php example for example result)

Get keyword details

Endpoint:
http://api.semstorm.com/api-v3/monitoring/monitoring-keyword/get-details [POST]

Parameters   PHP  CURL 
parameter method type required default  description
id POST array yes - Array with keyword ids. For backwards compatibility works also as integer for one keyword.
type POST string no heatmap Type of data to retrieve, valid values are "heatmap", "competitors" and "top50". Type "heatmap" and "competitors" returns same data, just refers to other visual representation in system panel.
datemin POST string no Report start date in format YYYYmmdd eg. 20160901. Default: day 2 weeks ago.
datemax POST string no Report end date in format YYYYmmdd eg. 20170530. Default: yesterday.
gap POST string no daily Date gap to aggregate data by, possible values are "daily", "weekly", "monthly".
Output   RESULT 
method type description
result array Array with results and/or error messages, keyed by keywords ids.
result[_KEYWORD_ID_] array Array with keyword data, keyed by device name.
result[_KEYWORD_ID_][_DEVICE_] array Array with device data, keyed by domain.
result[_KEYWORD_ID_][_DEVICE_][_DOMAIN_] array Array with domain data, keyed by date.
result[_KEYWORD_ID_][_DEVICE_][_DOMAIN_][_DATE_] array Domain data on given keyword, device and date specified in result keys.
result[_KEYWORD_ID_][_DEVICE_][_DOMAIN_][_DATE_]["position"] number Domain position. If date gap is set to daily it will be integer, otherwise it is average value.
result[_KEYWORD_ID_][_DEVICE_][_DOMAIN_][_DATE_]["position_change"]* number Domain position change. * - this value is available only for type "top50".
result[_KEYWORD_ID_][_DEVICE_][_DOMAIN_][_DATE_]["url"]* string Domain url. * - this value is available only for type "top50".

Description:
Retrieve details about keywords. Each of keyword (idetified by keyword id) can have few results, depending on group device count it is in.
Output differs depends on chosen "type".

Error:
Throttling: Possible throttle prevention.

PHP example code:

examples/Monitoring/KeywordList.php

Curl:

curl -X POST -d '{ "id": [ __KEYWORD_ID_1__, (...) ], "params": { "type": "competitors", (...) } }' http://api.semstorm.com/api-v3/monitoring/monitoring-keyword/get-details.json?services_token=__ACCESS_TOKEN__

Output:

(see php example for example result)

Monitoring Tables

Endpoint: http://api.semstorm.com/api-v3/monitoring/monitoring-tables/{_TABLE_NAME_} [GET]

Parameters   PHP  CURL 
method type required default  description
url string yes - Name of table to retrieve.
Output   RESULT 
method type description
result[_TABLE_NAME_] array Content of given table.

Description:
This endpoint is used to retrieve information about current API params.
Currently there are two tables possible to retrieve: "engines" which contains full set of engine-country ids collection, and "devices" which is lsit of possible devices names.

Error:
Wrong table name.

Table of engines

Endpoint:
http://api.semstorm.com/api-v3/monitoring/monitoring-tables/engines [GET]

Input
parameter method type required default  description
Output   RESULT 
method type description
result["engines"][]["name"] string Engine name.
result["engines"][]["id"] integer Engine id.
result["engines"][]["countries"] array Countries list for given engine.
result["engines"][]["countries"][]["name"] string Country name.
result["engines"][]["countries"][]["id"] integer Country id.

Description:
Return table containing all possible engines and countries variations.

Error:
None.

PHP example code:

examples/Monitoring/TablesEngines.php

Curl:

curl http://api.semstorm.com/api-v3/monitoring/monitoring-tables/engines.json?services_token=__ACCESS_TOKEN__

Output:

(see php example for example result)

Table of devices

Endpoint:
http://api.semstorm.com/api-v3/monitoring/monitoring-tables/devices [GET]

Input
parameter method type required default  description
Output   RESULT 
method type description
result["devices"] array Array with proper devices names (strings).

Description:
Return table containing proper devices names.

Error:
None.

PHP example code:

examples/Monitoring/TablesDevices.php

Curl:

curl http://api.semstorm.com/api-v3/monitoring/monitoring-tables/devices.json?services_token=__ACCESS_TOKEN__

Output:

{"devices": [ "mobile", "desktop" ]}

API errors

Authorization errors

Passing invalid token (or not passing at all) in request will result in authorization error.

PHP example code:

examples/Monitoring/ErrorAuthorization.php

Curl:

curl http://api.semstorm.com/api-v3/monitoring/monitoring-campaign/_ID_.json?services_token=this-is-wrong-access-token

Output:

[ "Unauthorised access." ]

Errors messages

When error occurs you can check "message" in "error" variable returned from server.

PHP example code:

examples/Monitoring/ErrorSimple.php

Curl:

curl http://api.semstorm.com/api-v3/monitoring/monitoring-campaign/123456.json?services_token=__ACCESS_TOKEN__

Output:

{"error": { "message": "(404) No entry for given id." }

Bulk operations errors

In some requests errors returns more information. For example bulk operations returns array with information which operations succeded and which failed.

PHP example code:

examples/Monitoring/ErrorBulk.php

Curl:

curl -X POST -d '{ "id": [_CAMPAIGN_ID_1_, _CAMPAIGN_ID_2_, (...)] }' http://api.semstorm.com/api-v3/monitoring/monitoring-campaign/start.json?services_token=__ACCESS_TOKEN__

Output:

(see php example for example result)

Throttle prevention errors

Error with code 503 in most cases will concern throttle prevention. If error message will contain "Throttle prevention. Data may be incomplete(...)" that means system was overloaded and refused to sustain connection.
This is temporary problem, you can retry your request after few secons - just remember that very large request will require more time to wait.
If problem sustains it propably means you are requesting too big set of data at once. Try split it into few smaller requests.

PHP example code:

There is no example of this error, as it happens occasionaly for big set of data.

Curl:

There is no example of this error, as it happens occasionaly for big set of data.

Output:

{ "params": {(...)}, "error": { "message": "(503) Service unavailable. Throttle prevention. Data may be incomplete. Try again later.", "result": {(...)} } }