Marketing API Version

Ad Keyword Stats

Stats specific to each interest, or keyword, targeted by an ad. Specify keywords for an ad in the ad set's targeting spec. Keywords arealso known as Interests in Ads Manager.

When someone sees an ad targeting multiple keywords, attribute the impression to all those interests if they fall in that interest segment.

If someone with sports and outdoor interests sees an ad targeting both, attribute 1 impression to sports and 1 to outdoor. If someone has only sports as an interest, attribute 1 impression to sports and 0 impressions to outdoor.

Limits

Can be query for the past 7 days excluding the current day. The IDs specified in ad_ids must be for ads active in the past 7 days and the ads must use interest targeting.

Reading

Stats on the ad's interest targeting options (previously known as keywords)

Permissions

Developers usually request these permissions for this endpoint:

  • ads_management

Examples

Query the keywordstats connection of the Ad object:

<API_VERSION>/<AD_ID>/keywordstats

To query from a particular day in the last week:

<API_VERSION>/<AD_ID>/keywordstats?date=YYYY-MM-DD

Response

A sample response looks like this:

{
  "data": {
    "Good Housekeeping": {
      "id": "<id>",
      "name": "Good Housekeeping",
      "impressions": "65205",
      "unique_impressions": "52824",
      "clicks": "3209",
      "unique_clicks": "3175",
      "total_actions": "3383",
      "total_unique_actions": "2973",
      "actions": [
        {
          "action_type": "photo_view",
          "value": "42"
        },
        {
          "action_type": "video_view",
          "value": "40"
        },
        {
          "action_type": "post",
          "value": "31"
        },
        {
          "action_type": "unlike",
          "value": "1"
        },
        {
          "action_type": "post_like",
          "value": "74"
        },
        {
          "action_type": "like",
          "value": "2931"
        },
        {
          "action_type": "comment",
          "value": "1"
        },
        {
          "action_type": "link_click",
          "value": "263"
        },
....
        }
      ],
      "unique_actions": [
        {
          "action_type": "photo_view",
          "value": "38"
        },
        {
          "action_type": "video_view",
          "value": "17"
        },
        {
          "action_type": "post",
          "value": "28"
        },
        {
          "action_type": "unlike",
          "value": "1"
        },
        {
          "action_type": "post_like",
          "value": "56"
        },
        {
          "action_type": "like",
          "value": "2929"
        },
....
        }
      ]
    },
    "Better Homes and Gardens (TV series)": {...}
  }
}
If you want to learn how to use the Graph API, read our Using Graph API guide.

Parameters

This endpoint doesn't have any parameters.

Fields

FieldDescription

id

numeric string

Keyword id

actions

The total number of actions people took that are attributed to your ads. Actions may include engagement, clicks or conversions.

clicks

unsigned int32

The total number of clicks on your ad. This may include offsite clicks to your website, Page likes, post comments, event responses or app installs.

cost_per_total_action

float

The average cost of a relevant action.

cost_per_unique_click

float

The average cost for each unique link click (all) on your ad.

cpc

float

The average cost for each click (all) attributed to your ads.

cpm

float

The average cost for 1,000 impressions.

cpp

float

The average cost to reach 1,000 people.

ctr

float

Click-through rate for all clicks. The total number of clicks you received (ex: offsite clicks, likes, event responses) divided by the number of impressions.

frequency

float

The average number of times each person saw your ad.

impressions

unsigned int32

The number of times your ads were viewed.

name

string

Keyword name

reach

unsigned int32

The number of people who saw your ads at least once. Reach is different from impressions, which may include multiple views of your ads by the same people.

spend

float

The total amount of money you've spent on your campaign, ad set or ad during its schedule.

total_actions

unsigned int32

The total number of actions people took that are attributed to your ads. Actions may include engagement, clicks or conversions.

total_unique_actions

unsigned int32

The number of people who took an action that was attributed to your ads.

unique_actions

The number of people who took an action that was attributed to your ads.

unique_clicks

unsigned int32

The total number of unique people who have clicked on your ad. Ex: if 3 people click on the same ad 5 times, it will count as 3 unique clicks.

unique_ctr

float

Unique click-through rate for all clicks. The number of people who clicked anywhere in your ad, divided by the number of people you reached. Ex: if you received 20 unique clicks and your ad was shown to 1,000 unique people, your unique click-through rate would be 2%.

unique_impressions

unsigned int32

The number of people who saw your ads at least once. Reach is different from impressions, which may include multiple views of your ads by the same people.

Edges

No edges

Creating

You can't perform this operation on this endpoint.

Updating

You can't perform this operation on this endpoint.

Deleting

You can't perform this operation on this endpoint.