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:

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