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

GET /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

curl \
  -H "Authorization: Bearer $HUMBLYTICS_API_KEY" \
  "https://app.humblytics.com/api/google-ads-connections?propertyId=PROPERTY_ID"

Sample Response

{
  "connections": [
    {
      "id": "4262a1be-916b-4b76-aacd-9338282a81b7",
      "propertyId": "PROPERTY_ID",
      "userId": null,
      "googleUserId": "112011105627800270926",
      "googleUserEmail": "[email protected]",
      "googleUserName": "Amir Mxt",
      "customerAccounts": [
        {
          "id": "9797820499",
          "name": "Humblytics",
          "currency": "CAD",
          "timezone": "America/Toronto",
          "isActive": true,
          "managerId": "2731478791"
        }
      ],
      "createdAt": "2026-04-11T03:29:54.170Z",
      "updatedAt": "2026-05-01T18:03:59.463Z",
      "lastSyncAt": "2026-05-01T18:03:59.463Z",
      "tokenExpiresAt": "2026-05-01T19:03:57.821Z",
      "syncState": { "status": "idle", "lastSyncDate": "2026-05-01", "rowCount": 9 }
    }
  ]
}

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

GET /google-ads-connections/{id}

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

Sample Request

curl \
  -H "Authorization: Bearer $HUMBLYTICS_API_KEY" \
  "https://app.humblytics.com/api/google-ads-connections/CONNECTION_ID"

---

List Campaigns for a Google Ads Customer Account

GET /google-ads-connections/{id}/campaigns

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

curl \
  -H "Authorization: Bearer $HUMBLYTICS_API_KEY" \
  "https://app.humblytics.com/api/google-ads-connections/CONNECTION_ID/campaigns?customerId=9797820499"

Sample Response

{
  "campaigns": [
    { "id": "23673402199", "name": "GADS_BRAND_Defense_2026Q1", "status": "ENABLED", "channelType": "SEARCH" },
    { "id": "23766900361", "name": "GADS_COMPETITOR_Conquest_2026Q2", "status": "ENABLED", "channelType": "SEARCH" },
    { "id": "23673402196", "name": "GADS_CORE_PainPoints_2026Q1", "status": "PAUSED", "channelType": "SEARCH" }
  ]
}

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

GET /meta-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

curl \
  -H "Authorization: Bearer $HUMBLYTICS_API_KEY" \
  "https://app.humblytics.com/api/meta-connections?propertyId=PROPERTY_ID"

Sample Response

{
  "connections": [
    {
      "id": "4a20c9a9-d027-4cab-9130-28c05d00e72c",
      "propertyId": "PROPERTY_ID",
      "userId": null,
      "metaUserId": "122096569802691382",
      "metaUserEmail": null,
      "metaUserName": "Humblytics System User",
      "adAccounts": [
        {
          "id": "act_1841530576550922",
          "name": "Humblytics Ads",
          "currency": "CAD",
          "timezone": "America/Toronto",
          "isActive": true
        }
      ],
      "createdAt": "2026-04-15T16:21:59.948Z",
      "updatedAt": "2026-04-15T16:21:59.948Z",
      "lastSyncAt": null,
      "tokenExpiresAt": null,
      "syncState": null
    }
  ]
}

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

GET /meta-connections/{id}

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

---

Connection Status

GET /meta-connections/{id}/status

Lightweight health check. Useful before running expensive insight queries.

Sample Response

{
  "status": "connected",
  "canRefresh": false,
  "tokenExpiresAt": null,
  "syncState": null
}

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

---

List All Campaigns Across the Connection

GET /meta-connections/{id}/campaigns

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

{
  "accounts": [
    {
      "accountId": "act_1841530576550922",
      "accountName": "Humblytics Ads",
      "campaigns": []
    }
  ]
}

---

List Campaigns for a Specific Ad Account (with Metrics)

GET /meta-connections/{id}/accounts/{accountId}/campaigns

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

curl \
  -H "Authorization: Bearer $HUMBLYTICS_API_KEY" \
  "https://app.humblytics.com/api/meta-connections/CONNECTION_ID/accounts/act_1841530576550922/campaigns?since=2026-04-01&until=2026-04-30"

---

Daily Insights for an Ad Account

GET /meta-connections/{id}/accounts/{accountId}/daily-insights

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

curl \
  -H "Authorization: Bearer $HUMBLYTICS_API_KEY" \
  "https://app.humblytics.com/api/meta-connections/CONNECTION_ID/accounts/act_1841530576550922/daily-insights?since=2026-04-01&until=2026-04-30"

Sample Response

{
  "account": {
    "id": "act_1841530576550922",
    "name": "Humblytics Ads",
    "currency": "CAD",
    "timezone": "America/Toronto"
  },
  "insights": []
}

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

GET /meta-connections/{id}/campaigns/{campaignId}/ads

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

curl \
  -H "Authorization: Bearer $HUMBLYTICS_API_KEY" \
  "https://app.humblytics.com/api/meta-connections/CONNECTION_ID/campaigns/CAMPAIGN_ID/ads"

---

Detailed Ad Creative

GET /meta-connections/{id}/ads/{adId}

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

curl \
  -H "Authorization: Bearer $HUMBLYTICS_API_KEY" \
  "https://app.humblytics.com/api/meta-connections/CONNECTION_ID/ads/AD_ID"

---

Related Endpoints

• 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.