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

# List campaigns

`GET /campaigns`

## Request

- Base URL: `https://www.app.ocoya.com/api/_public/v1`
- URL: `https://www.app.ocoya.com/api/_public/v1/campaigns`
- Auth: API key in header `X-API-Key`

Returns a brand's AI campaigns, newest first, with each one's status and generation progress. Read one with its posts with `GET /campaigns/{campaignId}`.

## Query parameters

- `brandId` string, required
- `status` 'GENERATING' | 'GENERATED' | 'SCHEDULED' | 'ERROR'
- `page` integer
- `perPage` integer

## Response `200`

Success

- object
  - `total` integer, required: Campaigns matching the filter.
  - `page` integer, required: This page, from 0.
  - `perPage` integer, required: Campaigns per page.
  - `data` object[], required: This page of campaigns, newest first.
    - `id` string, required: Campaign ID.
    - `type` 'social' | 'blog' | 'email', required: Kind of campaign: social posts, blog articles, or an email (internal for now).
    - `name` string, required: The campaign's name in the app: its prompt, or `Untitled campaign`.
    - `prompt` string, required: The brief the campaign was generated from.
    - `goal` string, nullable, required: Campaign objective, when one was set.
    - `status` 'GENERATING' | 'GENERATED' | 'SCHEDULED' | 'ERROR', required: `GENERATING` while posts are being written, `GENERATED` when they are ready to review, `SCHEDULED` once the campaign runs (shown as Running in the app), `ERROR` when generation failed.
    - `duration` integer, nullable, required: Campaign length in days.
    - `startDate` string, nullable, required: Day of the first post, `YYYY-MM-DD`, when one was set.
    - `postsPerDay` number, nullable, required: Posting frequency, when one was set: `0.5` is every other day.
    - `plannedPostCount` integer, nullable, required: Posts the campaign was asked for.
    - `postCount` integer, required: Posts generated so far.
    - `postLength` string, nullable, required: Caption length the posts were written at.
    - `channelIds` string[], required: Channels the campaign posts to.
    - `generation` object, nullable, required: Generation progress. `null` for a campaign made before progress was recorded.
      - `status` string, required: `GENERATING` while posts are being written, then `GENERATED`, or `ERROR` when every post failed.
      - `phase` string, required: Step of the generation: `queued`, `posts`, `complete` or `error`.
      - `current` integer: Post being written, from 1.
      - `total` integer: Posts to write.
      - `completed` integer: Posts written so far.
      - `failed` integer: Posts that could not be written.
      - `error` string: Why generation failed, when it did.
      - `startedAt` string
      - `updatedAt` string
      - `completedAt` string
    - `createdAt` string, required: When the campaign was created.
    - `updatedAt` string, required: When the campaign last changed.

## Other responses

- `400`: Unknown status.
- `401`: Missing or invalid API key.
- `403`: Invalid brand id, or the API key's user does not own this brand.
- `429`: Rate limit exceeded: 60 requests per minute per API key.
- `500`: Unknown error

## Changes

- **2026-11-04** `ef9bd3530850`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/ocoya/apis/ocoya-api/changes/campaigns/get.md)

---

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