Campaign¶

A campaign is the top-level object under an ad account. It holds the marketing objective, the budget and the delivery schedule; targeting lives on the ad sets below it and creatives on the ads. Each Nova Play ad account has 2 to 4 campaigns.

Naming convention¶

Nova Play names every campaign with a fixed pattern:

{GAME}_{PLATFORM}_{OS}_{GEO}_{OBJECTIVE}_{YYYYMM}

Part	Values	Meaning
`GAME`	`DMS`, `IME`, `ZSD`, `PBM`, `CML`, `CPM`, `SST`, `HTD`, `WGS`, `PSV`	Three-letter game code (Dragon Merge Saga, Idle Mining Empire, Zombie Siege Defense, Puzzle Blast Mania, Castle Match Legends, Car Park Master 3D, Sushi Shop Tycoon, Hero Tower Defense, Word Garden Story, Pixel Survivors).
`PLATFORM`	`FB`	Ad platform. Always `FB` on this API.
`OS`	`AND`, `IOS`	Operating system of the promoted game.
`GEO`	`T1`, `SEA`, `LATAM`, `EA`	Region group targeted by the campaign. T1 = US, GB, CA, AU, DE; SEA = VN, ID, PH, TH; LATAM = BR, MX; EA = JP, KR, TW.
`OBJECTIVE`	`INSTALL`, `VALUE`	Business goal: volume of installs, or purchase value (ROAS).
`YYYYMM`	e.g. `202607`	Year and month the campaign started.

Example: DMS_FB_AND_T1_VALUE_202607 is a Dragon Merge Saga campaign on Android, targeting tier-1 countries, optimised for purchase value, started July 2026. When two campaigns in the same account would collide, the second gets a _B suffix.

Note that the API objective field is OUTCOME_APP_PROMOTION for every campaign. The INSTALL / VALUE distinction appears in the name, in bid_strategy (LOWEST_COST_WITHOUT_CAP for INSTALL, LOWEST_COST_WITH_MIN_ROAS for VALUE) and in the ad set's optimization_goal (APP_INSTALLS vs VALUE).

Fields¶

Field	Type	Description
`id`	string	Campaign id (17 digits). Always returned.
`name`	string	See naming convention above.
`account_id`	string	Numeric ad account id, without the `act_` prefix.
`objective`	string	Always `OUTCOME_APP_PROMOTION`.
`status`	string	Configured status: `ACTIVE`, `PAUSED` or `ARCHIVED` (campaign ended).
`configured_status`	string	Same as `status`.
`effective_status`	string	Status as actually delivering: `ACTIVE`, `PAUSED` or `ARCHIVED`.
`buying_type`	string	Always `AUCTION`.
`bid_strategy`	string	`LOWEST_COST_WITHOUT_CAP` (INSTALL campaigns) or `LOWEST_COST_WITH_MIN_ROAS` (VALUE campaigns).
`daily_budget`	string	Daily budget in cents of the account currency. `"97000"` = 970.00 USD.
`budget_remaining`	string	In cents. In this sandbox it equals `daily_budget`.
`start_time`	datetime	First day of delivery, `YYYY-MM-DDT00:00:00+0000`.
`stop_time`	datetime	Day after the last day of delivery. Omitted when the campaign has no end date.
`created_time`	datetime	Creation timestamp.
`updated_time`	datetime	Last update timestamp.
`special_ad_categories`	array	Always `[]`.
`smart_promotion_type`	string	Always `GUIDED_CREATION`.
`is_budget_schedule_enabled`	bool	Always `false`.

Default fields when fields is omitted: id,name.

Fields whose value is null are dropped from the response rather than returned as null: a campaign that is still running has no stop_time key at all.

Edges¶

Edge	Description
`/<campaign_id>/adsets`	Ad sets in the campaign.
`/<campaign_id>/ads`	Ads in the campaign (across its ad sets).
`/<campaign_id>/insights`	Performance for this campaign. Default `level=campaign`.

List campaigns: `GET /act_<account_id>/campaigns`¶

Parameter	Type	Required	Description
`access_token`	string	yes	Personal token (or `Authorization: Bearer`).
`fields`	string	no	Comma-separated list of campaign fields. Default `id,name`.
`limit`	int	no	Page size, default 25, maximum 500.
`after`	string	no	Cursor from a previous page. See Paging.

Archived (ended) campaigns are included. Filter on effective_status client-side if you only want running ones; you will still need the archived ones to explain historical insights rows.

curl -G "https://graph.huydata.com/v21.0/act_199454714457591/campaigns" \
  -d "access_token=$META_ACCESS_TOKEN" \
  -d "fields=id,name,objective,status,effective_status,daily_budget,start_time,stop_time,bid_strategy,created_time,updated_time"

{
  "data": [
    {
      "id": "12020064400866904",
      "name": "DMS_FB_AND_T1_INSTALL_202604",
      "objective": "OUTCOME_APP_PROMOTION",
      "status": "ACTIVE",
      "effective_status": "ACTIVE",
      "daily_budget": "97000",
      "start_time": "2026-04-18T00:00:00+0000",
      "bid_strategy": "LOWEST_COST_WITHOUT_CAP",
      "created_time": "2026-04-17T04:00:00+0000",
      "updated_time": "2026-04-17T04:00:00+0000"
    },
    {
      "id": "12025898431825415",
      "name": "DMS_FB_AND_T1_VALUE_202607",
      "objective": "OUTCOME_APP_PROMOTION",
      "status": "ACTIVE",
      "effective_status": "ACTIVE",
      "daily_budget": "218000",
      "start_time": "2026-07-13T00:00:00+0000",
      "bid_strategy": "LOWEST_COST_WITH_MIN_ROAS",
      "created_time": "2026-07-10T02:00:00+0000",
      "updated_time": "2026-07-10T02:00:00+0000"
    },
    {
      "id": "12027158065922978",
      "name": "DMS_FB_AND_LATAM_VALUE_202608",
      "objective": "OUTCOME_APP_PROMOTION",
      "status": "ACTIVE",
      "effective_status": "ACTIVE",
      "daily_budget": "44000",
      "start_time": "2026-08-05T00:00:00+0000",
      "bid_strategy": "LOWEST_COST_WITH_MIN_ROAS",
      "created_time": "2026-08-02T05:00:00+0000",
      "updated_time": "2026-08-02T05:00:00+0000"
    },
    "..."
  ],
  "paging": {
    "cursors": {
      "before": "b2Zmc2V0OjA",
      "after": "b2Zmc2V0OjQ"
    }
  }
}

The first campaign started on 2026-04-18, before the beginning of the performance history (2026-06-30). Its insights are available from 2026-06-30 onwards only.

Read one campaign: `GET /<campaign_id>`¶

Parameter	Type	Required	Description
`access_token`	string	yes	Personal token.
`fields`	string	no	Comma-separated list of campaign fields. Default `id,name`.

curl -G "https://graph.huydata.com/v21.0/12020064400866904" \
  -d "access_token=$META_ACCESS_TOKEN" \
  -d "fields=id,name,account_id,objective,status,effective_status,configured_status,buying_type,bid_strategy,daily_budget,budget_remaining,start_time,stop_time,created_time,updated_time"

{
  "id": "12020064400866904",
  "name": "DMS_FB_AND_T1_INSTALL_202604",
  "account_id": "199454714457591",
  "objective": "OUTCOME_APP_PROMOTION",
  "status": "ACTIVE",
  "effective_status": "ACTIVE",
  "configured_status": "ACTIVE",
  "buying_type": "AUCTION",
  "bid_strategy": "LOWEST_COST_WITHOUT_CAP",
  "daily_budget": "97000",
  "budget_remaining": "97000",
  "start_time": "2026-04-18T00:00:00+0000",
  "created_time": "2026-04-17T04:00:00+0000",
  "updated_time": "2026-04-17T04:00:00+0000"
}

stop_time was requested but is not in the response because this campaign has no end date.

Errors specific to this object¶

`code`	`type`	Message	Cause
`100`	`OAuthException`	`(#100) Tried accessing nonexisting field (budget) on node type (Campaign)`	A name in `fields` is not a campaign field (here `budget` instead of `daily_budget`).
`100` (subcode `33`)	`GraphMethodException`	`Unsupported get request. Object with ID '...' does not exist, ...`	Unknown campaign id.

{
  "error": {
    "message": "(#100) Tried accessing nonexisting field (budget) on node type (Campaign)",
    "type": "OAuthException",
    "code": 100,
    "fbtrace_id": "AgPFmAMRIgRiW8BDjh1EI"
  }
}