Decide Knowledge

ReferencePublishers

Publishers

To fetch performance data for the ad units associated with your account, send an authenticated request to the /ad_units endpoint.

Get Publisher Performance Data#

POST https://dashboard.decide.co/v1/ad_units

Retrieve ad unit performance data.

Request body

NameTypeDescription
start_time* string Start time in yyyy-mm-dd
end_time* string End time in yyyy-mm-dd

* Required.

Responses

  • 200Success
  • 400Invalid start_time / end_time, or an inverted time range (start after end)
  • 401Authentication error or invalid login token
  • 429Maximum request limit reached
  • 500Unspecified internal error

Example request#

Take a look at how you might call this method via curl. Don’t forget to include your login token in the authorization header.

curl https://dashboard.decide.co/v1/ad_units \
    -H 'content-type: application/json' \
    -H 'authorization: Bearer <your_login_token>' \
    -d '{"start_time":"2025-05-15","end_time":"2025-05-22"}'

The Response Object#

Data is returned as a valid JSON object. A sample response is shown below. It includes the following fields:

  • last_update_time (string) is the time stamp of the request and is meant to signify the freshness of the data.
  • rows (array) contains the data.
  • column_metadata (array) contains the helpful information describing the formatting for the row object fields (or columns) e.g. { id: "cpm", type: "Money" }.
  • unconfirmed_revenue_dates (array) contains dates in the date range that have unconfirmed revenue data.

Here is a sample successful response:

200 | OK

{
    "result": {
        "last_update_time": "2025-05-23 12:32:22 EDT",
        "rows": [{
            "start_time": "2025-05-15",
            "end_time": "2025-05-22",
            "ad_unit": "publisher1_above_content",
            "estimated_revenue": 1854.21,
            "ad_requests": 763251,
            "impressions": 83541,
            "referrals": 456,
            "cpm": 1.12,
            "fill_rate": 0.8,
            "rtr": 0.001
        }, {
            "start_time": "2025-05-15",
            "end_time": "2025-05-22",
            "ad_unit": "publisher1_below_content",
            "estimated_revenue": 781.12,
            "ad_requests": 163251,
            "impressions": 56734,
            "referrals": 276,
            "cpm": 0.91,
            "fill_rate": 0.3,
            "rtr": 0.002
        }, {
            "start_time": "2025-05-15",
            "end_time": "2025-05-22",
            "ad_unit": "publisher1_in_content",
            "estimated_revenue": 123.45,
            "ad_requests": 663251,
            "impressions": 65645,
            "referrals": 301,
            "cpm": 1.54,
            "fill_rate": 0.5,
            "rtr": 0.01
        }],
        "column_metadata": [
            {
                "id": "ad_unit",
                "type": "String"
            },
            {
                "id": "start_time",
                "type": "Date"
            },
            {
                "id": "estimated_revenue",
                "type": "Money"
            },
            {
                "id": "ad_requests",
                "type": "Numeric"
            }

            // additional field definitions (objects) omitted below...
        ],
        "unconfirmed_revenue_dates": []
    }
}

See Columns for a detailed list of the columns that are returned in the row data.

Optional breakdowns#

The API supports optional “breakdown” endpoints that group data by additional fields for greater granularity. For example, the device breakdown will return one row for each unique combination of Ad Unit and Device (e.g. “desktop”, “tablet”, “mobile”).

Every breakdown takes the same start_time and end_time request body as /ad_units and returns the same response envelope. The only difference is the number of rows and the extra column each breakdown adds to every row.

POST https://dashboard.decide.co/v1/ad_units/breakdowns/date Retrieve ad unit performance data broken down by day.

One row per ad unit per day. start_time and end_time on each row narrow to the day that row covers.

Request body

NameTypeDescription
start_time*stringStart time in yyyy-mm-dd
end_time*stringEnd time in yyyy-mm-dd

Responses

  • 200Success
  • 400Invalid start_time / end_time, or an inverted time range (start after end)
  • 401Authentication error or invalid login token
  • 429Maximum request limit reached
  • 500Unspecified internal error
POST https://dashboard.decide.co/v1/ad_units/breakdowns/site Retrieve ad unit performance data broken down by site.

Adds a site column to every row.

Request body

NameTypeDescription
start_time*stringStart time in yyyy-mm-dd
end_time*stringEnd time in yyyy-mm-dd

Responses

  • 200Success
  • 400Invalid start_time / end_time, or an inverted time range (start after end)
  • 401Authentication error or invalid login token
  • 429Maximum request limit reached
  • 500Unspecified internal error
POST https://dashboard.decide.co/v1/ad_units/breakdowns/device Retrieve ad unit performance data broken down by device.

Adds a device column to every row. Supported alias: /v1/ad_units/breakdowns/devices.

Request body

NameTypeDescription
start_time*stringStart time in yyyy-mm-dd
end_time*stringEnd time in yyyy-mm-dd

Responses

  • 200Success
  • 400Invalid start_time / end_time, or an inverted time range (start after end)
  • 401Authentication error or invalid login token
  • 429Maximum request limit reached
  • 500Unspecified internal error
POST https://dashboard.decide.co/v1/ad_units/breakdowns/device_site Retrieve ad unit performance data broken down by device and then site.

Adds device and site columns to every row. Supported alias: /v1/ad_units/breakdowns/devices_and_site.

Request body

NameTypeDescription
start_time*stringStart time in yyyy-mm-dd
end_time*stringEnd time in yyyy-mm-dd

Responses

  • 200Success
  • 400Invalid start_time / end_time, or an inverted time range (start after end)
  • 401Authentication error or invalid login token
  • 429Maximum request limit reached
  • 500Unspecified internal error
POST https://dashboard.decide.co/v1/ad_units/breakdowns/device_date Retrieve ad unit performance data broken down by device and then day.

Adds a device column to every row, with one row per device per day.

Request body

NameTypeDescription
start_time*stringStart time in yyyy-mm-dd
end_time*stringEnd time in yyyy-mm-dd

Responses

  • 200Success
  • 400Invalid start_time / end_time, or an inverted time range (start after end)
  • 401Authentication error or invalid login token
  • 429Maximum request limit reached
  • 500Unspecified internal error
POST https://dashboard.decide.co/v1/ad_units/breakdowns/site_date Retrieve ad unit performance data broken down by site and then day.

Adds a site column to every row, with one row per site per day.

Request body

NameTypeDescription
start_time*stringStart time in yyyy-mm-dd
end_time*stringEnd time in yyyy-mm-dd

Responses

  • 200Success
  • 400Invalid start_time / end_time, or an inverted time range (start after end)
  • 401Authentication error or invalid login token
  • 429Maximum request limit reached
  • 500Unspecified internal error
POST https://dashboard.decide.co/v1/ad_units/breakdowns/device_site_date Retrieve ad unit performance data broken down by device and then site and then day.

Adds device and site columns to every row, with one row per device per site per day. This is the most granular publisher breakdown, so expect the largest response.

Request body

NameTypeDescription
start_time*stringStart time in yyyy-mm-dd
end_time*stringEnd time in yyyy-mm-dd

Responses

  • 200Success
  • 400Invalid start_time / end_time, or an inverted time range (start after end)
  • 401Authentication error or invalid login token
  • 429Maximum request limit reached
  • 500Unspecified internal error