API Queries - Report

The report function gives you access to reports for your campaign folders. There are several optional parameters, for choosing date periods and grouping. If optional parameters are omitted, the default is today, grouped by keyword (equivalent to specifying: period=today, groupby=keyword).

Additional Parameters

• groupby - Group by either keyword/category or date. Accepted values are "keyword", "date" or "month". (Optional)
• from_date & to_date - The report date range. Dates must be in the format YYYY-MM-DD.
  Note: Valid combinations are from_date and to_date parameters together, or period only. (Optional)
• period - The report date period. Accepted values are "yesterday", "today", "last 7 days", "month to date", "last month", "last 30 days" and "all time". Default is "today". (Optional)
  Note: Valid combinations are from_date and to_date parameters together, or period only. (Optional)
• folder - View report on campaigns in this folder only. (Optional)
• campaign - View report on the campaign specified. (Optional)

Note: Make sure to URL encode all values.

Example queries and responses:

• In this example, we will show the report with the period "last 7 days" and display only the campaign "example".

  Example query:

  https://bid.trellian.com/api.html?username=user&password=pass&api_key=key&mode=report&period=last 7 days&campaign=clothing

  Response:

  <results>
  <result Average_Bid="0.010" Avg_CPV="0.078" Campaign="example" Cost="11.560" 
  Daily_Limit="50.00" Folder="Examples" Geo_Target="US" Highest_Bid="1.07" My_Bid="0.07" 
  Remaining_Daily_Budget="38.44" Traffic="148" Traffic_Type="desktop" Unbilled=""/>
  </results>
  




• In this example, we will show a report for the last 7 days, grouped by date.

  Example query:

  https://bid.trellian.com/api.html?username=user&password=pass&api_key=key&mode=report&period=7%20days&groupby=date

  Response:

  <results>
  <result Billed="2971" Cost="661.130" Date="2018-08-10" Unbilled="40"/>
  <result Billed="2721" Cost="645.390" Date="2018-08-11" Unbilled="0"/>
  <result Billed="2832" Cost="647.470" Date="2018-08-12" Unbilled="0"/>
  <result Billed="3216" Cost="346.000" Date="2018-08-13" Unbilled="0"/>
  <result Billed="3281" Cost="704.720" Date="2018-08-14" Unbilled="4"/>
  <result Billed="3160" Cost="678.410" Date="2018-08-15" Unbilled="0"/>
  <result Billed="2619" Cost="636.060" Date="2018-08-16" Unbilled="1"/>
  </results>
  

If there are no campaign folders in your account, the response will not be an error. Instead, this will be shown:

</results>

Error Responses:

Possible error responses for this function are:

• 420 - Folder not in account.
• 420 - RON not found.
• 420 - Campaign could not be found.
• 421 - RON may only contain letters, digits and periods.
• 421 - Campaign may only contain letters, digits and periods.
• 421 - Folder name may only contain letters, digits and spaces.
• 431 - Reports may be grouped by keyword, date or month.
• 432 - From Date is not a valid date. Dates must be in the format YYYY-MM-DD, for example 2016-10-31.
• 432 - To Date is not a valid date. Dates must be in the format YYYY-MM-DD, for example 2016-10-31.
• 432 - Period is not valid. Valid settings are "yesterday" , "today", "last 7 days", "month to date", "last month", "last 30 days", "last 3 months", "all time".
• 432 - From Date must not be later than To Date.
• 432 - Either period only, or both From Date and To Date must be specified.
• General errors, such as 200 - Internal Error or 300 - Username or password invalid.

For a complete list of error responses, see the Error Codes manual page.