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","date_keyword", "month", "day_keyword" or "subId".
  
  • groupby=day_keyword - results grouped by date AND keyword. This allows requesting data for multiple dates, at keyword level, in a single request.
  • groupby=subId - results grouped by subid.
  Note: Group by date_keyword can only work with from_date and to_date parameters together, not work with period.(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&&api_key=key&mode=report&period=last%207%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&api_key=key&mode=report&period=last%207%7&days&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>




• In this example, we will show the results of groupby "day_keyword".

  Example query:

  
  
  https://www.trillion.com/api.html?username=user&apikey=key&mode=report&groupby=day_keyword&from_date=2023-05-02&to_date=2024-01-01

  Response:

  
  
  

  <results>
  <result Report_id="6333" Status="Processing"/>
  </results>
  

To fetch results, use the report status API call.




• In this example, we will show the results of groupby "subId".

  Example query:

  
  
  https://www.trillion.com/api.html?username=user&apikey=key&mode=report&groupby=subId&from_date=2023-05-02&to_date=2024-01-01

  Response:

  
  
  

  <results>
  <result Report_id="6334" Status="Processing"/>
  </results>
  

To fetch results, use the report status API call.

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 - Parameter period is not compatible with date_keyword grouping. Specify From Date and To Date only instead.
• 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 API Key invalid.

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