---
title: "List campaigns with filtering, sorting, and cursor pagination"
method: GET
path: "/campaigns"
tags: ["Campaigns"]
---

# List campaigns with filtering, sorting, and cursor pagination

`GET /campaigns`

## Request

- Base URL: `https://api.omnisend.com/api`
- URL: `https://api.omnisend.com/api/campaigns`
- Auth: one of:
  - OAuth 2
    - Client credentials
    - Token URL: `https://app.omnisend.com/oauth2/token` scopes: `campaigns.read`
  - API key in header `Authorization`

List campaigns with filtering, sorting, and cursor-based pagination.

**Scopes:**
`campaigns.read`

**Rate Limiting:**
This endpoint is rate limited to 400 requests per minute.

**Filtering & sorting:**
Supported query parameters: `nameContains`, `status`, `channel`, `type`, `parentCampaignID`, `createdAtFrom`/`createdAtTo`, `updatedAtFrom`/`updatedAtTo`, `sort`, `direction`, `limit`, `after`, `before`, `view`, `include`. Only these documented parameters are accepted; any unknown parameter returns 400.
- `sort` accepts `createdAt`, `updatedAt`, or `name`; `direction` (`asc`/`desc`) is only valid together with `sort`.

**Response shape:**
Items are always `CampaignDTO`. With `view=summary` the heavy sections `content` and `abTest` are omitted from every item unless requested with `include`; all other fields are unchanged. `include` has no effect without `view=summary`.

**Pagination:**
This endpoint uses cursor-based pagination.
- Use the `paging.cursors.after` value from the response to get the next page
- Use the `paging.cursors.before` value to get the previous page
- The `paging.hasMore` field indicates if more results are available
- Maximum page size is 250 items. Default: 100
- Do not send `after` and `before` together, and keep filters and sorting unchanged while paginating with a cursor

## Query parameters

- `limit` integer
- `after` string
- `before` string
- `sort` 'createdAt' | 'updatedAt' | 'name'
- `direction` 'asc' | 'desc'
- `status` string[]
- `nameContains` string
- `channel` string[]
- `type` 'regular' | 'booster' | 'abTest'
- `parentCampaignID` string
- `createdAtFrom` string, date-time
- `createdAtTo` string, date-time
- `updatedAtFrom` string, date-time
- `updatedAtTo` string, date-time
- `view` 'summary'
- `include` string[]

## Headers

- `Omnisend-Version` string, required

## Response `200`

List of campaigns with pagination

- CampaignsResponse: Paginated list of campaigns
  - `campaigns` Campaign[]: List of campaigns
    - `abTest` ABTest: A/B test configuration. Variants are keyed by "a" and "b"; the parent campaign's `content` field is omitted because variants carry their own content. `result` is populated once a winner is selected and is `null` otherwise.
      - `result` ABTestResult: A/B test result (read-only).
        - `isManuallySelected` boolean: Whether the winner was manually selected (read-only)
        - `selectedAt` string: When the winner was selected (read-only)
        - `winnerVariantID` string: Campaign ID of the winning variant (read-only). Matches variants.a.id or variants.b.id.
      - `settings` ABTestSettings: A/B test settings.
        - `decisionTime` ABTestDecisionTime: Decision time before selecting a winner. Same shape as booster delay.
          - `amount` integer: Amount of time units to wait
          - `unit` 'h' | 'd': Time unit: "h" for hours, "d" for days
        - `testSizePercent` integer: Percentage of audience for the test phase (10-100)
        - `winningMetric` 'openRate' | 'clickRate': Winner determination metric
      - `variants` ABTestVariants: A/B test variants object with keys "a" and "b".
        - `a` ABTestVariant: A/B test variant. Email-specific fields live under `content.email`.
          - `content` ABTestVariantContent: A/B test variant content grouped by channel.
            - `email` ABTestVariantEmail: Email content fields for an A/B test variant.
              - …
          - `id` string: Variant campaign ID (read-only). Used for reporting API access.
        - `b` ABTestVariant: A/B test variant. Email-specific fields live under `content.email`.
          - `content` ABTestVariantContent: A/B test variant content grouped by channel.
            - `email` ABTestVariantEmail: Email content fields for an A/B test variant.
              - …
          - `id` string: Variant campaign ID (read-only). Used for reporting API access.
    - `audience` Audience: Campaign audience
      - `excludedCountries` string[]: Countries excluded from the SMS audience, as ISO 3166-1 alpha-2 codes (e.g. "US"). Only applicable to SMS campaigns. Recipients in these countries are not sent to.
      - `excludedSegmentIDs` string[]: Segments to exclude from the audience
      - `includedSegmentIDs` string[]: Segments to include. Empty includes all subscribers
    - `boosterSettings` BoosterSettings: Booster-specific settings.
      - `campaignID` string, required: Parent campaign ID this booster follows up on
      - `delay` BoosterDelay: Delay between the parent campaign send and the booster send.
        - `amount` integer: Amount of time units before the booster is sent
        - `unit` 'h' | 'd': Time unit: "h" for hours, "d" for days
      - `sendTo` 'nonOpeners' | 'nonClickers', required: Audience selector. The booster targets recipients of the parent who did NOT perform the implied action (`nonOpeners` did not open; `nonClickers` did not click).
    - `brandID` string: Brand unique identifier (read-only)
    - `channel` 'email' | 'push' | 'sms': Campaign message channel
    - `content` Content: Campaign content
      - `email` Email: Email content
        - `contentID` string: Email content unique identifier referencing the campaign's email design
        - `preheader` string: Email preheader text displayed after the subject line in the recipient's inbox
        - `replyToEmail` string: Reply-to email address for recipient responses
        - `senderEmail` string: Sender email address shown in the recipient's inbox
        - `senderName` string: Sender display name shown in the recipient's inbox
        - `subject` string: Email subject line displayed in the recipient's inbox
      - `sms` SMS: SMS message content
        - `compliance` SMSCompliance: SMS compliance text settings
          - `stopKeywordText` string: STOP keyword text for US/CA recipients. Max 250 chars
          - `unsubscribeLinkText` string: Unsubscribe link text for non-US/CA recipients. Max 250 chars
        - `imageID` string: Image ID obtained from the Images API. When set, the message is delivered as MMS to US/CA recipients; other countries receive SMS without the image. Image must be JPEG, JPG, PNG, or GIF and not exceed 500 KB
        - `isLinkShorteningEnabled` boolean: Auto-shorten links in message body
        - `message` string: SMS message body. When sent as SMS, the message (including the appended compliance text and unsubscribe link/keyword) must not exceed 9 SMS segments for either US/CA or other-country recipients. When sent as MMS, the message (including the appended compliance text) must not exceed 1600 characters for US/CA recipients.
        - `senderName` string: Sender display name. Max 250 chars
    - `createdAt` string: Campaign creation timestamp (read-only)
    - `endedAt` string: Campaign end timestamp (read-only)
    - `id` string: Campaign unique identifier (read-only)
    - `language` string: Campaign language locale in xx_XX format
    - `name` string: Campaign name
    - `sendingSettings` SendingSettings: Campaign sending settings
      - `isTZOptimizationEnabled` boolean: Whether timezone optimization is enabled. Only available with immediate or scheduled strategy, and only in email campaigns
      - `optimizeFor` 'opens' | 'clicks' | 'orders': Optimization objective for personalized sends. Present when strategy is personalized
      - `respectQuietHours` boolean: Whether personalized sends avoid contact-local hours from 22:00 through 06:59
      - `scheduledAt` string: Scheduled send time in RFC 3339 format. Present when strategy is scheduled or personalized
      - `strategy` 'immediate' | 'scheduled' | 'personalized': Sending strategy
    - `startedAt` string: Campaign start timestamp (read-only)
    - `status` 'draft' | 'scheduled' | 'started' | 'sent' | 'error' | 'canceled' | 'paused' | 'onHold' | 'expired' | 'stopped': Campaign status
    - `type` 'regular' | 'abTest' | 'booster': Campaign type
    - `updatedAt` string: Campaign last update timestamp (read-only)
    - `url` string: Link to the campaign in the Omnisend app (read-only): the settings page of a draft campaign (for a booster, the parent campaign's booster page) or the report of a started, sent, canceled, stopped or expired campaign. Omitted for scheduled, paused, on-hold and error campaigns.
  - `paging` PagingResponse: Cursor-based pagination metadata
    - `cursors` CursorsResponse: Cursor pointers for paginating forward and backward through results
      - `after` string, nullable: Opaque cursor for fetching the next page of results
      - `before` string, nullable: Opaque cursor for fetching the previous page of results
    - `hasMore` boolean: Whether there are more items available beyond the current page
    - `limit` integer: Maximum number of items returned per page

## Other responses

- `400`: Request contains invalid or missing fields
- `401`: Authentication is missing or invalid
- `403`: Insufficient permissions for this operation
- `410`: API version has been retired
- `429`: Rate limit exceeded
- `500`: Unexpected error occurred

---

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