Skip to main content
GET
Get the Apple Ads daily series

Authorizations

Authorization
string
header
required

Bearer authentication using the project Secret Key (prefixed with sk_), used exactly as shown in the dashboard. Endpoints that support sandbox data take an explicit environment field or parameter. All v4 public endpoints require the Secret Key — see Authentication. Never expose the Secret Key in client-side code.

Query Parameters

from
integer<int64>
required

Start of the period, Unix seconds UTC. Bounds the days on the axis (and, for cohort metrics, the install dates).

to
integer<int64>
required

End of the period, Unix seconds UTC. Must be greater than from.

environment
enum<integer>
default:1

0 = sandbox, 1 = production.

Available options:
0,
1
metric
enum<string>
default:spend

One metric to plot; default spend. For window_roas_ and window_cac_, points use the mature cohort-window reading. The response semantics states what each point means.

Available options:
spend,
installs,
impressions,
taps,
ttr,
cpa,
cpt,
cpm,
users,
trials,
trials_converted,
paying,
revenue,
arpu,
arppu,
roas,
cost_per_trial,
cost_per_subscription,
cac,
window_roas_d0,
window_cac_d0,
window_roas_d3,
window_cac_d3,
window_roas_d7,
window_cac_d7,
window_roas_d14,
window_cac_d14,
window_roas_d30,
window_cac_d30,
window_roas_d60,
window_cac_d60,
window_roas_d90,
window_cac_d90,
window_roas_d180,
window_cac_d180,
window_roas_d365,
window_cac_d365
metrics
enum<string>[]

One comma-separated query value, such as metrics=spend,roas,cac. Up to four distinct names from the metric vocabulary, in requested order. A nonempty list overrides metric; empty metrics= falls back to metric (default spend). The first metric is primary. Repeated slots, unknown names, duplicates, and more than four names return 400 invalid_request. metrics[] is unsupported. MCP accepts one metric per call.

Maximum array length: 4
Available options:
spend,
installs,
impressions,
taps,
ttr,
cpa,
cpt,
cpm,
users,
trials,
trials_converted,
paying,
revenue,
arpu,
arppu,
roas,
cost_per_trial,
cost_per_subscription,
cac,
window_roas_d0,
window_cac_d0,
window_roas_d3,
window_cac_d3,
window_roas_d7,
window_cac_d7,
window_roas_d14,
window_cac_d14,
window_roas_d30,
window_cac_d30,
window_roas_d60,
window_cac_d60,
window_roas_d90,
window_cac_d90,
window_roas_d180,
window_cac_d180,
window_roas_d365,
window_cac_d365
revenue_type
enum<string>
default:gross

Which revenue basis feeds the revenue-derived metrics (revenue, arpu, arppu, roas). Both bases exist for every day; this selects the one plotted.

Available options:
gross,
net
currency
string
default:USD

ISO 4217 code, uppercase. Monetary metrics are converted at one midpoint rate for the whole period, reported in currency_conversion. If no exchange rate is available for the period, values are in USD: currency is USD and currency_conversion.rate_unavailable_for holds the requested code.

Pattern: ^[A-Z]{3}$
filter[country][]
string[]

Narrow the cohort (and Apple metrics where Apple supports the split) by storefront country. Array-valued — repeat the key.

filter[campaign_name][]
string[]

Narrow by campaign name. Array-valued — repeat the key.

filter[ad_set_name][]
string[]

Narrow by ad group. Array-valued — repeat the key.

filter[media_source_name][]
string[]

Narrows the Qonversion cohort only; Apple spend is not split by media source. When it does not apply to the requested metric, it is listed in filters_ignored. Array-valued — repeat the key.

filter_not[media_source_name][]
string[]

Exclude these media sources from the cohort. Array-valued — repeat the key. Exclusions of country, campaign_name, ad_set_name, status, and delivery return 400 with reason unsupported_parameter. Other supported cohort attributes can be excluded.

Response

Daily series for the requested metrics; flat fields describe the first line.

object
string
required
Example:

"analytics_apple_ads_series"

url
string
required
Example:

"/v4/analytics/apple-ads/report/series"

metric
string
required

The primary metric; the flat fields describe the first requested line.

unit
enum<string>
required

Granularity. Always day — a point is one UTC day.

Available options:
day
currency
string
required

Currency of the monetary points. If no exchange rate is available for the period, values are in USD and currency is USD (see currency_conversion).

revenue_type
enum<string>
required
Available options:
gross,
net
semantics
string
required

One sentence stating what a point of this metric means, including the cohort attribution where it applies.

is_cohort_metric
boolean
required

true when a point is attributed to the cohort acquired that day (revenue, arpu, arppu, trials, and so on); false when it measures what happened that day (spend, installs, taps).

points
object[]
required

One point per UTC day of the requested period, oldest first. Days without a value are present with value: null.

filters_ignored
string[]
required

Filter codes that do not apply to the requested metric and were not applied, including status and delivery. Sorted. An empty array means every filter was applied.

metrics
enum<string>[]

All resolved metrics in requested order, including a single metric for legacy calls.

Required array length: 1 - 4 elements
Available options:
spend,
installs,
impressions,
taps,
ttr,
cpa,
cpt,
cpm,
users,
trials,
trials_converted,
paying,
revenue,
arpu,
arppu,
roas,
cost_per_trial,
cost_per_subscription,
cac,
window_roas_d0,
window_cac_d0,
window_roas_d3,
window_cac_d3,
window_roas_d7,
window_cac_d7,
window_roas_d14,
window_cac_d14,
window_roas_d30,
window_cac_d30,
window_roas_d60,
window_cac_d60,
window_roas_d90,
window_cac_d90,
window_roas_d180,
window_cac_d180,
window_roas_d365,
window_cac_d365
series
object[]

One line per resolved metric; the first duplicates the legacy flat fields.

Required array length: 1 - 4 elements
coverage
object

Dates with Apple spend data inside the requested period. Present only for metrics that use Apple spend data (spend, installs, taps, roas, cost_per_subscription).

truncated
boolean

Present and true when the requested period is longer than 366 days; the oldest days are omitted.

currency_conversion
object | null

Present when a currency other than USD was requested. Either the rate that was applied, or rate_unavailable_for with the requested code when no exchange rate is available for the period (values are then in USD).