---
title: "Retrieve Campaigns"
method: GET
path: "/v1/campaigns"
tags: ["Campaigns", "v1"]
---

# Retrieve Campaigns

`GET /v1/campaigns`

Retrieve the list of all campaigns available in the account. Use pagination to control the number of campaigns returned, and include related campaign data, campaign settings, list, or custom feed information when needed.

:::info
Requires the `campaigns:read` OAuth2 scope.
:::

## Query parameters

- `account_id` string, required
- `page[num]` integer
- `page[size]` integer
- `include` string

## Response `200`

Success

- object
  - `data` CampaignV1[], required
    - `type` 'campaign', required — The type of the object.
    - `id` string, required — The unique identifier for the campaign.
    - `attributes` object, required
      - `name` string, required — Human-readable name of the campaign.
      - `status` 'draft' | 'scheduled' | 'running' | 'paused' | 'stopped' | 'terminated' | 'ended', required — Lifecycle status of the campaign. - `draft` — campaign is still being configured. No delivery, no spend. Can be transitioned into `scheduled` / `running` once `can_be_started` is `true`. - `scheduled` — campaign is fully configured and queued; ads start delivering when `start_date` is reached. No spend yet. - `running` — campaign is actively serving ads and consuming budget. - `paused` — campaign was previously `scheduled` or `running` and has been paused by the user. Delivery is halted and no further budget is consumed; can be resumed back to `running`. - `stopped` — delivery is automatically halted by Leadfeeder because of an external blocker (most commonly an unresolved billing issue on the account). The campaign resumes automatically once the blocker is cleared; the user cannot transition out of this state directly. Surfaced both for campaigns whose underlying status is `stopped` and for campaigns that are technically `scheduled` while the account has a billing issue. - `terminated` — campaign was permanently stopped by the user before reaching `end_date`. Terminal state; cannot be resumed. - `ended` — campaign reached its scheduled `end_date` and completed naturally. Terminal state.
      - `start_date` string, date-time, required — Scheduled start datetime of the campaign. Always present — a campaign cannot be created without a start date. Caveat: if a campaign gets stuck in `scheduled` past its original start date (for example because of an unresolved billing issue on the account), `start_date` is updated in place to the date the campaign is unstuck and actually begins delivering. Treat this field as the campaign's effective start, not necessarily the originally-configured one.
      - `end_date` string, date-time, nullable, required — Scheduled end datetime of the campaign. `null` for open-ended campaigns. Otherwise set from the moment an end date is configured, regardless of the campaign's lifecycle status.
      - `location_type` 'global' | 'region' | 'country' | 'city', required — Geographical granularity of the campaign's targeting.
      - `budget_type` 'total' | 'daily', required — How the campaign's budget cap is applied.
      - `budget` number, required — Configured budget value, expressed in the smallest indivisible unit consistent with the campaign's `currency`. The meaning depends on `budget_type`: total spend cap for `total`, daily cap for `daily`.
      - `total_budget` number, required — Effective total spend cap for the campaign, in units of `currency`. For `budget_type=total` this equals `budget`; for `budget_type=daily` it is the daily budget multiplied by the scheduled run length.
      - `budget_spent` number, float, required — Amount already spent by the campaign, in units of `currency`.
      - `budget_left` number, float, required — Remaining budget headroom (`total_budget - budget_spent`), in units of `currency`. Never negative.
      - `currency` string, required — ISO 4217 currency code for all monetary fields on the campaign (`budget`, `total_budget`, `budget_spent`, `budget_left`). Not user-controllable: it is inherited from the subscription that was active at the moment the campaign was started. Leadfeeder's billing system is currency-agnostic and assumes every chargeable campaign on an account uses the same currency as the current subscription — campaigns are not run across multiple currencies.
      - `can_be_started` boolean, required — Whether the campaign currently passes all preflight checks required to transition out of `draft`. `false` indicates missing configuration (budget, audience, locations, …).
      - `targets_crm_open_opportunities` boolean, required — `true` when the campaign's audience list is the dynamic "CRM accounts with open opportunities" list.
      - `created_at` string, date-time, required — Datetime when the campaign was created.
      - `updated_at` string, date-time, required — Datetime when the campaign was last updated.
    - `relationships` object, required — Reference pointers to related resources. Each relationship carries `id` / `type` by default; when the matching value is requested through `include=`, the resource is inlined under the same key with its full `attributes` block.
      - `created_by` object, nullable, required — The user who created the campaign.
        - `id` string, required — The Leadfeeder user ID.
        - `type` string, required
      - `list` union, required — Audience list (target companies) backing the campaign. Inlined as a full `list` resource when `include=list` is set; otherwise an `id` / `type` reference.
        - object — Reference returned by default — `id` / `type` only, when `include=list` is not requested.
          - `id` string, required
          - `type` 'list', required
        - ListV1
          - `type` 'list', required — The type of the object
          - `id` string, required — The unique identifier for the list
          - `attributes` object, required
            - `name` string, required — The human-readable name of the List
            - `scope` 'company' | 'contact', required — The scope type of the list
            - `created_at` string, date-time, required — Date and time when the list was created
            - `updated_at` string, date-time — Date and time when the list was updated
          - `relationships` object, required
            - `created_by` object, required
              - …
      - `custom_feed` union, required — Custom website-visit feed used for retargeting. Inlined as a full `custom_feed` resource when `include=custom_feed` is set; otherwise an `id` / `type` reference.
        - object — Reference returned by default — `id` / `type` only, when `include=custom_feed` is not requested.
          - `id` string, required
          - `type` 'custom_feed', required
        - CustomFeedV1
          - `type` 'custom_feed', required — The type of the object
          - `id` string, required — The unique identifier for the custom feed.
          - `attributes` object, required
            - `name` string, required — Name of the custom feed.
            - `created_at` string, date-time, required — Datetime when the custom feed was created.
            - `updated_at` string, date-time, required — Datetime when the custom feed was last updated.
            - `deletable` boolean, required — Whether this custom feed can be deleted.
            - `viewable` boolean, required — Whether this custom feed can be viewed.
            - `notifications` union[], required — Notification subscriptions configured for this custom feed.
              - …
            - `advanced_filters` object, nullable — Advanced filters configuration for the custom feed. Returns null if no filters are configured.
              - …
          - `relationships` object, required
            - `created_by` object, nullable, required — The user who originally created the custom feed.
              - …
            - `folder` object, nullable
              - …
      - `campaign_settings` union, required — Campaign-level configuration toggles. Inlined as a full `campaign_settings` resource when `include=campaign_settings` is set; otherwise an `id` / `type` reference.
        - object — Reference returned by default — `id` / `type` only, when `include=campaign_settings` is not requested.
          - `id` string, required
          - `type` 'campaign_settings', required
        - CampaignSettingsV1
          - `type` 'campaign_settings', required — The type of the object.
          - `id` string — Identifier of the campaign settings resource. Matches the parent campaign's id.
          - `attributes` object, required
            - `brand_safety_domains_exclusion_enabled` boolean, required — When `true`, Leadfeeder's brand-safety domain exclusion list is applied to the campaign, preventing ad delivery on flagged domains.
            - `automatically_include_new_target_companies` boolean, required — When `true`, companies that newly enter the target audience list are automatically added to the campaign's active targets.
            - `automatically_remove_target_companies` boolean, required — When `true`, companies removed from the target audience list are automatically deactivated as campaign targets.
            - `ads_visible_only_on_weekdays` boolean, required — When `true`, ads served by the campaign are limited to Monday–Friday delivery windows.
      - `campaign_summary` union, required — Aggregated lifetime performance summary. Inlined as a full `campaign_summary` resource when `include=campaign_summary` is set; otherwise an `id` / `type` reference.
        - object — Reference returned by default — `id` / `type` only, when `include=campaign_summary` is not requested.
          - `id` string, required
          - `type` 'campaign_summary', required
        - CampaignSummaryV1
          - `type` 'campaign_summary', required — The type of the object.
          - `id` string — Identifier of the campaign summary resource. Matches the parent campaign's id.
          - `attributes` object, required
            - `clicks` integer, required — Total ad clicks recorded over the campaign lifetime.
            - `impressions` integer, required — Total ad impressions delivered over the campaign lifetime.
            - `targeted_count` integer, required — Number of companies currently targeted by the campaign.
            - `audience_count` integer, required — Size of the audience list backing the campaign.
            - `reached_count` integer, required — Distinct companies that received at least one impression.
            - `influenced_count` integer, required — Distinct companies attributed to the campaign through subsequent tracked engagement.
            - `visits_count` integer, required — Website visits attributed to the campaign.
            - `currency` string, required — ISO 4217 currency code in which monetary values are reported.
            - `ecpm` number, float, required — Effective cost per mille (per 1000 impressions).
            - `ecpc` number, float, required — Effective cost per click.
            - `ctr` number, float, required — Click-through rate (`clicks / impressions`) expressed as a decimal ratio. Multiply by 100 to convert to a percentage: `0.05` means 5%.
            - `total_cost` number, float, required — Total spend over the campaign lifetime.
            - `ecpv` number, float, required — Effective cost per attributed website visit.
            - `vtr` number, float, required — Visit-through rate (`visits_count / impressions`) expressed as a decimal ratio. Multiply by 100 to convert to a percentage: `0.01` means 1%.
            - `cost_per_company` number, float, required — Total cost divided by reached_count.
      - `campaign_locations` union[], required — Geographical targets attached to the campaign. Each item is inlined with its `attributes` when `include=campaign_locations` is set; otherwise each entry is an `id` / `type` reference only.
        - union
          - object — Reference returned by default — `id` / `type` only, when `include=campaign_locations` is not requested.
            - `id` string, required
            - `type` 'campaign_location', required
          - CampaignLocationV1
            - `type` 'campaign_location', required — The type of the object.
            - `id` string, required — Identifier of the campaign-location association.
            - `attributes` object, required
              - …
  - `meta` object, required
    - `pagination` object, required
      - `page_num` integer, required
      - `page_count` integer, required
      - `total_count` integer, required
    - `request_id` string, required — A unique identifier assigned to each API request for end-to-end traceability.

## Other responses

- `400` — Bad Request
- `401` — Unauthorized. The request was rejected because the credentials are missing, invalid, expired, or have been revoked. The client must re-authenticate before retrying. Clients can differentiate via the `code` value of the first item in `errors`.
- `403` — Forbidden. The credentials are valid but the caller is not authorized to perform the request — typically because the user lacks the required permission, the OAuth scope is insufficient, the subscription plan does not include the required entitlement, the `account_id` does not belong to the authenticated user, or the target list is read-only and its members cannot be modified. Clients can differentiate via the `code` value of the first item in `errors`.
- `429` — Too many requests. Either the per-second rate limit or the monthly quota configured for the API key / OAuth application has been exceeded. Clients can differentiate via the `code` value of the first item in `errors`.
- `500` — Internal server error
- `504` — Server timeout

---

[API](https://skmtc.net/leadfeeder/apis/leadfeeder-public-api.md) · [All operations](https://skmtc.net/leadfeeder/apis/leadfeeder-public-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/leadfeeder/leadfeeder-public-api/revisions/9e2e63ba2a4e/schema)