External Reporting

Time	Status	User Agent
Retrieving recent requests…

This endpoint is used to pull reporting for an entire program at any grain.

This endpoint requires authorization via an authorization header. Please work with the Koddi team to receive credentials that can be used in the Sessions - Token endpoint. Details for this sessions endpoint can be found here.

Inputs

Sample request body:

{
    "currency_code": "USD",
    "dimensions": [
        "advertiser_id",
        "advertiser_name"
    ],
    "metrics": [
        "cost_per_click",
        "impressions",
        "clicks",
      	"revenue"
    ],
    "filters":[
        {
        "field": "advertiser_id",
        "operation": "=",
         "value": [
                12345
            ]
        }
      ],
    "sort": [
        {
            "field":"impressions",
            "order":"DESC"
        }
    ],
    "start_date": "2020-01-01",
    "end_date": "2020-01-31"
}

Request parameter details:

Field	Type	Description	Required
currency_code	string	The currency code that any monetary fields will be converted to.	Optional (Advertiser currency is default)
dimensions	array of strings	The list of dimensions to retrieve and report on. These are available options to include in the dimensions array: ad_group_id ad_group_media_type ad_group_name ad_group_short_id advertiser_id advertiser_name advertiser_type auction_rank campaign_id campaign_name conversion_source creative_key creative_name daily_date entity_group entity_group_id entity_id entity_name entity_type entity_type_id experience_name hour (please review with your Koddi team before using) io_line_item_amount io_line_item_name io_line_item_number io_name io_number io_remaining_amount io_total_amount keyword media_type month_date onsite_organic_rank (if passed for sponsored listings) onsite_paid_rank (if passed for sponsored listings) purchased_entity_id purchased_entity_name site_id slot week_date Also, you can request addiitonal items (your Koddi team will help with identitying the values to use): Any configured targeting parameter Any item included in a feed (entities, audiences, merchant/POS data) Any meta data (at the advertiser, campaign or ad group level) Any custom attributes Please note that only a subset of these dimensions might be relevant to your program. Please consult your Koddi representative to determine which dimensions to include in your API call.	Required
metrics	array of strings	The list of metrics to retrieve and report on. These are available options to include in the metrics array: ad_group_budget_recommendation auctions_won avg_auction_rank avg_auction_rank_all_auctions avg_bid avg_bid_all_auctions avg_onsite_organic_rank (if passed for sponsored listings) avg_onsite_paid_rank (if passed for sponsored listings) click_through_rate clicked_conversion_rate clicked_order_value_avg clicked_unit_price_avg clicks clicks_at_price_floor cost cost_per_click cost_per_thousand eligible_entity_count entity_count halo_exposed_revenue halo_exposed_roas halo_exposed_transactions halo_exposed_units halo_revenue halo_roas halo_transactions halo_units hours_live impressions opportunities share_of_voice targeted_opportunities unique_user_clicks unique_user_conversions unique_user_impressions video_average_duration_viewed video_complete_view_rate video_completes video_first_quartile_view_rate video_first_quartile_views video_pauses video_second_quartile_view_rate video_second_quartile_views video_starts video_third_quartile_view_rate video_third_quartile_views video_view_through_rate viewed_conversion_rate viewed_order_value_avg viewed_unit_price_avg win_rate win_rate_with_auctions_won Please note that only a subset of these dimensions might be relevant to your program. Please consult your Koddi representative to determine which dimensions to include in your API call.	Required
filters	object	The list of metrics or dimensions to filter on, and their operators.	Optional
field	string	The name of the dimension or metric you want to filter on	Required if filters object is present
operation	string	The operator of the filter	Required if filters object is present
value	string	The value of the dimension or metric that you want to filter on	Required if filters object is present
pagination	object	The pagination parameters.	Optional
start	integer	The start index.	Optional
count	integer	The count of objects to return. If null then ONLY 250 rows will be returned.	Optional
sort	array of objects	The list of sort options. Will sort by last_modified ascending by default.	Optional
field	string	The field to sort on.	Required if sort object array is present
order	string	The order to sort by, either ASC or DESC.	Optional. The report will sort in ascending order if not provided.
start_date	string	The start date of the report date range.	Required
end_date	string	The end date of the report date range.	Required

📘
A note on the pagination count....
If no count variable is provided, only the first 250 records will be returned.

Lookback Period for Bulk Data Pulls

Minor data restatements happen in due course of advertising business operations. We generally try to keep them to a minimum, but as a safeguard we generally suggest at least a 3 day look back window on the bulk endpoints. If data is restated beyond the 3 day window, a message will be posted on status.koddi.com and your Koddi team will send you a direct message.

Response

Field	Type	Description
headers	array of objects	The list of headers for the report. This corresponds directly to the metrics and dimensions included in the request.
name	string	The internal name of the field.
title	string	The user-facing label of the field.
type	string	The field type.
data	array of objects	The list of dictionary data point objects. These have keys corresponding to the headers.

Inputs

A note on the pagination count....

Lookback Period for Bulk Data Pulls

Response

Try It!

200200

400400