SyncWith

Get started

Facebook Ads API

đź’ˇ
Looking for something in specific? Jump to a reference section: Popular Endpoints - our curated list of the most useful Facebook Graph API endpoints Interactive Examples - practical use cases, ready to run in the Graph API Explorer, with sample response JSON Troubleshooting - solutions for the most common Facebook API error codes
Facebook’s API was released in 2010. Soon afterwards, The Facebook API: A Case Study In Not Caring About Developers hit the front page of a popular programming forum. In the decade since, it often feels like not much has changed. The platform has evolved, but the documentation hasn’t always kept pace. Even when Facebook has documented a particular feature, their documentation URLs keep changing, meaning Google doesn’t always have the right page in their index when you search for it! Worse, just getting your API integration through Facebook’s app review process can be a painful, bureaucratic experience.
This article captures all of SyncWith’s hard-won experience building our easy-to-use integrations for Facebook Ads, Facebook Post Insights, Instagram Post Insights and Facebook Page Insights. It focuses on how to use the Facebook Marketing API to report on your Facebook and Instagram ad campaigns and social media properties. Hopefully it helps you!

I Wish I Could Just Sync FB Data

If you’re just hoping to sync data and want to leverage all the hard won battles we’ve had with Facebook’s API, we do offer many destinations where we can ship your FB data:
  • Facebook Ads API to Databases (S3, BigQuery, MySQL, Postgres) - contact support to join our beta

Other Facebook Articles

And now onwards to the Facebook API

The Graph API

Every Facebook API request looks like this:
notion image
 
In practice, there are two kinds of endpoints:
Facebook models its data as a giant interconnected graph of things. They use language from graph theory to describe each request. The first type of request is for a node (the me node). The second type of request is for the edges of a node (the adaccount edges of the me node).
đź’ˇ
The terminology isn’t too important. Just beware that Facebook’s documentation often talks about Edges.

How to Identify a Node in Your Facebook API Request

Notice that every request has a node in it! There are three ways to identify a node in your requests:
  1. By its ID. Pages, posts, comments, users, ad accounts, campaigns, ad sets, ads: every thing in the Facebook universe has an ID. Many API calls will return IDs that you can use in future API calls.
  1. By its page URL. For example, Google’s Facebook page is https://www.facebook.com/Google/. You can use Google.
  1. By the special identifier me. Usually you won’t know what ID to use. So your first request will be to an endpoint that describes the resources you own. But how do you know what your ID is? To solve this problem, the Facebook API will always treat me specially, so that it returns data about the currently logged-in user.
Remember how we said that the Facebook API has evolved over the course of more than a decade? Even the shape of a node’s ID is inconsistent. There are at least three kinds of IDs:
  • Most IDs are just big numbers, for example 104958162837
  • Ad account IDs, which look like act_1413799628646329
  • Post IDs, which look like a page ID combined with another identifier, for example 86717889990_10150730856914991
You don’t really have to care about this, other than to recognize that the IDs may not be numbers, so if you’re storing them in a database, store them as a string.
đź’ˇ
Although the Graph API is Facebook’s proprietary API for accessing Facebook data, the ideas behind the Graph API eventually evolved into GraphQL. GraphQL has become a new, standardized way to query for data from APIs. Unfortunately, while the Graph API inspired GraphQL, the Graph API does not (yet?) support GraphQL itself.

Creating an App

Facebook lets anyone use their API, but you’ll have to set up a developer account, agree to some terms and conditions, and then create a “Facebook App” to get started. All of your future requests to the API will be tied back to your app, and to the individual user using your app. So no shady stuff!
The first step in creating an app is to register for a Facebook developer account.
You’ll need a Facebook account for this. As with all Facebook accounts, the account must be in your personal name. Creating the app for a business? Still use your personal account – you can grant access to a Business Manager account later.
  1. Go to Facebook for Developers
  1. Click “Get Started” in the upper right corner.
  1. Agree to the Platform Terms and Developer Policies.
  1. Verify your email address and phone number by getting a one-time code sent to you by email and SMS.
That’s it!

Creating the App

  1. Go to the Apps panel
  1. Click Create App
  1. Since you want to use the Facebook Ads API, pick Business as the app type.
notion image
  1. Fill in the basic information about your app. If this app is for a business, now’s a good time to link it to a Business Manager account. Don’t worry if you forget – you can always link it later.
notion image
  1. On the Add products page, you’ll want to enable the Marketing API. Find it and click the Set up button.
notion image
There’s no actual setup – just clicking the button is enough.
That’s it, that’s enough to get started!
You may want to add other products later. You can always add more products from the dashboard of your app. You might want to add:
  • Instagram Graph API, if you want to query Instagram posts and pages
  • Facebook Login, if you want your app to be used by users other than yourself

Permissions

Facebook groups their API into related sets of features. Access to each feature is controlled by a permission. There are a lot of them–the official Facebook API permissions reference lists 50 permissions. The most useful permissions for reporting on your Facebook metrics are:
  • ads_management OR ads_read - Either lets you fetch ads analytics data like impressions, reach, cost. ads_management is only needed if you want to use the API to create/pause campaigns, ad sets and ads.
  • leads_retrieval - To retrieve completed form submissions from users who engaged with your Facebook Lead Ads.
  • pages_read_engagement - To fetch analytics about engagement with your page’s posts, like follower names, likes, etc.
  • read_insights - To fetch analytics about reach and impressions of your page.
You’ll need to request the specific permissions as part of the process of getting a user access token, which we’ll discuss later.

App Review

đź’ˇ
By default, your Facebook app is in development mode. It has standard access for all of the Facebook API’s features. In this mode, only the app’s creator (you!) can use the API, and only to access data for your own pages, posts and ad accounts. If that works for you, you can skip the rest of this section!
If you want other users to use your service, or you want to access public information about other pages for competitive analysis, you’ll need to do app review. You must go through a review process for each and every permission that you want to use. For each permission, you’ll:
  • write some narrative text explaining why your app needs the permission
  • write a step-by-step guide on how a Facebook reviewer can access the part of your app that uses this permission
  • record a short, 1-2 minute screencast showing your app using the permission
It’s painful! You will likely get rejected the first few times. The reviewers will give a reason for the rejection, but often it will be so broad as to be useless. For example, when we were going through the process, we were rejected for violating section 1.9 of the Facebook Developer Policies.
Section 1.9 reads as follows:
You will follow any instructions we include in our technical documentation.
Not very helpful, eh? If the reason for your rejection is unclear, you can open a support question to ask for clarification. Once you understand the problem, fix it, record a new screencast, and resubmit your approval request.
Be patient–you’ll get approved eventually!

Making a Request

Graph API Explorer

The Facebook Graph API Explorer is a free tool published by Facebook. It is like a sandbox for developers. The Graph API Explorer makes it easy to send requests to different Facebook API endpoints. In particular, it hides much of the complexity of authenticating. This is very useful when first learning the API, as it lets you focus on the parts of the API that are specific to Facebook.
Throughout this article, when we provide a template request, we’ll often link to that request in the Graph API Explorer.
Video preview

User Token Authentication

Most requests to the Facebook Ads API need a user access token, passed in the Authorization header as a bearer token. For example, Authorization: Bearer YOUR-USER-ACCESS-TOKEN.
The exception is for endpoints that relate to Facebook page organic data. (But even then, you’ll need a user token in order to get a page token!)

How do I get a Facebook user access token?

Facebook user access tokens are issued via the Internet standard OAuth 2 protocol, using the authorization code grant flow.
notion image
Start the OAuth flow by sending the user to Facebook’s OAuth authorization URL. The URL should look like:
https://facebook.com/v13.0/dialog/oauth
  ?response_type=granted_scopes,code
  &scopes=ads_read+read_insights
  &client_id=YOUR-CLIENT-ID
  &redirect_uri=YOUR-URL-ENCODED-CALLBACK-URL
đź’ˇ
Note two things: 1. You must specify your desired permissions in the scopes parameter. 2. Pass the Facebook-specific extension response_type=granted_scopes,code to see which permissions the user consented to grant you. If you just pass response_type=code, you won’t know which permissions you were given.
Once the user has approved your request, Facebook will send them to your redirect URL.
Your redirect URL will issue a request to Facebook’s token URL at https://graph.facegbook.com/v13.0/oauth/access_token to get the access token.
You now have a user access token!
Learning the details of how to do OAuth is beyond the scope of this document. Many open-source libraries exist that will implement the OAuth protocol for you. We recommend searching your package manager for one, and following its instructions.

How long is a Facebook user access token valid?

Every Facebook user access token is valid for 90 days. The token can be invalidated before this time if the user revokes access to your application, changes their password, or logs out of Facebook.

How do I refresh a Facebook user access token?

You can’t! In the aftermath of the Cambridge Analytica scandal, Facebook users became a lot more sensitive about their data being abused by random app developers. As a result, user access tokens are only good for 90 days. After 90 days, you must send the user through the OAuth approval flow again to regain their consent.
You can read more about this change on Facebook’s developer blog.

How do I authenticate with a Facebook user access token?

The Facebook user access token should be sent as a Bearer token in the Authorization header. For example:
curl -H 'Authorization: Bearer EAAUFcAF...' https://graph.facebook.com/v13.0/me
It can also be sent as a query parameter called access_token if you’d prefer.

How can I inspect a Facebook user access token?

When the OAuth protocol completes, you’ll receive a granted_scopes parameter that indicates which permissions the user granted you access to. You can also assume that the token is valid for the next 90 days, so long as the user doesn’t revoke access to your app or change their Facebook password.
You can also use the /permissions endpoint or /debug_token endpoint to inspect a token.

Page Token Authentication

Requests for data associated with Facebook Pages are authenticated with a page access token, not a user access token.

How do I get a Facebook page access token?

Each page has its own unique access token. With a user access token that has the pages_show_list permission, make a request to the me/accounts endpoint.

How long is a Facebook page access token valid?

Unlike Facebook user access tokens, Facebook page access tokens never expire. They can be invalidated if the user who retrieved them revokes access to your app, changes their password, or logs out of Facebook.

How do I authenticate with a Facebook page access token?

The Facebook page access token should be sent as a query parameter called access_token. For example:
curl https://graph.facebook.com/v13.0/YOUR-FACEBOOK-PAGE-ID?access_token=EAAUFcA…

App Token Authentication

App tokens are tied only to your app. They only let you do operations related to your app, like measuring how many users are using it. You don’t need to use app tokens to use the Facebook Ads API.

Pagination

Even if your API request could return many thousand items, Facebook has a limit on the number of results that any single request will return. To retrieve the complete set of results, you will need to make multiple requests in sequence. This is called pagination.
Facebook uses cursor-based pagination. A response for an API request might look like:
{
  "data": [
     ... Endpoint data is here
  ],
  "paging": {
    "cursors": {
      "after": "MTAxNTExOTQ1MjAwNzI5NDE=",
      "before": "NDMyNzQyODI3OTQw"
    },
    "previous": "https://graph.facebook.com/{your-user-id}/albums?limit=25&before=NDMyNzQyODI3OTQw"
    "next": "https://graph.facebook.com/{your-user-id}/albums?limit=25&after=MTAxNTExOTQ1MjAwNzI5NDE="
  }
}
The presence of a paging object with a next key is a sign that your request has more results that still need to be fetched. Make a request to the URL specified in the paging.next key to fetch them. Repeat this process until there is no longer a next URL in the response. You can read more about Facebook’s pagination process on their website.

Rate Limits

Facebook calculates rate limits according to a complex formula. If your app or its users make too many requests in a short period of time, some of the requests may be temporarily rejected to protect Facebook’s infrastructure.
Generally speaking, the more successful you are, the more requests per hour Facebook will let you make.
For requests that use:
  • an app token, the limit is a function of how many users are using your app
  • a page access token, the limit is a function of how many users have engaged with your page in the past day
  • a user access token, the limit is a function of the resource that you are trying to access. For ads accounts, more ad impressions served in the past day will grant you higher rate limits.
If you hit the rate limit, just slow down and try again later. If you consistently hit the limit, consider changing your usage of the API to avoid re-fetching the same data, so that each request does more useful work.

Popular Endpoints

There are many different endpoints in the Facebook API. Every kind of object–pages, posts, comments, user profiles, albums, photos, ad accounts, campaigns, ad sets, ads–has multiple endpoints alone! We’ve curated the ones most relevant to social marketers.

Common Parameters

Many endpoints take two important parameters.

fields

The Facebook API can return huge amounts of data. By default, it returns a minimal amount. You will need to explicitly request the data you want by passing the fields query parameter with a comma-separated list of fields to return.
For example, the /v13.0/me endpoint returns this by default:
curl -H 'Authorization: Bearer EAUF...' https://graph.facebook.com/v13.0/me
{
  "name": "Colin Dellow",
  "id": "10104046205424917"
}
But if you pass the right query parameters, you can get a more informative response:
curl -H 'Authorization: Bearer EAUF...' \
  https://graph.facebook.com/v13.0/me?fields=id,name,picture
{
  "id": "10104046205424917",
  "name": "Colin Dellow",
  "picture": {
    "data": {
      "height": 50,
      "is_silhouette": false,
      "url": "https://platform-lookaside.fbsbx.com/platform/profilepic/?asid=10104046205424917&height=50&width=50&ext=1650729215&hash=AeTCGzCX1psXLcvJbdg",
      "width": 50
    }
  }
}

Field Expansion

You can also use a feature called field expansion to fine-tune the amount of nested data that gets returned. In this case, we’ll fetch only a subset of the picture data:
curl -H 'Authorization: Bearer EAUF...' \
  https://graph.facebook.com/v13.0/me?fields=id,name,picture{url}
{
  "id": "10104046205424917",
  "name": "Colin Dellow",
  "picture": {
    "data": {
      "url": "https://platform-lookaside.fbsbx.com/platform/profilepic/?asid=10104046205424917&height=50&width=50&ext=1650729215&hash=AeTCGzCX1psXLcvJbdg"
    }
  }
}

filtering

Many ads API endpoints can return large amounts of data:
  • /act_NNN/ads returns a row for each of your ads
  • /act_NNN/campaigns returns a row for each of your campaigns
  • /act_NNN/insights returns potentially thousands of rows per day that your ads are running
Often you only need a subset of the data. For example, ads that are in the ACTIVE state, campaigns that have a non-zero budget, or insights for people living in Canada.
Retrieving all the data and then filtering it after requires extra API calls. Instead, you can use the filtering parameter tell Facebook to filter the data before sending it to you
Facebook will only return a row of data if it matches all of the criteria in the filtering parameter. The parameter should be an array of filter clauses, serialized as JSON. Each clause identifies the field to be tested, the operator used to test it, and the permissible values.
For strings, the allowed operators are: IN, NOT_IN, CONTAIN, NOT_CONTAIN.
For numeric values, the allowed operators are: GREATER_THAN, LESS_THAN, EQUAL, NOT_EQUAL, IN_RANGE, NOT_IN_RANGE.
Some examples:
  • Filter /act_NNN/campaigns for only active campaigns:
      • filtering=[{"field":"effective_status","operator":"IN","value":"ACTIVE"}]
  • Filter /act_NNN/insights for users from Canada:
      • filtering=[{field:"country",operator:"IN",value:["CA"]}]
  • Filter /act_NNN/insights for rows with more than 10,000 impressions:
      • filtering=[{field:"impressions",operator:"GREATER_THAN",value:10000}]

limit

Any endpoint that returns multiple results also takes a limit parameter.
In order to make the fewest requests and get data as fast as possible, you should increase this to the maximum possible value. This varies by endpoint, but is generally 100 or 1000 items.

/v13.0/me

Facebook documentation URL: https://developers.facebook.com/docs/graph-api/reference/v13.0/user
The special identifier me will always return the user object of the user associated with the user access token that authenticated the request.
Use this endpoint for discovering the currently logged-in user’s name. The id and name fields are the most important fields in this response.
Interactive examples:
You can see a complete list of Facebook user fields and list of Facebook user edges here.

/v13.0/me/accounts

Facebook documentation URL: https://developers.facebook.com/docs/graph-api/reference/v13.0/user/accounts
The user accounts edge shows the Facebook pages for which the currently logged-in user is an admin.
Use this endpoint for discovering the IDs of Facebook pages, getting page access tokens, and getting the Instagram business account ID of an Instagram business account associated with a Facebook page.
Interactive examples:

/v13.0/me/adaccounts

Facebook documentation URL: https://developers.facebook.com/docs/marketing-api/reference/ad-account/v13.0
The user adaccounts edge shows the Facebook ad accounts to which the currently logged-in user has access.
Use this endpoint for discovering the IDs of Facebook ad accounts.
Interactive examples:

/v13.0/me/permissions

Facebook documentation URL: https://developers.facebook.com/docs/graph-api/reference/v13.0/user/permissions
The user permissions edge shows the results of the last authorization request for the currently logged-in user.
When you request access to a user's data on Facebook, the user may choose to selectively grant only some of the requested permissions:
notion image
Use this endpoint to discover which permissions the user granted your app, and which the user declined to grant your app.
Interactive examples:

/v13.0/act_NNN/ads

Facebook documentation URL: https://developers.facebook.com/docs/marketing-api/reference/adgroup/
The ad account ads edge provides static information about your ads, such as their name, text, associated images, call-to-action type, and status.
Use this endpoint to visualize which of your ads are running, and how the ad is presented to users.
Interactive examples:

/v13.0/act_NNN/campaigns

Facebook documentation URL: https://web.archive.org/web/20220218022423/https://developers.facebook.com/docs/marketing-api/reference/ad-campaign-group (note: Facebook's documentation is broken; this is an archived version)
The ad account campaigns edge provides static information about your campaigns, such as their name, start and end date, daily and lifetime budgets, remaining budget, and status.
Use this endpoint to visualize the pacing and lifetime of your campaigns.
Interactive examples:

/v13.0/act_NNN/insights

Facebook documentation URL: https://developers.facebook.com/docs/marketing-api/insights/parameters/v13.0
The ad account insights edge is the most important endpoint for monitoring your Facebook ad performance.
Use this endpoint to fetch key ad metrics like reach, spend, clicks, conversions and conversion values.
Interactive examples:

Important Parameters

  • date_preset: set this parameter to today, yesterday, this_month, last_month or one of the other date_preset parameter values to control the time range of your report. This parameter cannot be used with the time_ranges parameter.
  • fields: set this to a comma-separated list of fields to report on. See our list of Fields below for the most popular ones.
  • time_increment: set this parameter to all_days, monthly or an integer number of days to report at the daily, weekly, monthly or all-time level.
  • time_ranges: Set this parameter to a JSON object that describes a date range, for example, to get data for the first week of 2022, use {"since": "2022-01-01", "until": "2022-01-07"} This parameter cannot be used with the date_preset parameter.
  • level: Set this parameter to account, campaign, adset or ad to report at varying levels of granularity based on your account hierarchy.
  • breakdown: Set this parameter to age, country, gender or one of the other breakdown parameter values to report on more detailed demographic groups.

Popular Fields

The ad accounts insights endpoint supports hundreds of metrics, which you can report on by including them in the comma-separated fields parameter. You can see the complete list of fields here.
The most popular fields are:
  • spend: The amount spent, in your account's local currency.
  • impressions: The number of times one of your ads was seen by a person.
  • reach: The number of people who saw one of your ads.
  • clicks: The number of clicks on one of your ads.
  • ctr: The click-through rate of your ads, measured by number of clicks divided by number of impressions.
  • cpm: The cost per thousand impressions shown of your ads.
  • cpc: The cost per click of your ads.
  • frequency: The average number of times each user saw your ad.
  • account_id, account_name, campaign_id, campaign_name, adset_id, adset_name, ad_id, ad_name: Use these to report on the hierarchy of your advertising creatives.
  • actions, action_values, cost_per_action_type, cost_per_unique_action_type, conversions, conversion_values, cost_per_conversion: See the section on Actions and Conversions below.
For example, to report on spend and clicks by campaign name, you'd pass:
fields=spend,clicks,campaign_name

Actions and Conversions

Actions and conversions are things a user does that are reported to Facebook's tracking system. They could be clicking a link, adding an item to a cart, a custom conversion fired by your Facebook pixel integration, or dozens more. There's an incomplete list of action types on Facebook's website.
They are encoded in the response differently from simple metrics like spend or impressions. You can report on either the number of occurrences of the action (how many people added something to a cart) or the value of the action (what was the total dollar value of things added to the cart).
For example, if you wanted to analyze the performance of your e-commerce purchase funnel, you might ask for fields=actions,action_values,cost_per_action_type. You would get a response that looked like this:
{
  "data": [
    {
      "actions": [
        {
          "action_type": "omni_add_to_cart",
          "value": "198"
        },
        {
          "action_type": "omni_initiated_checkout",
          "value": "23"
        },
        {
          "action_type": "omni_purchase",
          "value": "18"
        }
      ],
      "action_values": [
        {
          "action_type": "omni_add_to_cart",
          "value": "1463.96"
        },
        {
          "action_type": "omni_initiated_checkout",
          "value": "857.27"
        },
        {
          "action_type": "omni_purchase",
          "value": "1325.25"
        }
      ],
      "cost_per_action_type": [
        {
          "action_type": "omni_add_to_cart",
          "value": "1.211768"
        },
        {
          "action_type": "omni_initiated_checkout",
          "value": "10.431739"
        },
        {
          "action_type": "omni_purchase",
          "value": "13.329444"
        }
      ],
      "date_start": "2022-02-24",
      "date_stop": "2022-03-25"
    }
  ]
}
With this data, you can calculate some key metrics:
  • drop-off rate at each stage of the funnel
  • total value of sales attributed to advertising
  • return on ad spend (ROAS)

Sorting

You can sort by at most one column, ascending or descending, by passing the sort parameter. Even though you can only pass one column, you must express it as an array.
Examples:
  • sort=["impressions_descending"]
  • sort=["actions:link_click_ascending"]

Synchronous vs Asynchronous Reports

Facebook documentation URL: https://developers.facebook.com/docs/marketing-api/insights/best-practices#asynchronous
The ad account insights endpoint can be called with the HTTP GET method. In this case, the response contains your desired ad performance data:
curl -H 'Authorization: Bearer EAAU...' \
  https://graph.facebook.com/v13.0/act_1413799628646329/insights
{
  "data": [
    {
      "account_id": "1413799628646329",
      "date_start": "2022-02-22",
      "date_stop": "2022-03-23",
      "impressions": "33019",
      "spend": "239.74"
    }
  ],
  ...pagination data
}
This works well for requests whose results can be quickly computed. Requests spanning a larger period of time, or breaking out the data by many dimensions may take too long to run for a synchronous request. In that case, you can do the same request using the HTTP POST method. The request will quickly return a response with a pending report ID:
curl -XPOST -H 'Authorization: Bearer EAAU...' \
  https://graph.facebook.com/v13.0/act_1413799628646329/insights
{"report_run_id": "646810956382915"}
This report is just another object in the Facebook system. Naturally, you can use the Facebook API to query its status:
curl -H 'Authorization: Bearer EAAU...' \
  https://graph.facebook.com/v13.0/646810956382915
{
  "id": "646810956382915",
  "account_id": "1413799628646329",
  "async_status": "Job Running"
}
Keep polling this endpoint until the async_status field changes to Job Completed.
At this point, you can make one final request to fetch the data:
curl -H 'Authorization: Bearer EAAU...' \
  https://graph.facebook.com/v13.0/646810956382915/insights
{
  "data": [
    {
      "account_id": "1413799628646329",
      "date_start": "2022-02-22",
      "date_stop": "2022-03-23",
      "impressions": "33019",
      "spend": "239.74"
    }
  ],
  ...paging data
}

/v13.0/act_NNN/customconversions

Facebook documentation URL: https://developers.facebook.com/docs/marketing-api/reference/custom-conversion/
The ad account customconversions edge lists your user-defined conversion event types.
Facebook has a comprehensive set of pre-defined conversion event types like Link Click, Add To Cart, Pageview, etc. You can also choose to use your own conversion event types that fire via the Facebook pixel.
Use this edge to map a custom conversion ID to a human-friendly display name. This is useful for translating the response from the ad insights endpoint, which returns conversions labelled like offsite_conversion.custom.123456789 or offsite_conversion.fb_pixel_custom.123456789.
Interactive examples:

/v13.0/FACEBOOK-PAGE-ID/published_posts

Facebook documentation URL: https://developers.facebook.com/docs/graph-api/reference/page/published_posts
The page published_posts edge retrieves post content, comments on posts, and analytics for the most recent posts for your Facebook page. You can track impressions and reach, reactions, shares, likes, and comments.
The metrics that you can fetch are broken into metrics for Page Posts, Page Post Engagement, Page Post Impressions, Page Post Reactions and Page Video Posts.
Interactive examples:

/v13.0/FACEBOOK-PAGE-ID/ratings

Facebook documentation URL: https://developers.facebook.com/docs/graph-api/reference/page/ratings
The page ratings edge shows user-submitted reviews and ratings on your Facebook page.
Interactive examples:

/v13.0/FACEBOOK-PAGE-ID/insights

Facebook documentation URL: https://developers.facebook.com/docs/graph-api/reference/page/insights
The page insights edge retrieves analytics about the performance of your Facebook page, from high-level impressions to detailed demographic breakdowns of your engaged users.
Unlike most Facebook APIs, it doesn't use the fields parameter. Instead, use the metric parameter to specify the metrics you are interested in.
The metrics that you can fetch are broken into metrics for Page Content, Page CTA Clicks, Page Engagement, Page Impressions, Page Reactions, Page User Demographics, Page Video Views and Page Views.
Interactive examples:

/v13.0/INSTAGRAM-BUSINESS-ACCOUNT-ID/insights

Facebook documentation URL: https://developers.facebook.com/docs/instagram-api/reference/ig-user/insights
To get your Instagram insights for your entire account, you first need to lookup your Instagram business account ID. The examples below show you how to do that.
Interactive examples:

/v13.0/INSTAGRAM-BUSINESS-ACCOUNT_ID/media

Facebook documentation URL: https://developers.facebook.com/docs/instagram-api/reference/ig-user/media
The list of Instagram post insights metrics is on a separate page.
To get Instagram insights for individual posts, you first need to lookup your Instagram business account ID. The examples below show you how to do that.
Interactive examples:

/debug_token

Facebook documentation URL: https://developers.facebook.com/docs/facebook-login/access-tokens/debugging-and-error-handling
The debug endpoint isn't needed in the usual course of things. However, if you're hitting permissions error, it can be useful on a case-by-case basis to inspect a token. You will learn if the token has expired, and which permissions and pages it grants access to.
Interactive examples:

Interactive Examples

Get the current user’s ID and name

Try this example on the Facebook Graph API Explorer (requires public_profile permission)
curl -H 'Authorization: Bearer EAAUF...' \
  https://graph.facebook.com/v13.0/me?fields=id,name
{
  "id": "10104046205424917",
  "name": "Colin Dellow"
}

List your Facebook pages and page access tokens

Try this example on the Facebook Graph API Explorer (requires pages_show_list permission)
curl -H 'Authorization: Bearer EAUUF...' \
  'https://graph.facebook.com/v13.0/me/accounts?fields=id,access_token,name&limit=100'
{
  "data": [
    {
      "id": "86717889990",
      "access_token": "EAAUFcA...B8fL",
      "name": "Snapsort"
    },
    {
      "id": "100271560051134",
      "access_token": "EAAUFcA...QH9u",
      "name": "Geekaphone"
    },
    ...more pages
  ],
  "paging": {
    "cursors": {
      "before": "ODY3MTc4ODk5OTAZD",
      "after": "MTUxMDI3NDA1OTE4NDYwNAZDZD"
    }
  }
}

List your Instagram business account IDs

Try this example on the Facebook Graph API Explorer (requires pages_show_list and instagram_basic permissions)
curl -H 'Authorization: Bearer EAAG...' \
  'https://graph.facebook.com/v13.0/me/accounts?fields=name%2Cid%2Cinstagram_business_account%7Bid%7D&limit=1000'
{
  "data": [
    {
      "name": "51 Moments",
      "id": "1510274059184604",
      "instagram_business_account": {
        "id": 158955023470
      }
    }
  ],
  "paging": {
    "cursors": {
      "before": "ODY3MTc4ODk5OTAZD",
      "after": "MTUxMDI3NDA1OTE4NDYwNAZDZD"
    }
  }
}
Try this example on the Facebook Graph API Explorer (requires instagram_basic, instagram_manage_insights and pages_show_list permissions)
curl -H 'Authorization: Bearer EAAG...'  "https://graph.facebook.com/v13.0/INSTAGRAM-ACCOUNT-ID/insights?metric=impressions,reach&period=day"
{
  "data": [
    {
      "name": "impressions",
      "period": "day",
      "values": [
        {
          "value": 228,
          "end_time": "2022-03-27T07:00:00+0000"
        },
        {
          "value": 1410,
          "end_time": "2022-03-28T07:00:00+0000"
        }
      ],
      "title": "Impressions",
      "description": "The total number of times that the business account's media objects have been viewed.",
      "id": "15841208254979231/insights/impressions/day"
    },
    {
      "name": "reach",
      "period": "day",
      "values": [
        {
          "value": 187,
          "end_time": "2022-03-27T07:00:00+0000"
        },
        {
          "value": 1150,
          "end_time": "2022-03-28T07:00:00+0000"
        }
      ],
      "title": "Reach",
      "description": "The total number of times that the business account's media objects have been uniquely viewed.",
      "id": "15841208254979231/insights/reach/day"
    }
  ],
  "paging": {
    "previous": "https://graph.facebook.com/v13.0/15841208254979231/insights?metric=impressions%2Creach&period=day&since=1648178757&until=1648351557",
    "next": "https://graph.facebook.com/v13.0/15841208254979231/insights?metric=impressions%2Creach&period=day&since=1648524359&until=1648697159"
  }
}

Get Instagram post analytics

Try this example on the Facebook Graph API Explorer (requires instagram_basic, instagram_manage_insights and pages_show_list permissions)
curl -H 'Authorization: Bearer EAAG...' \
  "https://graph.facebook.com/v13.0/YOUR-INSTAGRAM-ACCOUNT-ID/media?fields=id%2Cpermalink%2Ccomments_count%2Clike_count%2Cinsights.metric(impressions)&limit=1000"
{
  "data": [
    {
      "id": "15841208254979231",
      "permalink": "https://www.instagram.com/p/CbfOCN1rU8h/",
      "comments_count": 3,
      "like_count": 8,
      "insights": {
        "data": [
          {
            "name": "impressions",
            "period": "lifetime",
            "values": [
              {
                "value": 185
              }
            ],
            "title": "Impressions",
            "description": "Total number of times the media object has been seen",
            "id": "15841208254979231/insights/impressions/lifetime"
          }
        ]
      }
    }
  ],
  "paging": {
    "cursors": {
      "before": "QVFIUlpXVTlnek9XWTcwNlBnNzlUZAlVjVEh2NUdoNEJKRUxjempKa3BPQzUxWFNjYjhnbFZAQZAEVYbXBPQTZAQaG9EZA2tDa2l0NDdMckxPbHF2TVk2bEpFWEFB",
      "after": "QVFIUmhhUVIyZA0kyanZAlSmtmRDdpbzFvQjBLcG1qc2NWLWlBZAUY3Rm5CVEszVTRXaWo0d29MYzZAydGJWWFcxV1lhbEc2S1FpWllyVVFnNU4zUzQ4X0lSWkR3"
    },
    "next": "https://graph.facebook.com/v13.0/15841208254979231/media?fields=id%2Cpermalink%2Ccomments_count%2Clike_count%2Cinsights.metric%28impressions%29&limit=10&after=QVFIUmhhUVIyZA0kyanZAlSmtmRDdpbzFvQjBLcG1qc2NWLWlBZAUY3Rm5CVEszVTRXaWo0d29MYzZAydGJWWFcxV1lhbEc2S1FpWllyVVFnNU4zUzQ4X0lSWkR3"
  }
}

List your ad accounts

Try this example on the Facebook Graph API Explorer (requires ads_read permission)
Note: The Facebook ads API reports all dates in the ad account's timezone. It can be useful to fetch the timezone so that you know exactly which period is being reported.
curl -H 'Authorization: Bearer EAAUF...' \
  'https://graph.facebook.com/v13.0/me/adaccounts?fields=name%2Cid%2Ctimezone_name&limit=1000'
{
  "data": [
    {
      "name": "Colin Dellow",
      "id": "act_10100283992370037",
      "timezone_name": "America/Los_Angeles"
    },
    {
      "name": "Spool and Spindle",
      "id": "act_1413799628646329",
      "timezone_name": "America/Toronto"
    }
  ],
  "paging": {
    "cursors": {
      "before": "NjAwNDAwNjI5MzU4NwZDZD",
      "after": "NjA1NDAyOTczOTU0MAZDZD"
    }
  }
}

List your ad account's ad creatives

Try this example on the Facebook Graph API Explorer (needs ads_management permission)
curl -H 'Authorization: Bearer EAAU...' \
  'https://graph.facebook.com/v13.0/act_1413799628646329/ads?fields=id%2Cname%2Ccreative%7Bid%2Cname%2Cstatus%2Cobject_story_id%2Cobject_story_spec%7D&limit=1000'
{
  "data": [
    {
      "id": "6280207447540",
      "name": "January 2022",
      "creative": {
        "id": "6284054873740",
        "name": "{{product.name}} 2022-02-11-fe6a244b3741dc161421c91628d3033f",
        "status": "ACTIVE",
        "object_story_spec": {
          "page_id": "306918196055033",
          "instagram_actor_id": "997833046972628"
        }
      }
    },
    {
      "id": "6279074508940",
      "name": "Fabric sale 2",
      "creative": {
        "id": "6279074596540",
        "name": "A new sale EVERY DAY! 2021-12-20-048be516a999d6a106f15c957a559ac4",
        "status": "ACTIVE",
        "object_story_spec": {
          "page_id": "306918196055033",
          "instagram_actor_id": "997833046972628",
          "link_data": {
            "link": "http://www.spoolandspindle.ca/",
            "message": "SALE on FABRIC!",
            "name": "A new sale EVERY DAY!",
            "attachment_style": "link",
            "description": "visit us daily to discover today's discount. ",
            "image_hash": "217e68dddcd56081496b5623a6c39838",
            "call_to_action": {
              "type": "LEARN_MORE"
            }
          }
        }
      }
    },
    {
      "id": "6275719001340",
      "name": "Black Friday",
      "creative": {
        "id": "6275719684940",
        "name": "30% off SALE ON FABRIC! 2021-11-19-f93bacfbeacfeb4788c86718fb0d133f",
        "status": "ACTIVE",
        "object_story_spec": {
          "page_id": "306918196055033",
          "instagram_actor_id": "997833046972628",
          "video_data": {
            "video_id": "203216328537392",
            "title": "30% off SALE ON FABRIC!",
            "message": "It's time! Get 30% off almost everything in our shop with the code BIG30.",
            "link_description": "Limited time offer, in-stock items only, excludes Gift Cards, Remnants, Printing, Bundles, and Custom Kits.",
            "call_to_action": {
              "type": "SHOP_NOW",
              "value": {
                "link": "http://www.spoolandspindle.ca/"
              }
            },
            "image_url": "https://www.facebook.com/ads/image/?d=AQJEUW0vZVz1xjwN48eCdMnQmtkvsidurePQpqNjo_u5hauRMMxXAKzklvzec8gJApicf4PeBGumBk7oyZEGFfRlJXtYeWNbZbCpB3uCxMj-cquRPLFa-M3FD37qkr2lEtzmIEJVtn_egdcCy-8e4Iax",
            "image_hash": "3a9dbef44fdad7d014b1a244c612b5b7"
          }
        }
      }
    }
  ],
  "paging": {
    "cursors": {
      "before": "QVFIUjllNEZAEQi1qZAHZAvWVo4dFFwVUJBd0xTblYxdG9vTGVBT3c3QUM0M2FLZAExnLW5RUnR6ek8tb3dydFJHQ3RtRHdUbUtTcmxQbXoyeFJ0YUNZAN0xvdGtn",
      "after": "QVFIUnJlMjRCYlJ4azVTb2pUUHU4RXlJWGtzUVRCM2ttOUotSXF2UmVBcGExbDJxSmFURHZAVT0ZApWFp4ZAHplQVRHbkFIYlIwZAC1HX0lkNHQwYWcwR2lOeVhR"
    }
  }
}

List your active Facebook ad campaigns

Try this example on the Facebook Graph API Explorer (needs ads_management permission)
curl -H 'Authorization: Bearer EAUUF...' \
  'https://graph.facebook.com/v13.0/act_YOUR-AD-ACCOUNT-ID/campaigns?fields=created_time%2Cstart_time%2Cstop_time%2Cid%2Cname%2Cobjective%2Cadlabels%2Cbid_strategy%2Cbudget_remaining%2Cdaily_budget%2Clifetime_budget%2Cspend_cap%2Cbuying_type%2Cconfigured_status%2Ceffective_status%2Cstatus&limit=1000&filtering=%5B%7B%22field%22%3A%22effective_status%22%2C%22operator%22%3A%22IN%22%2C%22value%22%3A%5B%22ACTIVE%22%5D%7D%5D'
{
  "data": [
    {
      "created_time": "2022-01-03T13:09:57-0500",
      "start_time": "2022-01-03T13:09:58-0500",
      "id": "6280207445540",
      "name": "January 2022",
      "objective": "CONVERSIONS",
      "budget_remaining": "0",
      "buying_type": "AUCTION",
      "configured_status": "ACTIVE",
      "effective_status": "ACTIVE",
      "status": "ACTIVE"
    },
    {
      "created_time": "2021-11-30T12:15:50-0500",
      "start_time": "2021-11-30T12:15:50-0500",
      "stop_time": "2021-12-20T00:00:00-0500",
      "id": "6277005337740",
      "name": "holiday campaign",
      "objective": "CONVERSIONS",
      "bid_strategy": "LOWEST_COST_WITHOUT_CAP",
      "budget_remaining": "800",
      "daily_budget": "800",
      "buying_type": "AUCTION",
      "configured_status": "ACTIVE",
      "effective_status": "ACTIVE",
      "status": "ACTIVE"
    }
  ],
  "paging": {
    "cursors": {
      "before": "QVFIUksxMlIyQ3ZAkTmhDZA0ZAiV21VcmlabVkyaU5hRTJmSGM1RkVCb1JFSXI0cms0Y2FIMXhBWGV6MHRNczBJQXFVMi1VaHZAsUlFXdEVidnBJejI2STlFaUpR",
      "after": "QVFIUnE0aXA3RFVPS0NtcG8xY2pnUUlWUDFTZAzBjR05yNm5ZAMFNzNEVCdEVuTmcyeWx6UnFzVU5TYjVGUm5RWEJFVkhNNjRjY2VRRThIeHViWHlENmRrUWtR"
    }
  }
}

Get monthly spend by campaign for last quarter

Try this example on the Facebook Graph API Explorer (needs ads_management permission)
curl -H 'Authorization: Bearer EAAUF...' \
  'https://graph.facebook.com/v13.0/act_YOUR-AD-ACCOUNT-ID/insights?level=campaign&time_increment=monthly&date_preset=last_quarter&fields=campaign_name%2Cspend%2Creach%2Cimpressions%2Cclicks&limit=1000'
{
  "data": [
    {
      "campaign_name": "Conversions Ad",
      "spend": "188.03",
      "reach": "12222",
      "impressions": "36897",
      "clicks": "473",
      "date_start": "2021-10-01",
      "date_stop": "2021-10-31"
    },
    {
      "campaign_name": "Conversions Ad",
      "spend": "319.25",
      "reach": "15147",
      "impressions": "53539",
      "clicks": "611",
      "date_start": "2021-11-01",
      "date_stop": "2021-11-30"
    },
    {
      "campaign_name": "Fabric SALE",
      "spend": "291",
      "reach": "11696",
      "impressions": "49290",
      "clicks": "1164",
      "date_start": "2021-12-01",
      "date_stop": "2021-12-31"
    }
  ],
  "paging": {
    "cursors": {
      "before": "MAZDZD",
      "after": "OQZDZD"
    }
  }
}

List lead generation forms for a page

Try this example on the Facebook Graph API Explorer (needs a page access token with pages_manage_ads permission)
curl 'https://graph.facebook.com/v13.0/YOUR-FACEBOOK-PAGE-ID/leadgen_forms?access_token=PAGE_ACCESS_TOKEN'
{
  "data": [
    {
      "id": "5265075003587177",
      "locale": "en_US",
      "name": "SEO Tune-up Lead",
      "status": "ACTIVE"
    }
  ],
  "paging": {
    "cursors": {
      "before": "QVFIUk1yd1VhdkhaWnRUNmpJbV94NWxZAa2M0MjVFc1BRRDN2bTloSFJ0YkVQMlZACLVVpcExsN25IbWh4cDRELU94dm8tR3F5X3k1NXJDTk1jaHRVNkZAjeV9R",
      "after": "QVFIUk1yd1VhdkhaWnRUNmpJbV94NWxZAa2M0MjVFc1BRRDN2bTloSFJ0YkVQMlZACLVVpcExsN25IbWh4cDRELU94dm8tR3F5X3k1NXJDTk1jaHRVNkZAjeV9R"
    }
  }
}

List leads from a lead generation form

Try this example on the Facebook Graph API Explorer (needs leads_retrieval permission)
curl -H 'Authorization: Bearer EAAUFc...' \
  'https://graph.facebook.com/v13.0/YOUR-LEAD-FORM-ID?fields=id%2Cname%2Cleads&limit=1000'
{
  "id": "5265075003587177",
  "name": "SEO Tune-Up Form",
  "leads": {
    "data": [
      {
        "created_time": "2022-03-25T15:52:19+0000",
        "id": "375306397774453",
        "field_data": [
          {
            "name": "FULL_NAME",
            "values": [
              "Stuart D'amato"
            ]
          },
          {
            "name": "EMAIL",
            "values": [
              "stuart@example.com"
            ]
          }
        ]
      }
    ],
    "paging": {
      "cursors": {
        "before": "QVFIUmhKTG5hVVNTOVk3eXUyazhvaVE2azY1dlA1Vm9qaDJiOG5vcWh0Ri1TYll1dEdMZAWswWTVXbnBwdWlHaGYtLW1yNXhyOUt6V2ZAXT2s5ZAVJkSXVYSDFR",
        "after": "QVFIUmhKTG5hVVNTOVk3eXUyazhvaVE2azY1dlA1Vm9qaDJiOG5vcWh0Ri1TYll1dEdMZAWswWTVXbnBwdWlHaGYtLW1yNXhyOUt6V2ZAXT2s5ZAVJkSXVYSDFR"
      }
    }
  }
}

See your Facebook page's ratings

Try this example on the Facebook Graph API Explorer (needs pages_read_user_content permission)
curl 'https://graph.facebook.com/v13.0/YOUR-PAGE-ID/ratings?fields=created_time%2Crecommendation_type%2Creview_text&limit=1000&access_token=EAAG..'
{
  "data": [
    {
      "created_time": "2021-05-13T03:29:39+0000",
      "recommendation_type": "positive",
      "review_text": "It's great!"
    },
    {
      "created_time": "2021-05-13T03:30:58+0000",
      "recommendation_type": "negative",
      "review_text": "It's terrible!"
    }
  ]
}

List custom conversions for all ad accounts

Try this example on the Facebook Graph API Explorer (needs ads_management permission)
This example uses field expansion. Even though we're querying a list of ad accounts, we can use field expansion to make a nested query for custom conversions that belong to each ad account. This is convenient for a quick overview, but more difficult if you need to paginate the nested custom conversion objects.
curl -H 'Authorization: Bearer …'  \
  'https://graph.facebook.com/v13.0/me/adaccounts?fields=id%2Cname%2Ccustomconversions%7Bcustom_event_type%2Cevent_source_type%2Cpixel%7Bname%7D%2Crule%7D&limit=1000'
{
  "data": [
    {
      "id": "act_10100283992370037",
      "name": "Colin Dellow",
      "customconversions": {
        "data": [
          {
            "custom_event_type": "OTHER",
            "event_source_type": "pixel",
            "pixel": {
              "name": "Code 402 Pixel",
              "id": "556718854866543"
            },
            "rule": "{\"and\":[{\"event\":{\"eq\":\"PageView\"}},{\"or\":[{\"URL\":{\"i_contains\":\"contact-us\"}}]}]}",
            "id": "654826322474528"
          }
        ],
        "paging": {
          "cursors": {
            "before": "QVFIUmZAWekZAvbnlFUVctbHRJdl9PeU81ZAHNnbkV4TW5DY0hVRnJ0amhUV1hSRjlUZAlNNNjI4aWpaU29JeGNQVWR2MDdtRUZAHTXNucE81MzJLR2xlWDRwamVB",
            "after": "QVFIUmZAWekZAvbnlFUVctbHRJdl9PeU81ZAHNnbkV4TW5DY0hVRnJ0amhUV1hSRjlUZAlNNNjI4aWpaU29JeGNQVWR2MDdtRUZAHTXNucE81MzJLR2xlWDRwamVB"
          }
        }
      }
    },
    {
      "id": "act_1413799628646329",
      "name": "Spool and Spindle"
    }
  ],
  "paging": {
    "cursors": {
      "before": "NjAwNDAwNjI5MzU4NwZDZD",
      "after": "NjA1NDAyOTczOTU0MAZDZD"
    }
  }
}
Try this example on the Facebook Graph API Explorer (needs ads_management permission)
curl -H 'Authorization: Bearer ...' \
  'https://graph.facebook.com/v13.0/act_YOUR-AD-ACCOUNT-ID/customconversions?fields=id%2Cname%2Ccustom_event_type%2Cevent_source_type%2Cpixel%7Bname%7D%2Crule&limit=1000'
{
  "data": [
    {
      "id": "654826322474528",
      "name": "Submitted Contact Form",
      "custom_event_type": "OTHER",
      "event_source_type": "pixel",
      "pixel": {
        "name": "Code 402 Pixel",
        "id": "556718854866543"
      },
      "rule": "{\"and\":[{\"event\":{\"eq\":\"PageView\"}},{\"or\":[{\"URL\":{\"i_contains\":\"contact-us\"}}]}]}"
    }
  ],
  "paging": {
    "cursors": {
      "before": "QVFIUmZAWekZAvbnlFUVctbHRJdl9PeU81ZAHNnbkV4TW5DY0hVRnJ0amhUV1hSRjlUZAlNNNjI4aWpaU29JeGNQVWR2MDdtRUZAHTXNucE81MzJLR2xlWDRwamVB",
      "after": "QVFIUmZAWekZAvbnlFUVctbHRJdl9PeU81ZAHNnbkV4TW5DY0hVRnJ0amhUV1hSRjlUZAlNNNjI4aWpaU29JeGNQVWR2MDdtRUZAHTXNucE81MzJLR2xlWDRwamVB"
    }
  }
}

Get analytics on your Facebook page's reach

Try this example on the Facebook Graph API Explorer (needs read_insights permission)
curl 'https://graph.facebook.com/v13.0/FACEBOOK-PAGE-ID/insights?date_preset=yesterday&metric=page_fans%2Cpage_impressions%2Cpage_engaged_users&access_token=EAAG...'
{
  "data": [
    {
      "name": "page_fans",
      "period": "day",
      "values": [
        {
          "value": 65790,
          "end_time": "2022-03-28T07:00:00+0000"
        }
      ],
      "title": "Lifetime Total Likes",
      "description": "Lifetime: The total number of people who have liked your Page. (Unique Users)",
      "id": "86717889990/insights/page_fans/day"
    },
    {
      "name": "page_impressions",
      "period": "day",
      "values": [
        {
          "value": 8,
          "end_time": "2022-03-28T07:00:00+0000"
        }
      ],
      "title": "Daily Total Impressions",
      "description": "Daily: The number of times any content from your Page or about your Page entered a person's screen. This includes posts, stories, ads, as well other content or information on your Page. (Total Count)",
      "id": "86717889990/insights/page_impressions/day"
    },
    {
      "name": "page_engaged_users",
      "period": "day",
      "values": [
        {
          "value": 0,
          "end_time": "2022-03-28T07:00:00+0000"
        }
      ],
      "title": "Daily Page Engaged Users",
      "description": "Daily: The number of people who engaged with your Page. Engagement includes any click or story created. (Unique Users)",
      "id": "86717889990/insights/page_engaged_users/day"
    },
    {
      "name": "page_impressions",
      "period": "week",
      "values": [
        {
          "value": 49,
          "end_time": "2022-03-28T07:00:00+0000"
        }
      ],
      "title": "Weekly Total Impressions",
      "description": "Weekly: The number of times any content from your Page or about your Page entered a person's screen. This includes posts, stories, ads, as well other content or information on your Page. (Total Count)",
      "id": "86717889990/insights/page_impressions/week"
    },
    {
      "name": "page_engaged_users",
      "period": "week",
      "values": [
        {
          "value": 7,
          "end_time": "2022-03-28T07:00:00+0000"
        }
      ],
      "title": "Weekly Page Engaged Users",
      "description": "Weekly: The number of people who engaged with your Page. Engagement includes any click or story created. (Unique Users)",
      "id": "86717889990/insights/page_engaged_users/week"
    },
    {
      "name": "page_impressions",
      "period": "days_28",
      "values": [
        {
          "value": 285,
          "end_time": "2022-03-28T07:00:00+0000"
        }
      ],
      "title": "28 Days Total Impressions",
      "description": "28 Days: The number of times any content from your Page or about your Page entered a person's screen. This includes posts, stories, ads, as well other content or information on your Page. (Total Count)",
      "id": "86717889990/insights/page_impressions/days_28"
    },
    {
      "name": "page_engaged_users",
      "period": "days_28",
      "values": [
        {
          "value": 49,
          "end_time": "2022-03-28T07:00:00+0000"
        }
      ],
      "title": "28 Days Page Engaged Users",
      "description": "28 Days: The number of people who engaged with your Page. Engagement includes any click or story created. (Unique Users)",
      "id": "86717889990/insights/page_engaged_users/days_28"
    }
  ],
  "paging": {
    "previous": "https://graph.facebook.com/v13.0/86717889990/insights?access_token=EAAGi...&pretty=0&metric=page_fans%2Cpage_impressions%2Cpage_engaged_users&date_preset=yesterday&since=1648278000&until=1648364400",
    "next": "https://graph.facebook.com/v13.0/86717889990/insights?access_token=EAAG...&pretty=0&metric=page_fans%2Cpage_impressions%2Cpage_engaged_users&date_preset=yesterday&since=1648450800&until=1648537200"
  }
}

Get your Facebook page's user demographics, including gender, age and country

Try this example on the Facebook Graph API Explorer (needs read_insights permission)
curl 'https://graph.facebook.com/v13.0/FACEBOOK-PAGE-ID/insights?metric=page_fans_country%2Cpage_fans_gender_age&access_token=EAAG...'
{
  "data": [
    {
      "name": "page_fans_country",
      "period": "day",
      "values": [
        {
          "value": {
            "DE": 919,
            "BD": 1545,
            "BE": 253,
            "TW": 370,
            "PT": 877,
            "BG": 277,
            "NZ": 252,
            "FR": 483,
            "HU": 321,
            "SA": 696,
            "BR": 2255,
            "SE": 284,
            "SG": 762,
            "GB": 2107,
            "ID": 2837,
            "IE": 251,
            "CA": 1890,
            "US": 9540,
            "MM": 318,
            "EG": 3473,
            "IL": 278,
            "AE": 736,
            "IN": 7079,
            "ZA": 297,
            "IQ": 385,
            "IR": 363,
            "CL": 466,
            "GR": 507,
            "MX": 815,
            "IT": 1233,
            "CO": 383,
            "MY": 3493,
            "ES": 735,
            "AR": 740,
            "AU": 1399,
            "TH": 1668,
            "PE": 321,
            "VN": 619,
            "PH": 2306,
            "PK": 1517,
            "PL": 369,
            "RO": 856,
            "NL": 449,
            "TR": 647,
            "LK": 635
          },
          "end_time": "2022-03-25T07:00:00+0000"
        },
        {
          "value": {
            "DE": 919,
            "BD": 1545,
            "BE": 252,
            "TW": 369,
            "PT": 877,
            "BG": 276,
            "NZ": 252,
            "FR": 483,
            "HU": 321,
            "SA": 696,
            "BR": 2256,
            "SE": 285,
            "SG": 763,
            "GB": 2109,
            "ID": 2838,
            "IE": 252,
            "CA": 1891,
            "US": 9541,
            "MM": 318,
            "EG": 3473,
            "IL": 278,
            "AE": 738,
            "IN": 7077,
            "ZA": 297,
            "IQ": 385,
            "IR": 363,
            "CL": 465,
            "GR": 508,
            "MX": 813,
            "IT": 1233,
            "CO": 383,
            "MY": 3494,
            "ES": 735,
            "AR": 740,
            "AU": 1399,
            "TH": 1669,
            "PE": 321,
            "VN": 619,
            "PH": 2304,
            "PK": 1515,
            "PL": 369,
            "RO": 855,
            "NL": 447,
            "TR": 646,
            "LK": 635
          },
          "end_time": "2022-03-26T07:00:00+0000"
        }
      ],
      "title": "Lifetime Likes by Country",
      "description": "Lifetime: Aggregated Facebook location data, sorted by country (top 50), about the people who like your Page. (Unique Users)",
      "id": "86717889990/insights/page_fans_country/day"
    },
    {
      "name": "page_fans_gender_age",
      "period": "day",
      "values": [
        {
          "value": {
            "U.55-64": 57,
            "M.55-64": 2680,
            "U.35-44": 224,
            "F.45-54": 1997,
            "M.18-24": 2065,
            "M.35-44": 16140,
            "F.25-34": 5037,
            "U.65+": 51,
            "U.18-24": 7,
            "M.25-34": 22211,
            "U.45-54": 98,
            "F.65+": 902,
            "F.55-64": 1233,
            "M.13-17": 20,
            "M.65+": 2053,
            "F.35-44": 4160,
            "U.25-34": 121,
            "M.45-54": 6297,
            "F.18-24": 443
          },
          "end_time": "2022-03-25T07:00:00+0000"
        },
        {
          "value": {
            "U.55-64": 57,
            "M.55-64": 2682,
            "U.35-44": 224,
            "F.45-54": 1998,
            "M.18-24": 2059,
            "M.35-44": 16148,
            "F.25-34": 5039,
            "U.65+": 51,
            "U.18-24": 7,
            "M.25-34": 22196,
            "U.45-54": 98,
            "F.65+": 903,
            "F.55-64": 1232,
            "M.13-17": 20,
            "M.65+": 2053,
            "F.35-44": 4159,
            "U.25-34": 121,
            "M.45-54": 6304,
            "F.18-24": 441
          },
          "end_time": "2022-03-26T07:00:00+0000"
        }
      ],
      "title": "Lifetime Likes by Gender and Age",
      "description": "Lifetime: Aggregated demographic data about the people who like your Page based on the age and gender information they provide in their user profiles. (Unique Users)",
      "id": "86717889990/insights/page_fans_gender_age/day"
    }
  ],
  "paging": {
    "previous": "https://graph.facebook.com/v13.0/86717889990/insights?access_token=EAAG...&pretty=0&metric=page_fans_country%2Cpage_fans_gender_age&since=1647932400&until=1648105200",
    "next": "https://graph.facebook.com/v13.0/86717889990/insights?access_token=EAAG...&pretty=0&metric=page_fans_country%2Cpage_fans_gender_age&since=1648278000&until=1648450800"
  }
}

Get analytics on your Facebook page's posts

Try this example on the Facebook Graph API Explorer (needs pages_read_engagement and read_insights permissions)
Both the request and response for this example are a bit gnarly.
  • The request uses a nested field expression to get summary data for likes, comments and shares, for example: likes.limit(0).summary(true)
  • The request also uses field expansions to get insights data: insights.metric(metric1,metric2)
  • The response data is inconvenient to parse out, as it's presented as a series of nested arrays of nested objects
curl  'https://graph.facebook.com/v13.0/YOUR-PAGE-ID/published_posts?fields=id%2Cmessage%2Cinsights.metric(post_impressions%2Cpost_impressions_unique)%2Clikes.limit(0).summary(true)%2Ccomments.limit(0).summary(true)%2Cshares.limit(0).summary(true)&limit=100&access_token=EAAGi...'
{
  "data": [
    {
      "id": "86717889990_10150730856914991",
      "message": "How to Choose the Best Camera for Your Individual Needs as a Photographer",
      "insights": {
        "data": [
          {
            "name": "post_impressions",
            "period": "lifetime",
            "values": [
              {
                "value": 437
              }
            ],
            "title": "Lifetime Post Total Impressions",
            "description": "Lifetime: The number of times your Page's post entered a person's screen. Posts include statuses, photos, links, videos and more. (Total Count)",
            "id": "86717889990_10150730856914991/insights/post_impressions/lifetime"
          },
          {
            "name": "post_impressions_unique",
            "period": "lifetime",
            "values": [
              {
                "value": 414
              }
            ],
            "title": "Lifetime Post Total Reach",
            "description": "Lifetime: The number of people who had your Page's post enter their screen. Posts include statuses, photos, links, videos and more. (Unique Users)",
            "id": "86717889990_10150730856914991/insights/post_impressions_unique/lifetime"
          }
        ],
        "paging": {
          "previous": "https://graph.facebook.com/v13.0/86717889990_10150730856914991/insights?access_token=EAAG...&pretty=0&metric=post_impressions%2Cpost_impressions_unique&since=1647846000&until=1648018800",
          "next": "https://graph.facebook.com/v13.0/86717889990_10150730856914991/insights?access_token=EAAG...&pretty=0&metric=post_impressions%2Cpost_impressions_unique&since=1648191600&until=1648364400"
        }
      },
      "likes": {
        "data": [
        ],
        "summary": {
          "total_count": 56,
          "can_like": true,
          "has_liked": false
        }
      },
      "comments": {
        "data": [
        ],
        "summary": {
          "order": "ranked",
          "total_count": 11,
          "can_comment": true
        }
      },
      "shares": {
        "count": 4
      }
    }
  ],
  "paging": {
    "cursors": {
      "before": "QVFIUk5xb3dlTDhOUm1FTWhCUEt...",
      "after": "QVFIUlljbnR4dkEyUnBOYW1x..."
    },
    "next": "https://graph.facebook.com/v13.0/86717889990/published_posts?access_token=EAAGi0As5Jk..."
  }
}

Get Facebook post content and comments

Try this example on the Facebook Graph API Explorer (needs pages_read_engagement permission)
This request fetches two exclusive sets of data:
  • the message field, for when the Facebook post is a standalone post
  • the attachments{title,description,media} fields for when the Facebook post links to an external website
curl 'https://graph.facebook.com/v13.0/YOUR-FACEBOOK-PAGE-ID/published_posts?fields=id%2Cmessage%2Cattachments%7Btitle%2Cdescription%2Cmedia%7D%2Ccomments&limit=100&access_token=EAAG…'
{
  "data": [
    {
      "id": "224916144219268_1419692391408298",
      "attachments": {
        "data": [
          {
            "title": "Ugly, Beautiful And Strange Concept Cars",
            "description": "The 1980 and 1990's were an interesting time in the automotive industry. Car manufacturer created a full slate of beautiful and sometimes crazy concept cars.",
            "media": {
              "image": {
                "height": 538,
                "src": "https://external.fybz1-1.fna.fbcdn.net/safe_image.php?d=AQHsjuwxey6NX1f5&w=538&h=538&url=https%3A%2F%2Fwww.facebook.com%2Fads%2Fimage%2F%3Fd%3DAQLPalegBAGBB7CdDIseFQadr-mBqZE_Ec_0PezAAU5YlfAU-J9bzVEMyCkFwOZ9DSZFvG9dDFDW15qXrW_XjL6uuZkT_Ew_3bPRYk9C2NGWQkD3q0IJWfAWJ-uaPAhvqEwtWVrJX0rGUMupZvN6IDEu&cfs=1&ext=emg0&_nc_oe=6fcf8&_nc_sid=06c271&ccb=3-5&_nc_hash=AQFSLKLJKsQ1OnEq",
                "width": 538
              }
            }
          }
        ]
      },
      "comments": {
        "data": [
          {
            "created_time": "2017-03-29T21:57:12+0000",
            "message": "Zeb Odom",
            "id": "1419692391408298_1432604850117052"
          }
        ]
      }
    },
    {
      "id": "224916144219268_1389474574430080",
      "message": "What is your ultimate off-road machine?",
      "attachments": {
        "data": [
          {
            "title": "Extreme Off-Road Vehicles You Won't Believe Exist - Carsort",
            "description": "There are hundreds of different vehicles that claim to be able to take you anywhere. We have compiled a list of the most interesting off road vehicles on earth.",
            "media": {
              "image": {
                "height": 630,
                "src": "https://external.fybz1-1.fna.fbcdn.net/safe_image.php?d=AQGAYgrE48_NY99e&w=630&h=630&url=https%3A%2F%2Fwww.facebook.com%2Fads%2Fimage%2F%3Fd%3DAQKVvr11oqZaYPu0xh5ttb-heVmMIV1YbEP6ckJpkJlI3i0Xmp8VxLdF1vTnZQrIJAbM9N89xzSoNErxb7tkufqxHk_OS6PLc5k5bXWVaQHxSl6lBSIqHpfq6vI0kZyV_4dzykgelQxZuva36xkqHfyw&cfs=1&ext=emg0&_nc_oe=6fcf8&_nc_sid=06c271&ccb=3-5&_nc_hash=AQEwtNuwFfYN-Xs-",
                "width": 630
              }
            }
          }
        ]
      },
      "comments": {
        "data": [
          {
            "created_time": "2017-03-12T13:07:17+0000",
            "message": "That was tried back in the 40's or 50's with a Ford tractor. The results were somewhat less than overwhelming then. it's the same as rolling up the rim , rolling it back up, rolling it back down when you get the message play again.",
            "id": "1389474574430080_1414258155285055"
          },
          {
            "created_time": "2017-03-12T13:20:07+0000",
            "message": "",
            "id": "1389474574430080_1414266341950903"
          }
        ]
      }
    }
  ],
  "paging": {
    "cursors": {
      "before": "QVFIUnlOOWFzLVY5eXlCaGEydWp2aW5seGQ3NjB6clRFaENTd0I1eXB5b3laYWFsajQtUkRVWk9OWkRucDA2TkRKaXJTM09CZAUVFTkx0VndhV2tBTjdkcVAtLXp5Q3dsUXBGamRJeVhrY0pxZAHdBeHJpNmZAFRDFlaVhGTEpzMm44SjNt",
      "after": "QVFIUnV1aENCTGp3VUJUQ0FBS05kOUdHUUxMNUV1SWNFUXo4MzRFcFk2TTB0eDFFTllVSXV4dVBVN0xncXNUcXd1aHZAtb2F6VURScTh5amxRVmR2OFhiS05HSUdrOVRkSHRDVDRHTnlHdDl2NjdJcGZAYQWN5SmpnZAFctYzRickc2ZAkRh"
    }
  }
}

List the permissions of a Facebook user access token

Try this example on the Facebook Graph API Explorer
curl -H 'Authorization: Bearer ...' \
  'https://graph.facebook.com/v13.0/me/permissions'
{
  "data": [
    {
      "permission": "pages_show_list",
      "status": "granted"
    },
    {
      "permission": "public_profile",
      "status": "granted"
    },
    {
      "permission": "ads_read",
      "status": "declined"
    }
  ]
}

Inspect a Facebook access token

Try this example on the Facebook Graph API Explorer
To inspect a Facebook access token, you need:
  • the token to be inspected (can be expired/invalid)
  • a valid token issued from the same app
Often, you can use the same token for both parameters.
curl -H 'Authorization: Bearer EAAUF...' \
  'https://graph.facebook.com/v13.0/debug_token?input_token=EAAUF...'
{
  "data": {
    "app_id": "1413353502449115",
    "type": "USER",
    "application": "Test App 1",
    "data_access_expires_at": 1655997930,
    "expires_at": 1648227600,
    "is_valid": true,
    "scopes": [
      "pages_show_list",
      "ads_management",
      "instagram_basic",
      "public_profile"
    ],
    "granular_scopes": [
      {
        "scope": "pages_show_list"
      },
      {
        "scope": "ads_management"
      },
      {
        "scope": "instagram_basic"
      }
    ],
    "user_id": "10104046205424917"
  }
}

Troubleshooting

Error code 1: Please reduce the amount of data you're asking for, then retry your request

You may see an error like:
{
  "error": {
    "code": 1,
    "message": "Please reduce the amount of data you’re asking for, then retry your request"
  }
}
This can happen when using the Facebook ad insights endpoint if your response is expected to be very large.
Solution: In addition to using a smaller time span, or fewer dimensions, you may be successful if you switch to asynchronous requests. Read our section on Synchronous vs Asynchronous Requests for more information.

Error code 10: User has insufficient privileges on the page

You may see an error like:
{
  "error": {
    "message": "(#10) User has insufficient privileges on the page.",
    "type": "OAuthException",
    "code": 10,
    "fbtrace_id": "AQRkuosa8paONx6NwXKXni_"
  }
}
Possible cause: You are accessing an endpoint that returns information about multiple pages (for example, /me/accounts), and using field expansion to drill into a nested field like leadgen_forms. This request will fail if you lack the permissions on even a single one of the pages.
Solution: Directly access the single page's data by querying its Graph object explicitly.
Possible cause: You do not have the appropriate permissions to access a page.
Solution: Ensure that you are the Page Administrator, or that the administrator has delegated you appropriate permissions in the Page Roles section of the page.

Error code 100: Missing permissions

You may see an error like:
{
  "error": {
    "message": "(#100) Missing permissions",
    "type": "OAuthException",
    "code": 100,
    "fbtrace_id": "AWSsw4nFdSmQnI_BrE1y0Fn"
  }
}
Possible cause: Your Facebook user account does not have access to this resource.
Solution: Ask the owner of the page or ad account to grant you access.
Possible cause: Your Facebook user access token does not have the required scope to access this resource. Solution: Get a new user access token, and ensure that you have requested the appropriate permission, for example, ads_read is required to see ads data.

Error code 100: Time range too long

You may see an error like:
{
  "error": {
    "message": "Invalid parameter",
    "type": "OAuthException",
    "code": 100,
    "error_subcode": 1504016,
    "is_transient": false,
    "error_user_title": "Time range too long",
    "error_user_msg": "There cannot be more than 93 days (8035200 s) between since and from.",
    "fbtrace_id": "AgBsr5bE73wcl1udyt59Zxd"
  }
}
The Facebook page insights endpoint does not permit a timespan longer than 3 months (93 days).
Solution: Adjust the values sent in the since and until parameters so that they span fewer than 3 months.

Error code 100: Filter type = only supports numeric value.

You may see an error like:
{
  "error": {
    "message": "(#100) Filter type = only supports numeric value. Value \"LINK_CLICKS\" is given.",
    "type": "OAuthException",
    "code": 100,
    "fbtrace_id": "AlCxR0O6AvJq-IujGPS_v99"
  }
}
The operator that you pass for filtering must match the kind of value being filtered. To test against a string value, use the IN or NOT_IN operator, and pass an array of string values to test against. Read our section on filtering for more information.

Error code 190: Error validating access token: Session has expired

You may see an error like:
{
  "error": {
    "message": "Error validating access token: Session has expired on Thursday, 24-Mar-22 09:00:00 PDT. The current time is Thursday, 24-Mar-22 12:26:11 PDT.",
    "type": "OAuthException",
    "code": 190,
    "error_subcode": 463,
    "fbtrace_id": "Az8vEGYzvOWhZwhKC-vO8aZ"
  }
}
This means that the user access token or page access token you are using is no longer valid. All user tokens expire after 90 days. Additionally, a token may be invalidated by Facebook if the user revokes access to your app, changes their password or logs out.
Solution: Re-authenticate the user to get a new token.

Error code 190: This method must be called with a Page Access Token

You may see an error like:
{
  "error": {
    "message": "(#190) This method must be called with a Page Access Token",
    "type": "OAuthException",
    "code": 190,
    "fbtrace_id": "AGNZbwD3-o3WPNS6iJMtP4k"
  }
}
This means that you have used a user access token or app access token when querying a page-related endpoint, or a page access token from the wrong page.
Solution: Use a user access token to get a long-lived page access token for the specific page. Use the page access token to authenticate this request.

Error code 200: Provide valid app ID

You may see an error like:
{
  "error": {
    "message": "(#200) Provide valid app ID",
    "type": "OAuthException",
    "code": 200,
    "fbtrace_id":"A0YwvZxVZeXHso6jkteMG5L"
  }
}
This means that you did not provide a user access token, page access token or app token in your request.
Solution: Depending on which kind of object you are querying, double-check that you have included the correct kind of access token. Read our section on how to get a user access token, how to get a page access token, or how to get an app access token for more information.

Error code 200: Requires ads_management permission to manage the object

You may see an error like:
{
  "error": {
    "message": "(#200) Requires ads_management permission to manage the object",
    "type": "OAuthException",
    "code": 200,
    "fbtrace_id": "A1ZhP2NEH_HESKsgePQxyaX"
  }
}
This means that you did not provide a user access token that had the ads_management permission.
Solution: Ensure that your OAuth authorization request uses the ads_management scope, and that the user did not decline this scope in the consent dialog.

Error code 210: A page access token is required to request this resource

You may see an error like:
{
  "error": {
    "message": "(#210) A page access token is required to request this resource.",
    "type": "OAuthException",
    "code": 210,
    "fbtrace_id": "AFzK35Wl9eNpo1zM9yybZz_"
  }
}
Solution: Authenticate your request with a page access token for the specific page.

Error code 270: This Ads API request is not allowed for apps with development access level

You may see an error like:
{
  "error": {
    "message": "(#270) This Ads API request is not allowed for apps with development access level (Development access is by default for all apps, please request for upgrade). Make sure that the access token belongs to a user that is both admin of the app and admin of the ad account",
    "type":"OAuthException",
    "code":270,
    "fbtrace_id":"A8jYciqKPVlFd3TVoxqSqaZ"
  }
}
This means that you are using an app that has not gone through app review for the given permission.
Solution: Restrict your API requests to only things owned by the creator of the app, or follow the app review process. Read our section on the app review process for more information.

Error code 2500: An active access token must be used to query information bout the current user.

You may see an error like:
{
  "error": {
    "message": "An active access token must be used to query information about the current user.",
    "type": "OAuthException",
    "code": 2500,
    "fbtrace_id": "Ar01Yj5zYue0C-fgp7lK0h3"
  }
}
Solution: Your request did not include a user access token. Be sure to include the user access token in the Authorization header of your request.

Error code 2635: You are calling a deprecated version of the Ads API.

You may see an error like:
{
  "error": {
    "message": "(#2635) You are calling a deprecated version of the Ads API. Please update to the latest version: v13.0.",
    "type": "OAuthException",
    "code": 2635,
    "fbtrace_id": "Ap915RPpqQkrcR3PLxa3qNr"
  }
}
This means that you are calling a version of the API that is no longer supported. In order to support new features, Facebook releases new versions of the ads API on a frequent basis. Old versions will stop working once a new version has been available for at least 90 days.
Solution: Update your endpoints to use the newest version. You can read more about Facebook's deprecation schedule here.

async_status: "Job Failed" in Asynchronous Reports

Some asynchronous ads insights API calls may fail and end up in the Job Failed state instead of the Job Completed state.
These failures are often transient.
Solution: Backoff a few seconds, then retry the job again. We recommend retrying the job up to 5 times before giving up permanently.

Dynamic ad creative breakdowns return no rows

Sometimes, when you pass ad_format_asset, body_asset, call_to_action_asset, description_asset, image_asset, link_url_asset, title_asset or video_asset, you get no results.
Solution: These fields only have values when reporting at a level more granular than the default account level. Pass level=campaign, level=adset or level=ad in your request.

The frequency_value breakdown returns no rows

The frequency_value dimension works in tandem with the reach metric.
Solution: Add the reach metric to your fields parameter.

Facebook Documentation Webpages

We spent many hours scouring the web and reading Facebook’s ever-shifting documentation to put this page together. In addition to the endpoint specific documentation pages linked above, these pages are useful references:
Access Tokens - Learn about the difference between app tokens, user tokens and page tokens.
Action Types - Facebook tracks many kinds of actions that your users do, both on Facebook itself and, if you have the Facebook pixel installed in your app or website, on your own website. Learn how these actions are reported via the API.
App Review - Learn about the Facebook app review process, including a checklist of prerequisites and a list of common app rejection reasons.
Debugging an Access Token - Learn how to inspect an access token to see when it expires and which resources it grants access to.
Field Expansion - Learn how to get what you want in 1 request instead of multiple requests, by expanded nested references automatically with field expansion.
Pagination - Learn how Facebook paginates its API responses.
Rate Limits - There are separate rate limits for the Graph API and for the Marketing API. Learn how Facebook calculates the limits.