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

Find more examples under Available Options.

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

Add the below options as additional parameter in your formula.

"sort_by". Use this parameter to sort your data by metric. The sort is defaulted to Descending. Popular options are spend and clicks.
=accounts("this week", A1:H1, {"sort by", "clicks"}) 

"limit". Set how many rows to return. Our recommended 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}) 

*If a query takes more than 30 seconds to load in, Google will timeout and fail. Try lowering your limit or simplifying your filters. If you need all the data, use offset, below:

"offset". (Advanced feature) Create paging by using offset. This is primarily used if queries are pulling so much data they fail. 

=accounts("this week", A1:H1, {"limit", 2000}, {"offset", 1000})

"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 -  "name" and "network" are reliably supported.  "status"  and  "currency_code"  can 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)

"targets". (Advanced feature) By default, all of your adstage data across your entire organization will be pulled. If you want to only include certain things, Targets are your way to go. Targets can be a comma-separated list of identifiers for accounts, folders or account groups to narrow the scope of the data. 

Account example:
=campaigns("this week", A1:H1, {"targets", "/network/adwords/account/187274837"}) 

 Account Group example:
=campaigns("this week", A1:H1, {"targets", "/network/adstage/account_group/536"}) 

Folder example:
=campaigns("this week", A1:H1, {"targets", "/network/adstage/folder/1dab451a-84f6-41ba-97d9-875b8fe099107"}) 

To find the AdStage Entity ID of the account/account group/folder you are looking for build a table in Report with the field AdStage Entity ID. More here

When reporting on the Account Group or Folder level, the creator of the Sheet must have the Account Group/Folder set up in their own AdStage account. 

Using Facebook Real-Time data? Check out our Facebook Direct Parameter article:

Did this answer your question?