Ad¶

An ad is the deliverable unit: one creative (video, playable or image) shown to the audience of its ad set. Each Nova Play ad set contains 3 to 5 ads; an account has roughly 30 to 50 ads in total. Ads are the lowest level at which insights can be requested (level=ad).

Naming convention¶

{FORMAT}_{CONCEPT}_v{VERSION}

Part	Values	Meaning
`FORMAT`	`VID`, `PLAY`, `IMG`	Creative format: video, playable, static image.
`CONCEPT`	`Gameplay15s`, `Gameplay30s`, `Tutorial`, `BossFight`, `FailCompilation`, `Satisfying`, `Meme`, `StoryIntro`, `UpgradeLoop`, `Challenge`	Creative concept.
`VERSION`	`1`..`9`	Iteration number.

Example: PLAY_Satisfying_v4. The name prefix is the only place where playable ads are distinguishable from video ads: both have creative.object_type = "VIDEO". Playables additionally carry creative.asset_feed_spec.playable_asset_id.

Fields¶

Field	Type	Description
`id`	string	Ad id (17 digits). Always returned.
`name`	string	See naming convention.
`adset_id`	string	Parent ad set id.
`campaign_id`	string	Parent campaign id.
`account_id`	string	Numeric ad account id, without `act_`.
`status`	string	Configured status: `ACTIVE` or `PAUSED`.
`configured_status`	string	Same as `status`.
`effective_status`	string	`ACTIVE`, `PAUSED`, `CAMPAIGN_PAUSED` (parent campaign paused) or `ARCHIVED` (parent campaign ended).
`creative`	object	The ad creative, see below. Supports nested field selection.
`created_time`	datetime	When the ad started delivering, `YYYY-MM-DDT08:00:00+0000`.
`updated_time`	datetime	Last change; for paused ads, the day they were paused.
`tracking_specs`	array	`[{ "action.type": ["mobile_app_install"], "application": ["<application_id>"] }]`.

Default fields when fields is omitted: id,name.

`creative`¶

Full object (returned by fields=creative):

{
  "id": "12023710517544387",
  "name": "VID_UpgradeLoop_v2 creative",
  "object_type": "VIDEO",
  "call_to_action_type": "INSTALL_MOBILE_APP",
  "asset_feed_spec": {
    "ad_formats": ["SINGLE_VIDEO"]
  }
}

Key	Description
`id`	Creative id. Different from the ad id; one creative per ad in this sandbox.
`name`	Ad name followed by `creative`.
`object_type`	`VIDEO` for video and playable ads, `PHOTO` for image ads.
`call_to_action_type`	Always `INSTALL_MOBILE_APP`.
`asset_feed_spec`	`{ "ad_formats": ["SINGLE_VIDEO"] }` or `["SINGLE_IMAGE"]`; playables add `"playable_asset_id"`.

Nested field selection¶

Ask for a subset of the creative with braces. id is always included in the nested object.

fields=id,name,creative{id,name,object_type}

Edges¶

Edge	Description
`/<ad_id>/insights`	Performance for this ad. Default `level=ad`.

List ads of an account: `GET /act_<account_id>/ads`¶

Returns every ad in the account, across all campaigns and ad sets. With the default limit of 25 you will need more than one page; set limit=500 to get them in one call.

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

curl -G "https://graph.huydata.com/v21.0/act_199454714457591/ads" \
  -d "access_token=$META_ACCESS_TOKEN" \
  -d "fields=id,name,adset_id,campaign_id,status,effective_status,creative{id,name,object_type}" \
  -d "limit=3"

{
  "data": [
    {
      "id": "12024133208777808",
      "name": "VID_UpgradeLoop_v2",
      "adset_id": "12029269518058219",
      "campaign_id": "12020064400866904",
      "status": "ACTIVE",
      "effective_status": "ACTIVE",
      "creative": {
        "id": "12023710517544387",
        "name": "VID_UpgradeLoop_v2 creative",
        "object_type": "VIDEO"
      }
    },
    {
      "id": "12025889893776797",
      "name": "VID_FailCompilation_v3",
      "adset_id": "12029269518058219",
      "campaign_id": "12020064400866904",
      "status": "ACTIVE",
      "effective_status": "ACTIVE",
      "creative": {
        "id": "12022243190086259",
        "name": "VID_FailCompilation_v3 creative",
        "object_type": "VIDEO"
      }
    },
    {
      "id": "12028175088840265",
      "name": "VID_Challenge_v3",
      "adset_id": "12029269518058219",
      "campaign_id": "12020064400866904",
      "status": "ACTIVE",
      "effective_status": "ACTIVE",
      "creative": {
        "id": "12029144502147881",
        "name": "VID_Challenge_v3 creative",
        "object_type": "VIDEO"
      }
    }
  ],
  "paging": {
    "cursors": {
      "before": "b2Zmc2V0OjA",
      "after": "b2Zmc2V0OjM"
    },
    "next": "https://graph.huydata.com/v21.0/act_199454714457591/ads?fields=id%2Cname%2Cadset_id%2Ccampaign_id%2Cstatus%2Ceffective_status%2Ccreative%7Bid%2Cname%2Cobject_type%7D&limit=3&access_token=...&after=b2Zmc2V0OjM"
  }
}

List ads of an ad set or campaign: `GET /<adset_id>/ads`, `GET /<campaign_id>/ads`¶

Same parameters and response shape, restricted to the parent. Calling /ads on an ad id returns error 100 (Tried accessing nonexisting field (ads) on node type (Ad)).

curl -G "https://graph.huydata.com/v21.0/12029269518058219/ads" \
  -d "access_token=$META_ACCESS_TOKEN" \
  -d "fields=id,name,status,effective_status,created_time,updated_time"

{
  "data": [
    {
      "id": "12024133208777808",
      "name": "VID_UpgradeLoop_v2",
      "status": "ACTIVE",
      "effective_status": "ACTIVE",
      "created_time": "2026-04-18T08:00:00+0000",
      "updated_time": "2026-04-18T08:00:00+0000"
    },
    {
      "id": "12026127595876205",
      "name": "VID_Tutorial_v1",
      "status": "PAUSED",
      "effective_status": "PAUSED",
      "created_time": "2026-05-26T08:00:00+0000",
      "updated_time": "2026-07-03T08:00:00+0000"
    },
    {
      "id": "12026126969631519",
      "name": "PLAY_Satisfying_v4",
      "status": "PAUSED",
      "effective_status": "PAUSED",
      "created_time": "2026-05-05T08:00:00+0000",
      "updated_time": "2026-06-12T08:00:00+0000"
    },
    "..."
  ],
  "paging": {
    "cursors": {
      "before": "b2Zmc2V0OjA",
      "after": "b2Zmc2V0OjU"
    }
  }
}

A paused ad delivers through its updated_time day and produces no insights rows after that, but it keeps appearing in listings. Keep them: historical insights rows still reference their ids.

Read one ad: `GET /<ad_id>`¶

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

curl -G "https://graph.huydata.com/v21.0/12024133208777808" \
  -d "access_token=$META_ACCESS_TOKEN" \
  -d "fields=id,name,adset_id,campaign_id,account_id,status,effective_status,creative,created_time,tracking_specs"

{
  "id": "12024133208777808",
  "name": "VID_UpgradeLoop_v2",
  "adset_id": "12029269518058219",
  "campaign_id": "12020064400866904",
  "account_id": "199454714457591",
  "status": "ACTIVE",
  "effective_status": "ACTIVE",
  "creative": {
    "id": "12023710517544387",
    "name": "VID_UpgradeLoop_v2 creative",
    "object_type": "VIDEO",
    "call_to_action_type": "INSTALL_MOBILE_APP",
    "asset_feed_spec": {
      "ad_formats": ["SINGLE_VIDEO"]
    }
  },
  "created_time": "2026-04-18T08:00:00+0000",
  "tracking_specs": [
    {
      "action.type": ["mobile_app_install"],
      "application": ["5040209235711335"]
    }
  ]
}

With a nested selection:

curl -G "https://graph.huydata.com/v21.0/12024133208777808" \
  -d "access_token=$META_ACCESS_TOKEN" \
  -d "fields=id,name,creative{id,name,object_type,call_to_action_type}"

{
  "id": "12024133208777808",
  "name": "VID_UpgradeLoop_v2",
  "creative": {
    "id": "12023710517544387",
    "name": "VID_UpgradeLoop_v2 creative",
    "object_type": "VIDEO",
    "call_to_action_type": "INSTALL_MOBILE_APP"
  }
}

Ad¶

Naming convention¶

Fields¶

creative¶

Nested field selection¶

Edges¶

List ads of an account: GET /act_<account_id>/ads¶

List ads of an ad set or campaign: GET /<adset_id>/ads, GET /<campaign_id>/ads¶

Read one ad: GET /<ad_id>¶

`creative`¶

List ads of an account: `GET /act_<account_id>/ads`¶

List ads of an ad set or campaign: `GET /<adset_id>/ads`, `GET /<campaign_id>/ads`¶

Read one ad: `GET /<ad_id>`¶