Search API Connector Documentation

Print

Import Instagram Data to Google Sheets

premium

In this guide, we’ll walk through how to pull Instagram Insights data data directly into Google Sheets, using the API Connector add-on for Sheets.

To use the Instagram Insights API, you must have an Instagram Business account that is connected to a Facebook Page, and you must be an admin of that Facebook page. If you need help, this guide provides information on converting your personal Instagram account to a business account.

Contents

Before You Begin

Click here to install the API Connector add-on from the Google Marketplace.

Part 1: Connect to the Instagram Insights API

If you haven’t connected to the Instagram Insights API before, you’ll first need to initiate the connection.

  1. Open up Google Sheets and click Add-ons > API Connector > Manage Connections.
  2. In the list of available connections, find Instagram Insights and click Connect.
    instagram-img2
  3. You will be directed to Facebook and asked to choose which Instagram accounts and Facebook Pages you’d like to use with API Connector. If you are an admin of multiple accounts, make sure to choose the Instagram account and Facebook page that you’ve previously linked together. Click Done.
    instagram-img3
  4. You’ll then be returned to your Google Sheet, and can verify that your Instagram Insights connection is active in the Connections screen.

Part 2: Create Your Instagram API Request URL

For our first request, we’ll get some basic information about your Instagram account.

  • API root: https://graph.facebook.com
  • Endpoint: /me/accounts

Putting it all together, we get the full API Request URL.

https://graph.facebook.com/me/accounts

Part 3: Pull Instagram API Data into Sheets

We can now import our first set of data.

  1. Back in the Create Request interface, enter the Request URL we just created above.
    instagram-img1
  2. Under OAuth, choose Instagram Insights from the dropdown menu. You should see a badge saying “Connected” if you’ve already connected as described in Part 1.
    instagram-connected
  3. You don’t need any headers so just leave that section blank.
  4. Create a new tab and click ‘Set current’ to use that tab as your data destination.
  5. Name your request and click Run. A moment later you’ll see some information about your Instagram account populate your sheet. Pay special attention to the value located in the data.id field as you’ll need it in the next request.
    instagram-data-id

  6. Now let’s use that ID to get your Instagram Business account ID, because we’ll need that for all requests to the /insights endpoint, which is what we’re here for. In a new request, create an API URL like this, substituting in your own data ID.
    https://graph.facebook.com/YOUR_DATA_ID?fields=instagram_business_account
  7. Just as you did before, choose Instagram Insights from the Authentication menu (you’ll need to do this for all requests to the Instagram API) and click Run.

    You should now see your Instagram Business account ID printed into the sheet. Keep this handy, we’ll use this ID to get all our Instagram stats!
    instagram-img7

Part 4: Example API URLs

The Instagram API provides a lot of different endpoints and functionality. I’ve tried to give a lot of examples and summarize the most useful endpoints below, but for more complete information, please check the full Instagram Insights documentation here.

In addition, you can use API Connector’s API Library while in the add-on to easily pull up most of these sample URLs (and many others).

Account/User Metrics

  • Key metrics about an account (id, followers count, following count, etc)
    https://graph.facebook.com/v11.0/YOUR_BUSINESS_ACCOUNT_ID?fields=id,ig_id,followers_count,follows_count,media_count,name,profile_picture_url,username
    instagram-img10
  • Impressions and reach for your Instagram account, for the past 28 days. (Note that the Instagram Graph API returns 2 sets of values, one for the period ending today, and one for the period ending yesterday.)
    https://graph.facebook.com/YOUR_BUSINESS_ACCOUNT_ID/insights?metric=impressions,reach&period=days_28
    instagram-img8
  • Users who have viewed your Instagram business account in the last day.
    https://graph.facebook.com/YOUR_BUSINESS_ACCOUNT_ID/insights?metric=profile_views&period=day
  • A breakdown of cities where your Instagram followers are located
    https://graph.facebook.com/YOUR_BUSINESS_ACCOUNT_ID/insights?metric=audience_city&period=lifetime
    instagram-img9
  • Count of new followers from the prior day
    https://graph.facebook.com/YOUR_BUSINESS_ACCOUNT_ID/insights?metric=follower_count&period=day
  • Metrics by day for a date range (the “since” and “until” parameters contain the start and end dates)
    https://graph.facebook.com/YOUR_BUSINESS_ACCOUNT_ID/insights?metric=impressions,reach,profile_views&period=day&since=1577836800&until=1580428800
The Instagram Insights API requires dates to be entered as UNIX timestamps. In Sheets, you can convert a regular date in cell A1 to a UNIX timestamp with the formula =(A1-DATE(1970,1,1))*86400.

If you want to make a dynamically updating date range, add a dynamic date formula like =today()-1 to one cell, add a second cell that converts it to UNIX with the =(A1-DATE(1970,1,1))*86400 formula, and then reference that UNIX timestamp in your API request URL. Every time the date changes, your URL will update automatically.

Media Metrics (metrics about posts and other content)

  • List of post IDs and metrics. If you need more than 100 records, please check the section on pagination.
https://graph.facebook.com/v11.0/YOUR_BUSINESS_ACCOUNT_ID/media?fields=caption,comments_count,id,ig_id,is_comment_enabled,like_count,media_product_type,media_type,media_url,owner,permalink,shortcode,thumbnail_url,timestamp,username,video_title&limit=100
  • Engagement metrics for a specific post (lifetime totals only)
https://graph.facebook.com/POST_ID/insights?metric=impressions,reach,engagement,saved

Part 5: Handle Pagination

  1. By default Facebook’s graph API, which includes Instagram, limits the number of results in a single response (usually to 25 records) as described here: https://developers.facebook.com/docs/graph-api/using-graph-api/#paging. To get more records, you can add the ‘limit’ parameter (e.g. &limit=100) to the end of your URL (you can try a larger limit value, I’m not sure what the maximum is).
  2. If you still have more records after that, Facebook prints the URL for the next page of results into the paging » next field.
    instagram-img12
  3. In API Connector you can loop through these pages automatically using pagination handling, like this:
    • API URL: enter your request URL, including limit=100
    • Pagination type: next page URL
    • Field name: paging.next
    • Number of pages: enter the number of pages you’d like to fetch
      instagram-img13

Part 6: Useful Links

There are two very useful endpoints for Instagram analytics: /{ig-media-id} (metrics on a media object) and /{ig-user-id} (metrics on an Instagram Business or Creator Account). Each endpoint has different available metrics, as described here:

Available Media Metrics:

Available User/Account Metrics:

Unofficial APIs

The article above discusses Instagram’s official API, which has quite a few limits and isn’t the easiest to work with. Therefore you may also want to check out some of the unofficial APIs listed here: https://rapidapi.com/search/instagram. They have their own limits, and are mostly paid, but they simplify the connection process and provide some data points that Instagram doesn’t provide.

Previous Import Hunter Data to Google Sheets
Next Import Intercom Data to Google Sheets

41 thoughts on “Import Instagram Data to Google Sheets”

  1. Hey Ana,

    how can i see a day by day breakdown of the last 90 -120 days? i tried to use the “data_preset=last_90d” from FB ads account request, but it didn’t work.

    thank you so much for this post/content.
    – Leo.

    Reply
    • Hi Leo, thank you for the comment. To get data broken down by day you need to use the period=day query parameter. Then, to specify a time range, you need to use the since and until parameters, as a UNIX timestamp as described above. Unlike Facebook’s Insights API, the Instagram Insights API doesn’t support the date_preset parameter, so you need to explicitly specify the date.

      One more wrinkle: in my tests, it seems like since/until can only fetch 30 days at a time, though the documentation doesn’t state that clearly. So, in conclusion, you need to make a few different fetches to retrieve your data. If you plug in your dates and the UNIX conversion formula into a sheet called Inputs, then the following should work (just change your date inputs each time and append data into the same sheet):
      https://graph.facebook.com/v8.0/11111111111111111111/insights?metric=impressions,reach,profile_views,follower_count&period=day&since=+++Inputs!C2+++&until=+++Inputs!C3+++

      Reply
  2. Hi, Ana! Is it possible to recieve aggregated engagement data from all posts?

    I use this request – https://graph.facebook.com/v8.0/ig-user-id/insights?metric=engagement&period=day

    but it shows an error:

    “metric[0] must be one of the following values: impressions, reach, follower_count, email_contacts, phone_call_clicks, text_message_clicks, get_directions_clicks, website_clicks, profile_views, audience_gender_age, audience_locale, audience_country, audience_city, online_followers”

    As i understand it works only with ig-media-id instead of ig-user-id. In this way how to create automated scheduled reports for engagement metric?

    Reply
    • Hey Michael, based on what I see here, it looks like you can only get it for individual posts, not aggregated at an account level. So I think you have to do the following:
      1) get a list of your post IDs by running this query: https://graph.facebook.com/v9.0/YOUR_ACCOUNT_ID/media

      2) now substitute in those IDs into this query: https://graph.facebook.com/v9.0/YOUR_POST_ID/insights?metric=engagement,impressions,reach

      To run through a list of IDs, you can reference a range of cells like this: https://graph.facebook.com/v9.0/+++IDs!A2:A10+++/insights? metric=engagement,impressions,reach

      Then you will have engagement metrics for all the posts on your list, and can calculate the overall rate yourself. Can you please check if that would work for you?

      Reply
      • It works, but only for a lifetime period.

        I tried to add ‘period’ or ‘since/until’ to the queries, but it shows incompatible error. It looks like there’s no way to get monthly or daily engagement because of Instagram API limitations.

        But thank you anyway for answers!

      • Bummer, I just investigated this further and confirmed your findings. The Instagram API doesn’t provide any way to slice up the media insights by time, it’s all lifetime totals only. The /{ig-user-id}/insights endpoint does provide time slicing capabilities, but you can’t get the engagement metric there.
        Sorry for the inconvenience, I’ll update the post with some of these findings.

    • Hey Eddy, I don’t have any templates for Instagram but am happy to help you set up some requests to get data. Are there specific metrics you’re looking for?

      Reply
  3. Hi!
    Thank you for your post. I’m having the following error starting Part IV

    Status
    Completed with errors
    – Server responded with an error (400) show response

    ‘show response’ = {“error”:{“message”:”(#100) Tried accessing nonexisting field (insights) on node type (Business)”,”type”:”OAuthException”,”code”:100,”fbtrace_id”:”AdvCGsGT8eVdy5vECPellEV”}}

    Reply
    • Hi Leandro, I haven’t seen this error before so I can’t say for sure, but based on that error message it sounds like Facebook’s API has a problem providing insights data for that account ID. I would double-check some of the requirements: can you please confirm that your Instagram account is a public business or a creator account, that it’s connected to a FB page that you’re the admin of, and that the Instagram account has more than 100 followers?

      Reply
  4. Hello!
    Thank you for this great resource. I’m having quite a bit of trouble with something quite simple, however. I simply want to use the API to find the total number of followers an account (in this case my own) has.

    I feel as though I am missing something very obvious, help would be very appreciated.

    Thank you in advance.

    Reply
    • Hey there, you’re not missing something obvious, they’ve just hidden it deeply in the documentation :p. You can use this request URL to get total followers:
      https://graph.facebook.com/v9.0/YOUR_BUSINESS_ACCOUNT_ID?fields=followers_count
      I’ll update the article to make that more clear.

      Reply
  5. Hi!
    I’m really new to this, so I don’t really understand: is there a way to create automated scheduled reports? I’m trying to create a graph with monthly data, but I don’t know if I should simply do it by the end of the month or I should collect data daily.

    Thanks,
    Trinidad

    Reply
    • Hi Trinidad, sure, you can check this article on scheduling to see how you’d set up your request to refresh every month. So you could run a request like https://graph.facebook.com/v10.0/1111111111111111?fields=id,ig_id,followers_count,follows_count,media_count,name,profile_picture_url,username and then save all the values at the end of each month and re-run the query for new values. You can save the data manually or automate that monthly saving process with my other (totally free) addon Archive Data.

      Also, if you’re asking about getting historical data, that’s harder as the API only provides historical data for certain metrics. So feel free to provide more detail on what exactly you’re looking for.

      Reply
  6. Hi

    I’m having trouble getting all of the post ID of an Instagram account.

    ・I used the below API URL Path, and managed to get 25 id’s but how can I get more then 25 id’s? Is their a number limitation?

    https://graph.facebook.com/YOUR_BUSINESS_ACCOUNT_ID/media

    The output sheet has 4 columns as below.

    data.id, paging.cursors.before, paging.cursors.after, paging.next

    In the “paging.next” column there is a URL and the below message is inside it.

    {
    "error": {
    "message": "A user access token is required to request this resource.",
    "type": "OAuthException",
    "code": 102,
    "fbtrace_id": "ANq-J-qhCojmu43CABXZ02e"
    }
    }

    Reply
    • I added a section on pagination handling to the post, please check that and let me know if that successfully pulls in more records.

      Reply
      • Hi Thanks for the reply

        I made the change and the number increased from 25 to 39..
        but there are over 700 posts on the actual account.

        Let me know what i need to do in order to get at least 200…

      • I checked your sheet and see 700+ posts as expected, can you please let me know if you’re still having issues?

  7. Hello, I am testing your connector and it looks incredible.
    Could you please help me with one thing.
    Requests of this kind https://graph.facebook.com/v11.0/111111111111111111?fields=id,media_type,media_url,owner,timestamp are ok until I add media_product_type.

    With media_product_type I receive an error:
    Server responded with an error (400) show response{“error”:{“message”:”(#12) introduce IGTV to instagram graph api requires version v10.0 or higher”,”type”:”OAuthException”,”code”:12,”fbtrace_id”:”AZWd7Ax4ws56yEzztnzfdWr”}}

    How can I update instagram graph api to latest version?

    Reply
    • I see, it looks like that metric is a new metric available only in the newest API version. However, I’m not sure why you’re seeing this error, it worked fine for me when I tried https://graph.facebook.com/v11.0/1111111111111111?fields=id,media_type,media_url,owner,timestamp,media_product_type. I’ll look into this some more to see if I can replicate it.

      Reply
    • In theory this is possible as Instagram provides a messaging API. However, the method in this article won’t let you connect to it since messaging and insights require different permissions (Facebook / Instagram approve integrations only for the specific permissions requested).

      Reply
  8. Thank you for this amazing article! I’ve been referencing it a ton lately. I’m having a blast using your data methods to make something really pretty in Data Studio!

    I’m having an issue with pulling more than 25 rows of Post IDs, but it could also just be me not understanding things fully.

    Is this what my API URL Path is supposed to look like? https://graph.facebook.com/(FB User ID)/media&limit=150

    When I delete the “&limit=XXX“, it runs just fine. However if I run it otherwise, I get this error:
    Status
    Completed with errors
    – We received an error from the API server (400) show response{“error”:{“message”:”Unknown path components: \/media&limit=100″,”type”:”OAuthException”,”code”:2500,”fbtrace_id”:”AncPkjCs_XddrZIf0RH8iDK”}}

    I tried it with numbers ranging from 50-250. I’m not sure what to do. Do you know what I’m missing?

    Reply
    • Hey Stacie, thank you for the message. That’s awesome you’ve made a Data Studio report – if you wouldn’t mind sharing I’d love to see a copy.
      For your question, the first URL parameter is always separated with a ? while later parameters are separated with a &, so I think you just need to replace the & with an ? like this:
      https://graph.facebook.com/(FB User ID)/media?limit=100

      I’ll update the article to make that more clear. Please try that and let me know how it goes.

      Reply
  9. Hello, I would love some advice or guidance!

    I’m currently making API requests for most of the data mentioned in this tutorial. I have also setup the scheduling of API requests daily, weekly and monthly depending on the data.

    However, I’m struggling to work out a solution to remove duplicates or only make api requests for data not currently in the spread sheet. for example, if I’m making an API request for a list of media posted to the Instagram account I obviously keep having duplicates being added.

    Any guidance or ideas would be greatly appreciated. I’m rather new to google sheets and making api requests. However am a quick learner!

    Thanks in advance!
    Blake

    Reply
    • Hey Blake, can you try a URL like this? https://graph.facebook.com/v11.0/YOUR_BUSINESS_ACCOUNT_ID/media?fields=caption,comments_count,id,ig_id,is_comment_enabled,like_count,media_product_type,media_type,media_url,owner,permalink,shortcode,thumbnail_url,timestamp,username
      Then you’ll have a date associated with each of the posts in your account. This particular API doesn’t provide any way to natively filter data but you can use API Connector’s JMESPath functionality to add in a filter like this:
      data[?timestamp>'2021-02-16T16:59:55+0000'].{caption:caption,comments_count:comments_count,id:id,ig_id:ig_id,is_comment_enabled:is_comment_enabled,like_count:like_count,media_product_type:media_product_type,media_type:media_type,media_url:media_url,owner:owner.id,permalink:permalink,shortcode:shortcode,thumbnail_url:thumbnail_url,timestamp:timestamp,username:username}

      Where it says 2021-02-16T16:59:55+0000, you can also reference a cell instead of hard coding it in, so it dynamically reflects the latest value in your sheet. Then it will only pull in data past that date.

      Reply
      • Thank you kindly for this guidance!

        Would it be possible to get an example of how the JMESpath filter example would look if it’s checking the data.id column in cell C2. From this, I’m confident ill be able to work out the rest.

      • Do you mean you’d like to filter on ID instead of the timestamp? In that case you’d just substitute in “id” for “timestamp” like this:
        data[?id>'17928481555452202'].{caption:caption,comments_count:comments_count,id:id,ig_id:ig_id,is_comment_enabled:is_comment_enabled,like_count:like_count,media_product_type:media_product_type,media_type:media_type,media_url:media_url,owner:owner.id,permalink:permalink,shortcode:shortcode,thumbnail_url:thumbnail_url,timestamp:timestamp,username:username}

      • Hi Ana,

        May I have your email? I’m working on a comprehensive social media dashboard and would love to offer the template along with a detailed setup guide to your website to help get more people using these tools!

      • Hi Ana,

        Could you please provide an example of how this would work “Where it says 2021-02-16T16:59:55+0000, you can also reference a cell instead of hard coding it in, so it dynamically reflects the latest value in your sheet. Then it will only pull in data past that date.” for example referencing the the last row via date or data.id?

      • Sure, first create a dynamic cell in your sheet, setting the format to yyyy-mm-dd. For example like this:
        =text(today()-1,"yyyy-mm-dd")

        Now your filter would reference that cell, like data[?timestamp>'+++Sheet1!A1+++T00:00:00+0000']

  10. this seems like a great tool, and I keep running into the following error trying to run the Instagram Insight extension:
    1) post metrics: Completed with errors
    – We received an error from the API server (400) show response
    {“error”:{“message”:”Unsupported get request. Object with ID ‘{102160809832566}’ does not exist, cannot be loaded due to missing permissions, or does not support this operation. Please read the Graph API documentation at https:\/\/developers.facebook.com\/docs\/graph-api”,”type”:”GraphMethodException”,”code”:100,”error_subcode”:33,”fbtrace_id”:”A6N5D3I1UmsjYXdrlxrbL8i”}}

    Any ideas of what to do?

    Reply
    • Can you please make sure you’re using your Instagram Business ID (not your regular Instagram ID)? I can only get this error when I enter my Data ID or some other ID that’s not the Business ID. As a reminder, you get your Business ID with this query: https://graph.facebook.com/YOUR_DATA_ID?fields=instagram_business_account (full instructions here) Or feel free to reach out through support if you’d like me to take a look at your request setup.

      Reply

Leave a Comment

Table of Contents