This article will help you use the Google Sheets AdStage Add-on. By design, below is a collection of parameters that you can add to functions.

For information about the installation of the add-on and sample templates go here

Example Functions  

Use one of the following custom functions in a cell to get started:

=accounts("last week", {"name", "spend"})   
=campaigns("this month", {"name", "spend"})  
=adGroups("this year", {"name", "spend"})  
=ads("2015-07-04..2015-07-05", {"name", "spend"})  
=keywords("Last 30 Days", {"name", "spend"})

The Basics

Start with an entity level

Start with what entity level you want to target. Use the " = " and then state the "entity level. 

=accounts("last week", {"name", "spend"})   
=campaigns("this month", {"name", "spend"}) 

Insert parameters to your function

Timeframes

The functions allow both relative ranges (phrases like "last 30 days") and specific date ranges. When specifying specific date ranges you can use a cell range of dates (ex:D1:E1) or a date range string of format: "2016-02-28..2016-03-03"

Specify columns

Functions must be supplied the column names to fetch data for. You can make this a list (ex: {"name", "spend"}) or a range of cells - usually your header row (ex: A1:H1)

*Use additional Options

Additional options are added to the end of any of the supported custom functions in a list. You may just tack them on as additional arguments, wrap in a list, or even use a range of cells for configuration as the final parameter (ex: =accounts("this week", {"spend" "name"}, J7:K12))

Available Options

"limit". Set how many rows to return. Safe max is 1000 due to limits with custom functions timing out. If you do not specify, a limit we default to 25 rows. Example:
=accounts("this week", A1:H1, {"limit", 100})

"networks". Filter your cross-network data to specific networks. Example:
=campaigns("this week", {"spend", "date", "campaign name"}, {"networks", "adwords,bing_ads"})

"statuses". Filter down to certain statuses, such as only active, or including deleted items. Valid options are "all", "all_with_deleted", "all_active", "all_inactive" Example:
=campaigns("this week", A1:H1, {"statuses", "all_with_deleted"})

"timeframes".  Filter down to certain timeframes, such as "today", "this_month", "last_year". Example:
=campaigns("this week", A1:H1, {"statuses", "all_with_deleted"})

timeframes:

  • Today: this 1 day
  • Yesterday: last 1 day
  • Last 3 days: last 3 days
  • Last 3 days, including today: this 3 days
  • This month: this month
  • This month and last month: this 2 months
  • Last month: last month
  • Last month and the month before it: last 2 months
  • This year: this year
  • This year and last year: this 2 years
  • Last year: last year
  • Year to date: this year, up to end of yesterday
  • Year to now: this year, including today’s data (last sync)
  • Month/week to date/note

notes about timeframes:
THIS vs. LAST
If you want to include today, use THIS x days/weeks/months/years. If you don’t want to include today use LAST x days/weeks/months/years.

"...to date" vs. "...to now"
If you want to look include the last full day of data use, "...to date". If you want to include today's data (last import sync) use, "...to now". 

"relative_to". When using relative timeframes like "this month", specifies what day you're asking for (defaults to today). Example to pull data for June 2016 specifically without building a date range:
=campaigns("this month", {"spend", "date", "campaign name"}, {"relative_to", "2016-06-18"})

"aggregate_by". Get back data broken down by day, week, or month instead of totals. Use the special column name "Date". Example:
=campaigns("this week", {"spend", "date", "campaign name"}, {"aggregate by", "day"})

"group_by". Get back data aggregated by a common column - currently only "network" is reliably supported, but status or currency_code could be used as well. Example:
=campaigns("this week", {"spend", "date", "campaign name"}, {"group by", "network"})

"filters". Filters to apply to your data, such as campaign name matching (ex: "campaign name ~ Brand" for campaign names containing brand) and spend filtering (ex: "spend > 0"). Combine multiple filters with a semicolon: ";" Example:
=campaigns("this week", A1:H1, {"filters", "spend > 0; campaign name ~ Brand"})

Valid filters are:

  • >  (greater than)
  • < (less than)
  • ~ (text match)
  • !~ (text does not match)
  • = (text or number is exactly)

"targets". (Advanced feature) By default, all of your adstage data across your entire organization will be pulled. Targets can be a comma-separated list of identifiers for accounts, folders or account groups to narrow the scope of the data. Example:
=campaigns("this week", A1:H1, {"targets", "/network/adstage/folder/1dab451a-84f6-41ba-97d9-784b8fe09910f"})

Using Facebook Real-Time data? Check out our other FAQ, Click the button below!

Did this answer your question?