List campaigns - Ocoya API Docs

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}.

GET

https://www.app.ocoya.com/api/_public/v1/campaigns

List campaigns

cURL

curl --request GET \
  --url https://www.app.ocoya.com/api/_public/v1/campaigns \
  --header 'X-API-Key: <api-key>'

{
  "total": 12,
  "page": 0,
  "perPage": 20,
  "data": [
    {
      "id": "cmayxcmpn00087aps2m7hjs9z",
      "type": "social",
      "name": "Summer launch campaign",
      "prompt": "Summer launch campaign for our ecommerce analytics dashboard.",
      "goal": "launch",
      "status": "GENERATED",
      "duration": 7,
      "startDate": "2026-11-02",
      "postsPerDay": 1,
      "plannedPostCount": 7,
      "postCount": 7,
      "postLength": "medium",
      "channelIds": [
        "clh49poxf008x8kov4ncbjty9"
      ],
      "generation": {
        "status": "GENERATING",
        "phase": "posts",
        "current": 3,
        "total": 7,
        "completed": 2,
        "failed": 0,
        "error": "<string>",
        "startedAt": "2024-01-01T00:00:00Z",
        "updatedAt": "2024-01-01T00:00:00Z",
        "completedAt": "2024-01-01T00:00:00Z"
      },
      "createdAt": "2024-01-01T00:00:00Z",
      "updatedAt": "2024-01-01T00:00:00Z"
    }
  ]
}

Authorizations

X-API-Keystringheaderrequired

Your API key. Create one in Ocoya. Authorization: Bearer <key> works too.

Query Parameters

brandIdstringrequired

Ocoya brand ID. Get one from GET /brands.

Example:"cmayvq3hk00017apshay5qezu"

statusenum<string>

Only campaigns with this status.

Available options: GENERATING, GENERATED, SCHEDULED, ERROR

Example:"GENERATED"

pageinteger

Zero-based page number for paginated results.

Example:0

perPageinteger

Campaigns per page, up to 100. Defaults to 20.

Required range: 1 <= x <= 100

Example:20

Response

200application/json

Success

totalinteger

Campaigns matching the filter.

Example:12

pageinteger

This page, from 0.

Example:0

perPageinteger

Campaigns per page.

Example:20

dataobject[]

This page of campaigns, newest first.

Show child attributesHide child attributes

data.idstring

Campaign ID.

Example:"cmayxcmpn00087aps2m7hjs9z"

data.typeenum<string>

Kind of campaign: social posts, blog articles, or an email (internal for now).

Available options: social, blog, email

Example:"social"

data.namestring

The campaign's name in the app: its prompt, or Untitled campaign.

Example:"Summer launch campaign"

data.promptstring

The brief the campaign was generated from.

Example:

"Summer launch campaign for our ecommerce analytics dashboard."

data.goalstring | null

Campaign objective, when one was set.

Example:"launch"

data.statusenum<string>

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.

Available options: GENERATING, GENERATED, SCHEDULED, ERROR

Example:"GENERATED"

data.durationinteger | null

Campaign length in days.

Example:7

data.startDatestring | null

Day of the first post, YYYY-MM-DD, when one was set.

Example:"2026-11-02"

data.postsPerDaynumber | null

Posting frequency, when one was set: 0.5 is every other day.

Example:1

data.plannedPostCountinteger | null

Posts the campaign was asked for.

Example:7

data.postCountinteger

Posts generated so far.

Example:7

data.postLengthstring | null

Caption length the posts were written at.

Example:"medium"

data.channelIdsstring[]

Channels the campaign posts to.

Example:

[
  "clh49poxf008x8kov4ncbjty9"
]

data.generationobject | null

Generation progress. null for a campaign made before progress was recorded.

Show child attributesHide child attributes

data.generation.statusstring

GENERATING while posts are being written, then GENERATED, or ERROR when every post failed.

Example:"GENERATING"

data.generation.phasestring

Step of the generation: queued, posts, complete or error.

Example:"posts"

data.generation.currentinteger

Post being written, from 1.

Example:3

data.generation.totalinteger

Posts to write.

Example:7

data.generation.completedinteger

Posts written so far.

Example:2

data.generation.failedinteger

Posts that could not be written.

Example:0

data.generation.errorstring

Why generation failed, when it did.

data.generation.startedAtstring