ReferenceAPI Reference

API Reference

Performance endpoints are split by account type. Pick the one that matches your account and click through to get started.

Publishers

Ad unit performance data from /v1/ad_units, with breakdowns by site, device, and day.

Advertisers

Campaign performance data from /v1/campaigns, with breakdowns by creative, device, and day.

Columns

Every field that can appear in row data, and what it means.

Data Types

How String, Numeric, Date, Money, and Percent values are formatted.

Conventions#

The rules below hold for every endpoint, so they aren’t repeated on each page.

Base URL and method#

All endpoints live under https://dashboard.decide.co/v1 and take their arguments as a JSON request body, which makes them POST requests. A request whose path is missing the /v1 segment gets a 404, as does an unrecognised path under /v1.

Authentication#

Every endpoint except /login requires a login token in the Authorization header:

authorization: Bearer <your_login_token>

See Quick Start for how to generate one. Tokens are valid for 30 days.

Time range#

Every performance endpoint takes the same two required parameters:

Name	Type	Description
`start_time`*	string	Start time in `yyyy-mm-dd`. Inclusive.
`end_time`*	string	End time in `yyyy-mm-dd`. Inclusive.

* Required.

Both must be exactly ten characters, must parse as real dates, must not be earlier than 2015-04-01, and must not be in the future. Hourly granularity is not supported — the smallest unit is a day.

Response envelope#

A successful response is a JSON object with a single result key. Inside it you always get the same four 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.

Errors#

Every error, whichever endpoint produced it, comes back as {"http_status": <code>, "message": "<reason>"}. http_status repeats the HTTP status of the response and message explains the failure, so one code path can read both off any failed request.

Status	Message	Cause
`400`	`Request body is not valid JSON`	The body could not be parsed.
`400`	`Start time must be before end time`	The range is inverted.
`400`	Varies — names the argument and what is wrong with it	A `start_time` or `end_time` the API rejected. See the note below.
`400`	Varies	On `/login` only: the username and password did not match.
`401`	`Authentication failed`	The `Authorization: Bearer` header is missing or malformed.
`401`	`Invalid login token`	The token isn’t recognised.
`401`	`Sorry, your login token has expired.`	The token is older than 30 days.
`404`	`Version number not found in URL path (/v1)`	The path is missing the `/v1` segment.
`404`	`Endpoint not found`	The path under `/v1` is not one of the documented endpoints.
`413`	`Request body is larger than the 512000 byte limit`	The request body exceeds 500 KB.
`429`	`Maximum request limit reached. Please check rate limiting rules in documentation.`	See Rate Limits.
`500`	`An unspecified internal error occurred`	A server-side failure.

A rejected date returns 400

A start_time or end_time that is missing, not a string, not exactly ten characters, unparseable, earlier than 2015-04-01, or in the future returns 400, and the message names the argument and what is wrong with it — for example start_time cannot be after current time, got 2099-01-01. Fix the argument and send the request again; retrying it unchanged will fail the same way.