Skip to main content

Google Sheets

The SocialAPIs add-on for Google Sheets adds formulas that pull public Facebook and Instagram data into a sheet: Page followers, Instagram profiles and posts, Meta Ads Library ads.

Install​

The add-on is coming soon to the Google Workspace Marketplace. Install steps and the listing link: socialapis.io/integrations/google-sheets.

Add your API key​

  1. Copy your API key from the dashboard.
  2. In Sheets, open Extensions → SocialAPIs → Set API key.
  3. Paste the key and select Check and save. The check calls the free /usage endpoint, so it doesn't spend a credit.

The key is stored in your Google account's properties for the add-on and sent only to https://api.socialapis.io in the x-api-token header. In a shared spreadsheet, formulas use the key of the spreadsheet's owner (a Google rule for custom functions).

Functions​

FormulaEndpointCreditsReturns
=SOCIALAPIS_FB_PAGE(link, [field], [exact])GET /facebook/pages/details1, or 5 with exact TRUEOne field (name, followers, followers_display, likes, likes_display, category, verified, url, ad_page_id, image), or every field as a 2-row table
=SOCIALAPIS_FB_PAGE_ID(link)GET /facebook/pages/id1The numeric Page ID, as text
=SOCIALAPIS_IG_PROFILE(username, [field])GET /instagram/profile/details1One field (username, full_name, followers, following, posts, bio, verified, private, category, url), or every field as a 2-row table
=SOCIALAPIS_IG_POSTS(username)GET /instagram/profile/posts1One row per post of the first page: post_url, shortcode, type, likes, views, owner, counts_hidden
=SOCIALAPIS_FB_ADS(keywordOrAdPageId, [country])GET /facebook/ads/search1Active ads, one row per ad: ad_archive_id, advertiser, headline, text, cta, platforms, start_date, landing_domain, ads_library_url
=SOCIALAPIS_FB_POSTS(link, [limit])GET /facebook/pages/posts1 for 3 posts (default), 2 for 5-7, 3 for 8-9One row per post, with the API's own fields as columns
=SOCIALAPIS(endpoint, [params…])any endpoint of this sitewhat the endpoint costsOne row per item of the answer's list, or its fields as a 2-row table. params: "link=nasa&limit=6" or name, value pairs
=SOCIALAPIS_USAGE([field])GET /usagefreecredits_remaining (default), credits_used, usage_percent, plan, reset_at, base_credits, bonus_credits, never_expire_credits

link takes a Page URL or a username (nasa, facebook.com/nasa). For ads, a keyword searches active ads in a country (default US); a numeric ad_page_id (from =SOCIALAPIS_FB_PAGE(link, "ad_page_id")) lists one Page's ads (default country ALL).

Exact follower count: big Pages show a rounded count (e.g. 28M). =SOCIALAPIS_FB_PAGE("nasa", "followers", TRUE) returns the exact number for 5 credits instead of 1.

Any endpoint: =SOCIALAPIS("/facebook/search/pages", "query=coffee shop&limit=5") or =SOCIALAPIS("/facebook/pages/posts", "link", "nasa", "limit", 6). Every endpoint in this reference works, with its own parameters and credits.

In a sheet set to French, German, Spanish and many other languages, Google Sheets separates arguments with ; instead of ,: =SOCIALAPIS_FB_PAGE("nasa"; "followers"). Extensions → SocialAPIs → Insert example sheet uses the right one for your sheet.

Credits and caching​

Each formula is one API call. Calls that return data are charged, including empty results; errors (4xx/5xx) are not charged. Results are cached for 10 minutes per spreadsheet, so recalculating doesn't spend credits again. SOCIALAPIS_USAGE is never cached.

Errors​

A cell shows #ERROR! with the reason on hover: #NO_KEY (no key saved), #INVALID_KEY, #NO_CREDITS, #RATE_LIMITED, #INVALID_LINK / #INVALID_USERNAME / #UNKNOWN_FIELD (refused before the call, nothing spent), #NOT_FOUND, #API_ERROR (not charged, try again).

Google stops a custom function after 30 seconds, so each formula makes one call and lists return their first page only.