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

# List campaigns

`GET /v1/campaigns`

## Request

- Base URL: `https://api.mailbeast.ai`
- URL: `https://api.mailbeast.ai/v1/campaigns`
- Auth: HTTP bearer

Cursor-paginate the workspace campaigns (id, name, status, lead count), newest-first and stable under concurrent changes.

Requires one of the following scopes: `campaigns:read`, `campaigns:all`, `all:read`, `all:all`.

## Query parameters

- `cursor` string
- `limit` integer
- `status` 'draft' | 'scheduled' | 'active' | 'paused' | 'stopped' | 'completed' | 'failed'
- `tags` string

## Response `200`

- CampaignListApiResponseDto
  - `data` CampaignListItemApiDto[], required
    - `id` string, uuid, required
    - `name` string, required
    - `status` 'draft' | 'scheduled' | 'active' | 'paused' | 'stopped' | 'completed' | 'failed', required
    - `leadsCount` number, required
    - `tags` TagApiDto[], required: Tags on this campaign. Create and delete them in the dashboard - here they are read, and you can filter the list by them with `?tags=`. Campaign tags are a separate dictionary from mailbox tags, so the ids do not cross over.
      - `id` string, uuid, required
      - `name` string, required
      - `color` string, nullable, required: Hex colour shown in the dashboard.
    - `createdAt` string, date-time, required
  - `meta` CampaignListMetaDto, required
    - `hasMore` boolean, required: Whether more campaigns are available after this page.
    - `nextCursor` string, nullable: Pass as `?cursor=` to fetch the next page; null when `hasMore` is false.

## Other responses

- `400`: The request body or parameters failed validation.
- `401`: Missing or invalid API key.
- `403`: The key lacks a required scope, or the plan does not include API access.
- `429`: Rate limit exceeded - retry after the interval in the Retry-After header.

---

[API](https://skmtc.dev/mailbeast/apis/mailbeast-public-api.md) · [All operations](https://skmtc.dev/mailbeast/apis/mailbeast-public-api/llms.txt) · [OpenAPI document](https://skmtc.dev/mailbeast/apis/mailbeast-public-api/revisions/6440ce0738a4?raw)