Unified.to
All articles

How to Pull Cross-Platform Ad Performance Reports Using Unified's Advertising API

January 16, 2026

Updated July 2026

Most advertising analytics features fail before the first report is returned.

On paper, ad performance reporting looks straightforward. Pick a date range. Select a campaign. Pull metrics. In practice, those steps only work if every ad platform agrees on how reports are generated, which filters are supported, and what a 'metric' actually represents.

That's where product complexity shows up.

Advertising platforms don't expose reporting in the same way. Some require preconfigured reports. Others return metrics inline with entity objects. Filtering behavior, date semantics, and supported KPIs vary by provider. Even when platforms expose similar metrics, the structure and granularity aren't guaranteed to match.

For product teams, this creates uncomfortable questions:

  • Is reporting a query-driven operation or a static list?
  • Can we use the same filters across Google, Meta, and TikTok?
  • Which KPIs are selectable, and which are computed upstream?
  • Are metrics returned per day, per entity, or as aggregates?
  • Can this feature ship broadly, or only for one provider?

Many products solve this by building provider-specific reporting pipelines or limiting analytics to a single ad platform. That works initially, but it doesn't scale.

Unified's Advertising API is designed to remove that constraint. Instead of forcing you to integrate three different reporting systems, Unified exposes a single, normalized reporting surface where provider differences are handled upstream.

This guide shows how to pull cross-platform ad performance reports using Unified's Advertising API—step by step—without building separate reporting logic for Google Ads, Meta Ads, and TikTok Ads, and without assuming more structure than the API guarantees.

Prerequisites

  • Node.js v18+
  • A Unified account
  • At least one Advertising integration enabled (Google Ads, Meta Ads, or TikTok Ads)
  • Your Unified API key
  • A customer Advertising connectionId

Step 1: Set up your project

mkdir ads-reporting-demo
cd ads-reporting-demo
npm init -y
npm install @unified-api/typescript-sdk dotenv

Create a .env file:

UNIFIED_API_KEY=your_unified_api_key
CONNECTION_ADS=your_customer_ads_connection_id

Step 2: Initialize the SDK

import "dotenv/config";
import { UnifiedTo } from "@unified-api/typescript-sdk";

const { UNIFIED_API_KEY, CONNECTION_ADS } = process.env;

const sdk = new UnifiedTo({
  security: { jwt: UNIFIED_API_KEY! },
});

At this point, you're authenticated and ready to interact with Advertising integrations through a single client.

Step 3: Understand how Ads reporting works (critical)

Unified exposes advertising reports through a single list endpoint:

GET /ads/{connection_id}/report

The reporting surface itself is read-only. Campaigns, groups, ads, and creatives support write operations across the platforms that allow it, with the API returning 501 Not Implemented where a specific write isn't supported. Reporting does not.

Each result returned is an AdsReport object. At a high level, an AdsReport includes:

  • organization_id
  • start_at and end_at (the report's date range)
  • currency
  • metrics[] (an array containing the performance data)

Each metrics entry is { value, type }, where type is a normalized enum of 100+ KPIs (see the Report model). The vocabulary is consistent across providers. What varies is which KPIs a provider returns and the granularity (per-day, per-entity, or aggregate), so validate coverage against your target provider rather than assuming a fixed set.

Step 4: Know which report filters are supported

Reporting filters are provider-specific. Unified normalizes the endpoint, but not every provider supports the same query parameters.

Commonly supported filters

Across providers, Ads reports may support:

  • org_id
  • campaign_id
  • group_id
  • ad_id
  • start_gte
  • end_lt
  • limit
  • offset

Provider differences you must handle

  • Google Ads
    • Supports date filtering and entity filters
    • Supports a type parameter to request specific KPIs
  • Meta Ads
    • Supports date filtering
    • Adds updated_gte for incremental reads
  • TikTok Ads
    • Supports date filtering
    • Does not document KPI selection via type

Do not assume filter parity across providers. Always check supported list options before enabling a filter in your UI.

Step 5: Pull a baseline report

Here's a minimal, provider-safe example that pulls reports for a date range:

const reports = await sdk.ads.listAdsReports({
  connectionId: CONNECTION_ADS!,
  startGte: "2025-01-01",
  endLt: "2025-01-31",
  limit: 50,
});

The response is an array of AdsReport objects. Each report represents a scoped result set for the given filters.

Step 6 (Optional): Request a specific KPI type

Some providers support selecting a specific KPI via the type parameter (for example, Google Ads).

const reports = await sdk.ads.listAdsReports({
  connectionId: CONNECTION_ADS!,
  startGte: "2025-01-01",
  endLt: "2025-01-31",
  type: "CLICKS",
  limit: 50,
});

Unified documents supported KPI selectors (via the type parameter) for certain providers. Supported values are provider-specific and documented in the Advertising API blog and integration pages.

  • CLICKS
  • IMPRESSIONS
  • CTR
  • COST
  • CONVERSIONS
  • CPA
  • ROAS
  • This is a subset; the Report model has the full 100+ enum. Supported values are provider-specific.

If a provider does not support KPI selection, the type parameter may be ignored. Your application should handle this gracefully.

Step 7: Handle metrics safely

All performance data lives inside report.metrics.

What Unified does guarantee:

  • Metrics are returned as an array.
  • Currency is specified at the report level.
  • Metrics are scoped to the report's date range and filters.

What Unified does not guarantee:

  • Which KPI types a given provider returns (coverage varies).
  • Whether metrics are per-day, per-entity, or aggregated.
  • Whether monetary values use major or minor currency units.

For this reason:

  • Do not hardcode metric field names.
  • Do not compute derived metrics unless you control the inputs.
  • Treat metrics as provider-defined data that your analytics layer interprets.

Pagination and rate limits

Ads reports use offset-based pagination:

  • limit controls page size (typically capped at 100)
  • offset controls pagination

When you receive a 429 response, handle it with backoff and retry logic. Unified enforces both provider-level and platform-level rate limits. The SDK does not automatically retry for you.

Provider considerations you must handle

  • Reporting is list-based
    There is no explicit 'run report' operation. All reporting is driven by list filters.
  • Metrics coverage varies
    The KPI vocabulary is normalized; which metrics a provider returns is not. Validate coverage per provider.
  • Filter support varies
    Never assume a filter exists across all ad platforms.
  • Webhooks are limited
    Advertising webhooks exist for only a few platforms (Meta Ads, Google DV360, Snapchat, and TikTok Ads). Polling remains the primary change-detection mechanism for the rest.

To pull cross-platform ad performance reports with Unified:

  • Authenticate and obtain a valid Ads connectionId
  • Use GET /ads/{connection_id}/report with provider-safe filters
  • Scope reports by date range and entity IDs
  • Request KPI types where supported
  • Treat metrics as an opaque, provider-defined payload
  • Handle pagination and rate limits explicitly

→ Start your 30-day free trial

→ Book a demo

All articles