Decide Knowledge

ReferenceAdvertisers

Advertisers

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

Get Advertiser Performance Data#

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

Retrieve campaign 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/campaigns \
    -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-06-01 12:32:22 EDT",
        "rows": [{
            "start_time": "2025-05-15",
            "end_time": "2025-05-22",
            "campaign": "Campaign 1",
            "cpa": 200,
            "cpc": 1.75,
            "cpm": 1.58,
            "impressions": 1164703,
            "conversions": 87,
            "referrals": 456,
            "spent": 1200
        }, {
            "start_time": "2025-05-15",
            "end_time": "2025-05-22",
            "campaign": "Campaign 2",
            "cpa": 143,
            "cpc": 1.25,
            "cpm": 1.89,
            "impressions": 864703,
            "conversions": 65,
            "referrals": 344,
            "spent": 1500
        }, {
            "start_time": "2025-05-15",
            "end_time": "2025-05-22",
            "campaign": "Campaign 3",
            "cpa": 300,
            "cpc": 2.13,
            "cpm": 1.99,
            "impressions": 783125,
            "conversions": 98,
            "referrals": 765,
            "spent": 2100
        }],
        "column_metadata": [
            {
                "id": "campaign",
                "type": "String"
            },
            {
                "id": "start_time",
                "type": "Date"
            },
            {
                "id": "cpm",
                "type": "Money"
            },
            {
                "id": "conversions",
                "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 Campaign and Device (e.g. “desktop”, “tablet”, “mobile”).

Every breakdown takes the same start_time and end_time request body as /campaigns 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/campaigns/breakdowns/date Retrieve campaign performance data broken down by day.

One row per campaign 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/campaigns/breakdowns/creative Retrieve campaign performance data broken down by creative.

Adds creative_headline and creative_id columns 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/campaigns/breakdowns/device Retrieve campaign performance data broken down by device.

Adds a device 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/campaigns/breakdowns/device_creative Retrieve campaign performance data broken down by device and then creative.

Adds device, creative_headline, and creative_id columns 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/campaigns/breakdowns/device_date Retrieve campaign 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/campaigns/breakdowns/creative_date Retrieve campaign performance data broken down by creative and then day.

Adds creative_headline and creative_id columns to every row, with one row per creative 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/campaigns/breakdowns/device_creative_date Retrieve campaign performance data broken down by device and then creative and then day.

Adds device, creative_headline, and creative_id columns to every row, with one row per device per creative per day. This is the most granular advertiser 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