Introduction to Action Spec
Related Topics

In this document


The Open Graph presents a simple, consistent view of the Facebook social graph, uniformly representing objects in the graph and the connections between them. The Action Spec is a comprehensive and precise query language within the API that provides you with access to the Open Graph. The Action Spec enables you to specify the sub-graph of interest for the purpose of running and measuring marketing activities on Facebook. You can specify the action type and properties of the object of interest using selectors. In essence, selectors are the building blocks of an Action Spec query. You can apply these to a number of marketing apps such as:

The Action Spec is an extremely powerful framework that gives you complete and precise access to the entire social graph to manage and optimize your marketing presence on Facebook. See the list of available on site objects and actions in Defining Action Specs.

Measuring Conversions using Action Spec

When running ads that point to a page, app, or website with social plugins, you can use the conversion spec to define specific actions to track back to ads using multiple click and view through attribution windows. Conversion specs enable marketers to measure and optimize their ad campaigns to very specific downstream actions.

Below are three examples of ways you can use the Action Spec to measure the performance of your ads.

If you are interested in driving awareness for a product, you can sponsor a video page post featuring that product. For the page post, you can set up a custom conversion spec to track actions such as:

  • Number of video plays on that page post
  • Number of video plays on any video on the page
  • Number of likes on that specific page post
  • Number of users posting on the page’s wall

If you are running an offer and sponsoring the offer claims through news feed posts, you can set up the conversion spec to track actions such as:

  • Number of users who claimed the offer
  • Number of users who became fans of the page
  • Number of users who commented, liked, or shared any page post on the page

If you are promoting a page and interested in acquiring new fans, you can create a page like page post and set up a custom conversion spec to track actions such as:

  • Number of page likes

Number of views of a specific page tab (e.g., “wall”). If you do not specify a conversion spec for a given ad or page post that points to an app or website, the default conversion spec will be used.

  • Ads that point to a page will be set up with “page_story” as the conversion spec. This will track any action that impacts the “people talking about this” metric (page likes, page post likes, comments, @mentions, check-ins, photo tags, page post shares (including offer shares), votes, follows, and offer claims)
  • App stories will be set up with “app_engagement” as the conversion spec. This will track "App install," "App used," and "credits spent" (does not include app shares)
  • Event ads will be set up with RSVPs- Number of RSVPs (yes and maybe) to an event


You cannot create a conversion spec for an object for which you do not have permission to advertise. Because the default conversion spec for ads pointing to apps contains potentially sensitive insights, we will also disable the default conversion spec for app ads if those ads are created by someone who is not an admin of that app

For more information on conversion specs, go here