List Socialize campaigns

Outcome

List campaigns in one authorized Socialize workspace, optionally filtering by creator and status. Use the returned campaign ids to open individual campaigns.

Before you start

• Use the intended environment and the same verified organization throughout. This guide grants no access.
• Discover granted canonical Socialize workspaces through supported Auth/resource discovery. A brand uses the Auth workspace id; display names and provider account ids are not substitutes.
• Select resource context separately from action input. Application permission and workspace access are both required; organization ownership alone does not establish access.
• Published application permission: app_topolo_socialize.calendar:read.

Select the workspace

• Discover and select the intended existing Socialize workspace outside the input. This action has no brandId/workspaceId input field.
• When no resource is named, the source resolves the caller’s default workspace; explicitly named unknown/forbidden resources are denied rather than changed to another workspace.
• Use returned data[].id for campaigns.get. createdBy, when supplied, is an existing user id filter and never changes the original authenticated caller.

Request

GET /api/campaigns

The action input object maps to query parameters. Do not add a workspace id to it; resource selection is separate.

Pagination and response

• The reviewed handler returns {data,meta}, where meta.count equals data.length for this page. It is not the total result count.
• Omitted limit defaults to 50 in response metadata; omitted offset defaults to 0. Use integer limit 1–100 and non-negative integer offset.
• The status filter accepts draft, scheduled, active, completed and cancelled. Do not infer provider delivery from a campaign status.
• The catalogue output schema is deliberately structural and permits other carriers; this handler’s actual return shape is data array and meta object. Do not synthesize a nextCursor, page.hasMore or total.
• Use an explicit authorized workspace for reproducible scope. A different default workspace can return a different collection even with the same body.

Effects

• Workspace authorization can insert a missing local brands mirror or update its organization/status to active before returning. The source labels these actions read-only, but that is not a guarantee of zero storage writes. They do not create, schedule or publish a campaign/post.
• Queries campaigns only for the resolved brand; applies optional createdBy/status/limit/offset filters. No campaign or post is created, changed or published.

Worked examples

These are synthetic and unrun examples. Empty pages illustrate the carrier and pagination metadata without inventing live campaign records.

First page of draft campaigns

Request

{
  "status": "draft",
  "limit": 20,
  "offset": 0
}

Response illustration

{
  "data": [],
  "meta": {
    "count": 0,
    "limit": 20,
    "offset": 0
  }
}

This page contains zero matching campaigns in the resolved workspace. It is not a count of every campaign in the organization.

Continue at an explicit offset

Request

{
  "limit": 20,
  "offset": 20
}

Response illustration

{
  "data": [],
  "meta": {
    "count": 0,
    "limit": 20,
    "offset": 20
  }
}

The offset is a request position, not a cursor or stable snapshot. Concurrent changes can affect pagination; do not invent page.hasMore or a total count.

Errors and recovery

• 403 workspace_forbidden: Verify the exact selected workspace and existing grant. Unknown and inaccessible named brands share a denial; do not probe other ids or widen permission automatically.

The catalogue also declares generic authentication, permission, throttling, validation and dependency errors. Preserve actual status/body/request id; the reviewed route delegates ApplicationError serialization and does not establish a captured response body for those categories. Validate against the current action contract before a later authorized call.

No campaign-content rollback is needed for this read. Authorization can synchronize the local brand mirror; do not delete it as compensation. Preserve actual errors and context; any subsequent mutation needs its own authorization.

Change log

• 2026-10-21: Added workspace discovery, query constraints, offset pagination and synthetic response examples from reviewed source f8e30bad6947f868302f24e9cb31b6a2bdd1fbf6. Clarified page count versus total, structural catalogue precision and authorization mirror writes. No business call or provider test was run.

Source

Reviewed Socialize campaigns.ts, authenticatedRoutes.ts and brandAccess.ts at the pinned source revision, with a fresh credential-visible catalogue comparison. A source review is not proof of the currently deployed provider revision.