# 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](/external-analytics-api.md) or `/api/v1` like the [Ads Attribution API](/ads-attribution-api.md). 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.

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

```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](/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](/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](/external-analytics-api.md) — UTM-based traffic and form data; pair with these endpoints for campaigns where ad-platform attribution is incomplete.
* [Connectors](/connectors.md) — how to set up Meta and Google Ads connections in the dashboard.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.humblytics.com/ads-connections-api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.