API Connector Documentation

Print

Import Instagram Data to Google Sheets

Last Updated OnJanuary 8, 2024
byAna
< Knowledge Base

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

The easiest way to get started with the Instagram Insights API is through API Connector’s built-in integration.

  1. In Sheets, open API Connector and create a new request (Extensions > API Connector > Open > Create request)
  2. Select Instagram from the drop-down list of applications
    instagram-application
  3. Under Authorization, click Connect to Instagram
    instagram-authorization
  4. 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
  5. You'll then be returned to your Google Sheet, and can verify that your Instagram Insights connection is active.

Part 2: Get your Instagram Business Account ID

Requests to Instagram's API requires use of your Instagram Business Account ID. This requires a sequence of two requests to retrieve:

  1. In API Connector, create a Custom request URL of https://graph.facebook.com/me/accounts. Choose Instagram Insights from the OAuth dropdown menu and hit Run.
    instagram-response1
  2. Note the value in the data.id field as we'll plug that into this next request.
  3. Create a new request URL of https://graph.facebook.com/YOUR_DATA_ID?fields=instagram_business_account. As before, select Instagram Insights from the OAuth menu, and hit Run.
    instagram-response2
  4. Your Instagram Business Account ID is located in the instagram_business_account.id field. Keep that handy as we'll use that in all our requests.

Part 3: Pull Data from Instagram to Sheets

Now that we have our ID, let’s pull some data into Sheets.

  1. Under Endpoint, choose the data you'd like to retrieve. Let's start by getting an account overview.
    instagram-endpoints
  2. Under Path parameters, fill in your business account ID from above.
  3. Select the fields you'd like to see in your report, select a destination sheet, and Run your request.
    instagram-response3
  4. Now repeat for any other data points of interest: engagement insights, post metrics, etc.

Part 4: Create a Custom API Request

Alternatively, you can run your own custom requests instead of using API Connector’s pre-built integration, using any of the endpoints and parameters shown in the API documentation. Here's an example request setup:

  • Application: Custom
  • Method: GET
  • Request URL: https://graph.facebook.com/v14.0/11111111/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&limit=100
  • OAuth: Instagram Insights
instagram-img15

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. To get more records, you can set the limit parameter to 100.
  2. If you still have more records after that, the URL for the next page of results is printed into the paging.next field. You can loop through those next page URLs automatically with pagination handling, like this:
    • Pagination type: next page URL
    • Field name: paging.next
    • Run until: choose when to stop fetching data
      instagram-pagination-nextpageurl

Part 6: Flatten Fields to Headers

By default, Instagram's insights reports print out into rows instead of column headers, like this:
instagram-rows

To print these metrics into individual columns instead of rows, use API Connector's flatten function with the following settings:

  • Flatten field to header: custom
  • Path to header: data.title
  • Path to value: data.total_value

Part 7: API Documentation & Resources

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:

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 in the long run may be less reliable than using the official API, but they can simplify the connection process and provide some data points that Instagram doesn't provide itself.

Appendix: Daily Metrics Template

In this template, everything is configured for you to type in your Instagram business ID and an end date, and fetch the trailing 31 days of daily engagement metrics for your Instagram account.

instagram-dailymetrics

Get a copy of the template here.

72 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. 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: since/until can only fetch 30 days at a time, so you need to make a few different fetches to retrieve your data.

      Reply

      • Hi Ana,

        Love your post. I have the same use case as Leo's and I kept getting this error message, even though the date range is under 30 days:

        {"error":{"message":"(#100) (follower_count) metric only supports querying data for the last 30 days excluding the current day","type":"OAuthException","code":100,"fbtrace_id":"A_xShfApDTNImI9MgflzEa4"}}

        Thanks so much!
        - Firas

      • Instagram's follower_count metric is only available for the last 30 days specifically, it's not just a 30 day range. So back-dating the query doesn't work since they don't provide any historical data past the last 30 days.

  2. 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!

    Reply

  3. 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

      Reply

  4. 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

  5. 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?

  6. 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

  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

      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. Hi again! Yes, so I double-checked to make sure I was using my Instagram Business ID, and the same results came up. Do you have any idea why this may be happening?

    Reply

    • I can only guess that you've inadvertently entered a line break or extra character, since as far as I know the only possible cause of this error is an incorrect ID. You can try copying/pasting it in again (or reference the cell). If you'd like me to take a look feel free to send over a screenshot of your business ID and request setup and I can help spot the difference 🙂

      Reply

  12. 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. Or feel free to reach out through support if you'd like me to take a look at your request setup.

      Reply

  13. sorry if I missed a lesson up there, but is there a way to get total interactions (engagements) of an account within a day? and number of reach of a post within a day?

    I surely appreciate your great lesson up there, and more if you kindly help me with above issue

    Reply

    • Hey Rono, if you want to get engagement from a specific day, you can use a URL like this: https://graph.facebook.com/v12.0/17841403836625216/insights?metric=impressions, reach, website_clicks, profile_views&period=day&since=1639785600&until=1639872000
      If you leave off the since/until parameters, it will give you yesterday and the prior day’s data.

      For reach of a specific post, you'd use a URL like this:https://graph.facebook.com/POST_ID/insights?metric=reach

      Reply

  14. Hey! This is such a great tool. I'm trying to aggregate daily data very similar to Rono in the comment above. I've pulled the data but all the dates are populated in this format: "2021-01-01T08:00:00+0000". This appears to have aggregated the reporting based on the PST timezone rather than as UTC. Do you know if there is a way to aggregate the data using UTC? (I'm trying to match these metrics to other datasources that are using UTC.) According to the documentation, they say that the API is delivering in UTC so I'm wondering if I just have a parameter off or something. https://developers.facebook.com/docs/instagram-api/guides/insights#utc

    -Ted
    https://moonbaselabs.com/

    Reply

    • Thanks, Ted! I get the same results, each day comes back as yyyy-mm-ddT08:00:00+0000, which as you noted corresponds to midnight PST.
      I believe this is Facebook's default timezone, and I don't see any way to change it. In one place their documentation alludes to this, though not very clearly (it says Metrics that support lifetime periods will have results returned in an array of 24 hour periods, with periods ending on UTC−07:00)

      Reply

  15. Is there a way of getting just the follower count when using https://graph.facebook.com/v9.0/BUSINESS_ID?fields=followers_count? Whenever I use that command, It also prints off the ID, and headers for the columns.

    Reply

  16. Hi, I'm currently trying out the extension. But I can not get any Data from my Instagram. I can request both of the ID's. But all of the other requests I put in after that fail with this message:

    1) IG Test: Completed with errors
    - We received an error from facebook.com (400) show response

    {"error":{"message":"(#100) Tried accessing nonexisting field (ig_id) on node type (Page)","type":"OAuthException","code":100,"fbtrace_id":"AYkkMd0wActjZ2F9QHSRZ3Q"}

    Reply

    • Their error message says you're using the Page node for the ig_id field, i.e. you're using your Facebook Page ID to get Instagram metrics. To get Instagram metrics, you'll need to use your Instagram Business ID instead. You can see more about Instagram's error messages here: https://developers.facebook.com/docs/instagram-basic-display-api/reference/error-codes.
      Also, if you're sure you're using the right ID, it could be that you didn't connect the Facebook Page with the Instagram account, so I would also test disconnecting and reconnecting the connection, making sure to link the accounts during that process.

      Reply

  17. Hey guys,

    Great tool so far!
    I'm having trouble importing Instagram Story data tho.
    Here's my URL:
    https://graph.facebook.com/v11.0/XXXXX/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

    The only data.media_product_type I get is "FEED".
    Where's my mistake?

    - Mark

    Reply

  19. when I use https://graph.facebook.com/v12.0/111111111111/insights?metric=reach,impressions,profile_views&period=day&since=+++Inputs!B1+++&until=+++Inputs!B2+++
    it only showed "Request processed, no records found". But I import 14 days data, it is impossible to have this problem.

    Reply

    • Can you please check the raw data response from the API? If you see data there but not in your sheet, then click Output options > View more > JMESPath to make sure there's no JMESPath expression filtering your data. You can also click Edit Fields and make sure you haven't filtered out the fields in your request.

      Reply

      • Hmm I can't seem to replicate this, I just tested several scenarios and could only get the "no records found" error when I filtered out all fields in the field editor. Even using invalid timestamps didn't produce this error. Mind contacting support so I can take a look?

  20. Hello,

    is there a chance to make that reporting from Instagram to Sheets fully automatic, lets say everyday the API Connector would update the info in Sheets so I dont need to provide any activities manually?

    Thabk you in advance.

    Reply

      • Thank you for your reply, Ana. Let me please have another question: how can I get the number of gained followers and unfollows for the last 24 hours?

        Thank you so much in advance.

      • Hi El, the Instagram API doesn't have a metric for unfollows. I think the following 2 requests will be useful for you:
        1) https://graph.facebook.com/v12.0/1111111?fields=followers_count. This provides a count of total followers at the time you run the request.
        2) https://graph.facebook.com/v12.0/1111111/insights?metric=follower_count&period=day. This provides a count of new followers per day. You can optionally add since and until parameters to get more data (up to a range of 30 days).
        From here you can calculate the number of unfollows (e.g. If you have 100 followers on day 1, 110 followers on day 2, and 12 new followers, that means you have 2 unfollows).

        It's a bit clunky but that's the best we can do with the data provided.

      • So, there is no chance to get the number of followers for the last 7 or 30 days? I can only get the number of actual followers?

        Thanks in advance

      • You can, the second request URL shows how to get the number of new followers by day. You could get data for the last week by adding since/until stamps like this: https://graph.facebook.com/v12.0/17841403836625216/insights?since=1648598400&until=1649203200&metric=follower_count&period=day

  21. Hi Ana,
    Is there any way to import some sort of shares count onto google sheets? I have tried including "shares" or "shares_count" into multiple URLs but it doesn't read it. Is this a possibility? Or is this data not included? Thank you.

    Reply

    • Unfortunately this data isn't provided by Instagram, they only provide engagement (sum of likes_count, comment_count, saved), saved, impressions, reach, and video_views metrics (info).
      Update: As of v18, Instagram now provides more specific engagement metrics.

      Reply

  22. Please help me. An error message is displayed. Is this wrong?

    https://graph.facebook.com/v14.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&limit=100

    Error message；
    1) Instagram Daily: Completed with errors
    - We received an error from facebook.com (403) show response{"error":{"message":"(#200) Provide valid app ID","type":"OAuthException","code":200,"fbtrace_id":"ACaBTXW_Gy_EDHD0YZBmaWB"}}

    Reply

    • It sounds like you haven't selected Instagram Insights connection from the OAuth dropdown menu, can you please make sure it's selected?
      Also, instead of creating a custom request, I suggest using the built-in Instagram integration, as it automatically applies OAuth and will avoid this type of issue.

      Reply

    • Their insight documentation says "The API only reports organic interaction metrics; interactions on ads containing a media object are not counted" which sounds like promoted post data is not included, but I'm not totally sure as I've never tested this myself. If you'd like to try it out and see, feel free to message support, I'll be happy to give you a free temporary account so you can see what data gets returned.

      Reply

  24. Hello Ana,
    frist, thank you for this great guide.

    i want to engagement data for instagram media. and than i try to this work.

    https://graph.facebook.com/v14.0/IDNUMBER?fields=id,media_type,media_url,like_count,permalink,timestamp

    it was perfect but i need engagement data on this sheet. how can i check engagement data on that url?

    i really need to data for id, timestamp, like_count + engagement data(impression, reach, saved)

    Reply

    • Sure, I think this is what you're looking for, can you please check?
      https://graph.facebook.com/v14.0/111111111111111111/media?fields=media_url,media_type,insights.metric(engagement,impressions,reach,saved)
      To clean it up a bit, you can also use the Flatten fields to columns option, where the path to header = data.insights.data.name, and the path to value = data.insights.data.values. The visual field editor will also let you re-arrange fields and filter out any extra columns.

      Reply

  25. Hi Ana!

    Just like someone above im trying to figure out our follow/unfollow count. I use this:
    https://graph.facebook.com/v12.0/17841403836625216/insights?since=1648598400&until=1649203200&metric=follower_count&period=day

    and changed the business id to ours, but im having trouble with the since/until. How do I get the correct numbers? I get an error that says:

    {"error":{"message":"(#100) (follower_count) metric only supports querying data for the last 30 days excluding the current day","type":"OAuthException","code":100,"fbtrace_id":"A6OAR73V83GyyzV5jiPKq5N"}}

    Thanks for all the help!

    Reply

    • The metric follower_count can only be queried for the last 30 days, but your since/until timestamps are from March 30 to April 6.
      So please update your timestamps to be within the last 30 days, or use API Connector's preset integration as that will let you select dates from a calendar instead of entering UNIX timestamps. If you are using the preset integration, you can get the follower_count metric by selecting the "Get daily engagement insights" endpoint.

      Reply

  26. Hi Ana,

    Is it possible to export a list of my business page's followers and their follower count? Keen to understand who our most followed followers are.

    Regards,
    Pete

    Reply

    • The Instagram API doesn't enable exporting a list of followers; for privacy reasons it's very limited. To get this data you would need to use an unofficial method, e.g. a web scraper or an unofficial API (I can't recommend anything specifically, but if you navigate to https://rapidapi.com/search/instagram you'll see numerous services).

      Reply

  27. Hi! I would like to pull someone's data. is it possible?

    list of their instagram reels, tittles, description of the reels or even comments on their instagram posts and such?

    Reply

Leave a Reply to Blake Douglas Cancel reply

Jump To