---
title: "Get a campaign"
method: GET
path: "/campaigns/{campaignId}"
tags: ["Campaigns"]
---

# Get a campaign

`GET /campaigns/{campaignId}`

## Request

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

Returns one campaign with its brief, status, generation progress and posts. Each saved post has a `postGroupId` you can use with the post endpoints.

## Path parameters

- `campaignId` string, required

## Query parameters

- `brandId` string, required

## Response `200`

Success

- object
  - `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.
  - `posts` object[], required: The campaign's posts, in order.
    - `sequence` integer, required: Position in the campaign, from 1.
    - `title` string, nullable, required: Title, for a blog article.
    - `captionPreview` string, required: The caption, cut to 280 characters.
    - `scheduledAt` string, nullable, required: When the post is planned or scheduled to publish.
    - `approved` boolean, required: Whether the post was approved in the campaign review.
    - `postGroupId` string, nullable, required: The saved post, once the campaign has saved it. Read it in full with `GET /post/{postId}`. `null` until then.
    - `status` 'GENERATING' | 'DRAFT' | 'PENDING_CLIENT_APPROVAL' | 'PENDING_INTERNAL_APPROVAL' | 'SCHEDULED' | 'POSTED' | 'NEEDS_ATTENTION' | 'ERROR', nullable, required: Status of the saved post. `null` while it is not saved yet.
    - `mediaCount` integer, required: Images or videos on the post.

## Other responses

- `401`: Missing or invalid API key.
- `403`: Invalid brand id, or the API key's user does not own this brand.
- `404`: The brand has no campaign with this ID.
- `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/:campaignId/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)