---
title: "List ad campaigns"
method: GET
path: "/campaigns/ads/"
tags: ["campaigns"]
---

# List ad campaigns

`GET /campaigns/ads/`

## Request

- Base URL: `https://api.hive.co/v2`
- URL: `https://api.hive.co/v2/campaigns/ads/`
- Auth: HTTP bearer

Published Meta ad campaigns for the authorized brand, most recently created first. All performance figures are Meta-reported, served from Hive's cached stats. `stats` is only present when requested with `stats=true`; compare `stats_refreshed_at` to avoid re-fetching unchanged stats.

## Query parameters

- `limit` integer
- `offset` integer
- `stats` boolean

## Headers

- `X-Partner-Id` string, required

## Response `200`

- PaginatedAdsCampaigns
  - `offset` integer, required
  - `limit` integer, required
  - `total_items` integer, required
  - `items` AdsCampaignWithStats[], required
    - `id` string, required
    - `name` string, required
    - `status` string, required
    - `objective` string, required
    - `start_time` string, date-time, nullable, required
    - `stop_time` string, date-time, nullable, required
    - `budget_cents` integer, nullable, required
    - `budget_type` string, nullable, required
    - `stats_refreshed_at` string, date-time, nullable, required
    - `stats` AdsCampaignStats: Versioned view over the cached Meta lifetime insights — the raw insights blob is never passed through. All figures are Meta-reported; ads have no Hive-attributed revenue sections (unlike email and SMS).
      - `spend` number, double
      - `impressions` integer
      - `reach` integer
      - `frequency` number, double
      - `clicks` integer
      - `unique_clicks` integer
      - `cost_per_click` number, double
      - `cost_per_unique_click` number, double
      - `click_through_rate` number, double
      - `results` integer
      - `cost_per_result` number, double
      - `meta_purchase_value` number, double
      - `meta_purchase_roas` number, double

## Other responses

- `422`: The request was rejected on its query parameters. Field errors are keyed by parameter name, rejections on the parameter values (e.g. an unknown ID) use a flat `errors` list.

---

[API](https://skmtc.dev/hive-co/apis/hive-api.md) - [All operations](https://skmtc.dev/hive-co/apis/hive-api/llms.txt) - [OpenAPI document](https://skmtc.dev/hive-co/apis/hive-api/revisions/aa145f089347?raw)