Teads Developer Portal

Required request fields

Submit these fields when you create a report. See Dimensions and Metrics for the full list of supported values.

Field	Type	Required	Description
`dimensions`	`array<string>`	Yes	Dimensions to group results by.
`metrics`	`array<string>`	Yes	Metrics to return.
`filters.date.start`	ISO 8601 timestamp	Yes	Inclusive lower bound.
`filters.date.end`	ISO 8601 timestamp	Yes	Inclusive upper bound.
`filters.date.timezone`	IANA timezone	No	Timezone used to resolve daylight-saving shifts.
`emails`	`array<string>`	No	Email recipients. Defaults to an empty list.
`format`	`string`	No	`csv`, `jsonv1`, or `xlsx`; defaults to `xlsx`.

All filters other than date are optional. Most filters use arrays of numeric resource IDs. Status filters are an exception: they use the status value stored in the database, such as 1 for active. The formats filter uses strings such as inread.

Resource filters

Field	Type	Description
`filters.ad_sources`	`array<int>`	Ad source IDs, such as Google DBM ID `3`.
`filters.ad_status`	`array<int>`	Ad status IDs.
`filters.ads`	`array<int>`	Ad IDs.
`filters.adsources`	`array<int>`	Connection IDs.
`filters.advertisers`	`array<int>`	Advertiser IDs.
`filters.creatives`	`array<int>`	Creative IDs.
`filters.insertions`	`array<int>`	Insertion IDs.
`filters.insertion_status`	`array<int>`	Insertion status IDs.
`filters.packs`	`array<int>`	Pack IDs.
`filters.placements`	`array<int>`	Placement IDs.
`filters.placement_status`	`array<int>`	Placement status IDs.
`filters.publishers`	`array<int>`	Publisher IDs.
`filters.scenarios`	`array<int>`	Scenario IDs.
`filters.websites`	`array<int>`	Website IDs.

Text filters

Field	Type	Description
`filters.browser`	`array<string>`	Browser names, such as `Chrome`.
`filters.connection_buy_type`	`array<string>`	Connection buy types, such as `rtb`.
`filters.country`	`array<string>`	ISO 3166-1 alpha-2 country codes, such as `US` or `FR`.
`filters.demand_source`	`array<string>`	Demand type, such as `direct sold` or `programmatic`.
`filters.device`	`array<string>`	Device names, such as `Desktop`.
`filters.formats`	`array<string>`	Format names, such as `inread`.
`filters.operating_system`	`array<string>`	Operating-system names, such as `Windows`.
`filters.tags`	`array<string>`	Tag IDs or names as supported by the account.

Format filtering warning

Filtering by formats can produce slow or failed requests because of the amount of computation required. If a request fails or takes too long, remove the format filter and filter the returned data afterward.

Output formats

CSV

Use format: "csv" for machine consumption:

day,advertiser_billable_volume,teads_billing-usd
2020-11-23T00:00:00Etc/GMT,30622,197.68621

JSONV1

Use format: "jsonv1" for a structured response containing the request configuration, lines, and totals:

{
  "filters": {
    "placements": [17270]
  },
  "dimensions": ["day", "placement"],
  "metrics": ["placementCall", "start", "complete", "click", "impression"],
  "date": {
    "start": "2020/01/01 00:00:00 +00:00",
    "end": "2020/01/01 23:59:59 +00:00"
  },
  "lines": [["2020/01/01", "17270 - Inread", "1 000", "99", "5"]],
  "totals": ["1 000", "99", "5"]
}

XLSX

xlsx is the default format and is convenient for human review. Teads Manager users receive reports in XLSX format.

Filters and formats