t1k:marketing:ua:adjust

Field	Value
Module	`ua`
Version	`1.8.4`
Effort	`high`
Tools	—

How to invoke

/t1k:marketing:ua:adjust

Adjust Report Service API

Adjust is a mobile measurement partner (MMP): attribution + user-acquisition analytics. The Report Service API (RS-API) is the single source of truth for pulling aggregated reporting — installs, clicks, cost, ad revenue, eCPM, ROAS, and retention — into a marketing/monetization dashboard.

The legacy KPI Service is deprecated and has been migrated to the Report Service API. Build only against RS-API.

When to Use

Building a UA spend / ROAS dashboard backed by Adjust reporting
Pulling ad-revenue / eCPM by app and network for monetization views
Exporting Adjust report data (CSV / parquet) for spreadsheets or warehousing
Validating which metric/dimension slugs, apps, countries, and networks a token can query

Authentication

RS-API uses a static per-user Bearer API token — no OAuth, no client-id/secret, no token expiry or refresh.

Authorization: Bearer <adjust_api_token>

Find the token in the Adjust dashboard: gear (bottom-left) > Account settings > My profile tab > User Details > API Token.
Resetting the token in the dashboard immediately invalidates the previous token.
SSO-configured accounts do NOT see the token in the dashboard — request it from your Adjust rep or [email protected].

Credentials needed:

adjust_api_token — static per-user Bearer token (from My profile, or via support for SSO accounts)

Reference: Authentication

Base URL & Endpoints

Base host: https://automate.adjust.com/reports-service

Endpoint	Method	Path	Use
JSON report	GET	`/reports-service/report`	Primary reporting — aggregated KPIs as JSON
Pivot report	GET	`/reports-service/pivot_report`	Pivoted output with per-dimension subtotals
CSV report	GET	`/reports-service/csv_report`	Same query as CSV stream for export
Parquet report	GET	`/reports-service/parquet`	Apache Parquet — recommended for large exports
Filters data	GET	`/reports-service/filters_data`	Discover valid apps/metrics/dimensions/countries

References: RS-API overview · Reports · Pivot · CSV · Filters data

Core Query Model

Every report is built from three required parameters:

dimensions — CSV grouping axes, e.g. app,os_name,partner_name,campaign,week,day
metrics — CSV values to aggregate, e.g. installs,clicks,cost,ad_revenue,ad_impressions,ecpm,revenue,roas_d7,retention_rate
date_period — accepts absolute (2026-01-01:2026-01-31), relative, or logical formats

Spend-affecting parameter:

ad_spend_mode — adjust | network | mixed. Materially changes reported cost/ROAS; always set it explicitly.

Common optional params: app_token__in, os_names, countries, currency, utc_offset, sort (prefix - for descending), sandbox.

JSON response shape:

{
  "rows": [
    { "app": "...", "partner_name": "...", "campaign": "...", "installs": 0, "cost": 0, "attr_dependency": {} }
  ],
  "totals": { "installs": 0, "cost": 0 },
  "warnings": [],
  "pagination": null
}

Key Metrics & Dimensions Glossary

Representative slugs (validate against filters_data / the Datascape metrics glossary before querying):

Volume: installs, clicks, ad_impressions
Spend / efficiency: cost, ecpm, roas_d7 (and other ROAS windows)
Revenue: revenue, ad_revenue
Retention: retention_rate
Dimensions: app, os_name, partner_name, campaign, country, day, week

Metric and dimension slugs are not free-form — an invalid slug returns 400. Use the filters_data endpoint to enumerate valid slugs and populate dashboard dropdowns.

Choosing a Format

Need	Endpoint
Live dashboard reads	`report` (JSON)
Matrix / breakdown views	`pivot_report`
Spreadsheet export	`csv_report` (set `readable_names=true` for human headers)
Large bulk pulls / warehouse	`parquet` (Adjust-recommended)

Filtering & Sorting

Filter operators (pivot/report): __in, __contains, __lt, __gt
app_token__in to scope to specific apps; countries to scope geography
sort accepts a metric/dimension slug, prefix - for descending
currency to normalize multi-currency cost/revenue

Rate Limits & Error Handling

Concurrency-based limit: exceeding 50 simultaneous requests returns HTTP 429. There is no documented per-minute/per-day quota and no rate-limit response headers. Throttle parallel calls rather than spacing sequential ones.
Observed response codes: 200, 204 (no content), 400 (bad slug / malformed date_period), 401 (bad token), 403 (no access), 429 (concurrency), 503/504 (transient — retry with backoff).

Example Dashboard Queries

UA spend & ROAS by campaign (last 7 days, network spend):

GET /reports-service/report
  ?dimensions=campaign,partner_name
  &metrics=cost,installs,roas_d7
  &date_period=2026-05-25:2026-05-31
  &ad_spend_mode=network
  &sort=-cost
Authorization: Bearer <adjust_api_token>

Ad-revenue & eCPM by app and network:

GET /reports-service/report
  ?dimensions=app,partner_name
  &metrics=ad_revenue,ad_impressions,ecpm
  &date_period=2026-05-01:2026-05-31
  &currency=USD
Authorization: Bearer <adjust_api_token>

App Automation API (adjacent, non-reporting)

The App Automation API shares the automate.adjust.com host but lives under /app-automation and handles app config/cloning — not analytics. Do not confuse its base path with /reports-service.

Reference: App Automation API

Gotchas

KPI Service is deprecated. Do NOT build against docs.adjust.com/en/kpi-service; it has been migrated to the Report Service API. Old tutorials/clients (e.g. adjust/api-client-r) target the legacy KPI Service.
SSO accounts cannot see the API token in the dashboard. Request it from your Adjust rep or [email protected] — a common first-time-setup blocker.
Rate limit is concurrency-based (50 simultaneous requests → 429), NOT a documented per-minute quota. Throttle parallelism, not sequential spacing.
ad_spend_mode changes the numbers. adjust vs network vs mixed produce materially different cost/ROAS — always set it explicitly; defaulting silently changes reported spend.
Validate metric/dimension slugs first. They are not free-form; an unknown slug returns 400. Use filters_data or the Datascape metrics glossary.
Use parquet for large exports. Adjust explicitly recommends it over JSON/CSV for performance on big pulls.
date_period format mismatches cause 400. Mixing logical/relative/absolute formats or using the wrong delimiter is a common 400 source — start:end with :.
/app-automation is not reporting. It shares the host but is app-config management; never point reporting queries at it.