Ads Connections API

Ads Connections API

The Ads Connections API exposes read-only access to the Meta Ads and Google Ads accounts your property has connected via the Humblytics dashboard. Use it to list connections, inspect connected ad accounts, pull campaign metadata, and fetch daily insights — all without setting up your own Meta App Review or Google Ads developer token.

Base URL: https://app.humblytics.com/api

Note: these endpoints sit under /api, not /api/external/v1 like the External Analytics API or /api/v1 like the Ads Attribution API. All three bases accept the same property-scoped Bearer API key.

Authentication

Same property-scoped API key as the rest of the public API. Generate one at Utilities → API in the dashboard.

Authorization: Bearer <your_api_key>

Read-only by design

These endpoints expose GETs only. Connecting, refreshing, and disconnecting ad accounts is done through the Connectors page in the dashboard — not via the API. If you need to programmatically manage (not just read) Meta or Google Ads campaigns, use the official Meta CLI or Google Ads API directly with your own credentials. Never route production ad-platform traffic through an unapproved Meta developer app — that is the documented pattern Meta is actively banning, regardless of how the access token was issued.

Prerequisites

Before any of these endpoints return data, the user must connect the relevant ad account(s) in the Humblytics dashboard at Connectors → Meta Ads or Connectors → Google Ads. Empty connections arrays mean nothing is connected for that property.


Google Ads

List Google Ads Connections

Lists all Google Ads connections for a property.

Query Parameters

Name
Type
Required
Notes

propertyId

string

Yes

The property to scope to.

Sample Request

Sample Response

Notes

  • customerAccounts[].id is the customerId you'll need for the /campaigns endpoint below.

  • tokenExpiresAt past now does not mean the connection is broken — Humblytics handles token refresh server-side.

  • syncState.status can be idle, syncing, or error.


Get a Single Google Ads Connection

Returns a single connection by ID. Same shape as one entry in the list response above.

Sample Request


List Campaigns for a Google Ads Customer Account

Lists campaigns for a specific Google Ads customer account.

Query Parameters

Name
Type
Required
Notes

customerId

string

Yes

Google Ads customer account ID. Get this from customerAccounts[].id in the connection response.

Sample Request

Sample Response

Notes

  • status is one of ENABLED, PAUSED, REMOVED.

  • channelType mirrors Google's value (SEARCH, DISPLAY, SHOPPING, VIDEO, PERFORMANCE_MAX, DEMAND_GEN).

  • For revenue-attached performance metrics (spend, ROAS, conversions), use the Ads Attribution API — it joins this campaign data with on-site session and revenue data.


Meta Ads

List Meta Ads Connections

Lists all Meta Ads connections for a property.

Query Parameters

Name
Type
Required
Notes

propertyId

string

Yes

The property to scope to.

Sample Request

Sample Response

Notes

  • adAccounts[].id is the accountId you'll need for account-scoped endpoints below. It includes the act_ prefix.

  • Meta connections are typically system-user-based (metaUserName: "Humblytics System User"), so tokenExpiresAt is often null (no expiry).


Get a Single Meta Connection

Returns a single connection by ID. Same shape as one entry in the list response above.


Connection Status

Lightweight health check. Useful before running expensive insight queries.

Sample Response

status values: "connected", "expired", "error".


List All Campaigns Across the Connection

Returns campaigns grouped by ad account, across every account on the connection. Use this when you need a "show me everything" view; use the per-account endpoint below when you need performance metrics.

Sample Response


List Campaigns for a Specific Ad Account (with Metrics)

Returns campaigns for one ad account, including performance metrics for the requested date range (when supplied).

Query Parameters

Name
Type
Required
Notes

since

string

No

Start date (ISO date, YYYY-MM-DD).

until

string

No

End date (ISO date, YYYY-MM-DD).

If since/until are omitted, returns campaigns without performance metrics attached.

Sample Request


Daily Insights for an Ad Account

Day-by-day campaign performance breakdown for a specific ad account. The primary endpoint for spend reconciliation.

Query Parameters

Name
Type
Required
Notes

since

string

Yes

Start date (YYYY-MM-DD).

until

string

Yes

End date (YYYY-MM-DD).

Sample Request

Sample Response

insights is empty when no spend ran in the date range. When data exists, each row includes per-day campaign-level spend, impressions, clicks, and conversion metrics from Meta's Insights API.


List Ads Within a Campaign

Returns the ads inside a campaign — creative metadata, destination URLs, and ad-level performance (when applicable). Use this for creative inspection workflows ("which ads are driving spend without revenue?").

Sample Request


Detailed Ad Creative

Full creative metadata for a single ad — image/video URLs, copy variations, landing URL, status. Pair with the campaign-level endpoint above to drill into specific creative.

Sample Request


  • Ads Attribution API — joins this connector data with on-site session and revenue data for full-funnel ROAS reporting. This is what you want for "which campaigns are paying back?" rather than raw spend.

  • External Analytics API — UTM-based traffic and form data; pair with these endpoints for campaigns where ad-platform attribution is incomplete.

  • Connectors — how to set up Meta and Google Ads connections in the dashboard.

Last updated