2025 Growth Unified Hits Major Growth Milestones with 6.5x usage & 4.5x revenue growth
Unified.to
All articles

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

January 16, 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. Ads, campaigns, and groups may support write operations depending on provider support, but 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)

Unified documents where metrics live, but does not publish a stable, spec-backed schema for their internal structure. The metrics array should be treated as an opaque payload that your application can inspect or pass through, not as a guaranteed schema.

This distinction matters. You should not assume daily rows, per-entity breakdowns, or specific metric field names unless you validate them against your target provider.

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

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 in public docs:

  • The exact fields inside each metrics entry.
  • 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 are opaque
    Unified normalizes access, not interpretation. Validate metric structure per provider.
  • Filter support varies
    Never assume a filter exists across all ad platforms.
  • Webhooks are limited
    Advertising webhooks are currently documented only for Meta Ads. Polling remains the primary reporting mechanism for other providers.

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