> For the complete documentation index, see [llms.txt](https://docs.humblytics.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.humblytics.com/ads-connections-api.md).

# Ads Connections API

The Ads Connections API exposes read-only access to Google Ads and Meta Ads accounts connected through the Humblytics dashboard. Use it to inspect connected accounts, pull campaign metadata, and fetch daily insights.

> **Base URL**: `https://app.humblytics.com/api`
>
> Note: these endpoints sit under `/api`, **not** `/api/external/v1` like the [External Analytics API](https://docs.humblytics.com/external-analytics-api.md) or `/api/v1` like the [Ads Attribution API](https://docs.humblytics.com/ads-attribution-api.md). All three bases accept the same Bearer API key.

### Authentication

Same API key as the rest of the public API. Create one on the **Agents** page (`/agent`, **API keys** tab). Account keys work for every site you own; a property key only returns connections for its own site.

```http
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 these endpoints return data, the user must connect the relevant account in the Humblytics dashboard at **Connectors → Google Ads** or **Connectors → Meta 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

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

#### Sample Response

```json
{
  "connections": [
    {
      "id": "4262a1be-916b-4b76-aacd-9338282a81b7",
      "propertyId": "PROPERTY_ID",
      "userId": null,
      "googleUserId": "112011105627800270926",
      "googleUserEmail": "amir@humblytics.com",
      "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

```bash
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

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

#### Sample Response

```json
{
  "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](https://docs.humblytics.com/ads-attribution-api.md) — 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

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

#### Sample Response

```json
{
  "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

```json
{
  "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

```json
{
  "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

```bash
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

```bash
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

```json
{
  "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

```bash
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

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

***

### Related Endpoints

* [Ads Attribution API](https://docs.humblytics.com/ads-attribution-api.md) — 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](https://docs.humblytics.com/external-analytics-api.md) — UTM-based traffic and form data; pair with these endpoints for campaigns where ad-platform attribution is incomplete.
* [Connectors](https://docs.humblytics.com/connectors.md) — how to set up the live Meta Ads connection and check connector availability.
