Graph API Version

Ad Keyword Stats

Stats specific to each interest, or keyword, targeted by an ad. Provide keywords in ad set targeting spec. Keywords are known as Interests in Ads Manager.

When someone sees an ad targeting multiple keywords, we attribute the impression to all keywords if they fall in that interest segment. For example, 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

Query for the past 7 days excluding current day. The IDs you use 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

Request these permissions for this endpoint:

ads_management

Code Samples

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

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"
        },
....
        }
      ],
      "unique_actions": [
        {
          "action_type": "photo_view",
          "value": "38"
        },
        {
          "action_type": "video_view",
          "value": "17"
        },
....
          "action_type": "post_like",
          "value": "56"
        },
        {
          "action_type": "like",
          "value": "2929"
        },
....
        }
      ]
    },
    "Better Homes and Gardens (TV series)": {...}
  }
}

Parameters

This endpoint doesn't have any parameters.

Fields

Field	Description
`id` numeric string	Keyword id
`actions` list<AdsActionStats>	The total number of actions people took that are attributed to your ads. Actions may include engagement, clicks or conversions.
`clicks` unsigned int32	The number of clicks on your ads. Default
`cost_per_total_action` float	The average cost of a relevant action.
`cost_per_unique_click` float	The average cost for each unique click (all).
`cpc` float	The average cost for each click (all).
`cpm` float	The average cost for 1,000 impressions.
`cpp` float	The average cost to reach 1,000 people.
`ctr` float	The percentage of times people saw your ad and performed a click (all).
`frequency` float	The average number of times each person saw your ad.
`impressions` unsigned int32	The number of times your ads were on screen. Default
`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 estimated 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` list<AdsActionStats>	The number of people who took an action that was attributed to your ads.
`unique_clicks` unsigned int32	The number of people who performed a click (all). Default
`unique_ctr` float	The percentage of people who saw your ad and performed a unique click (all).
`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. Default

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.