Read and manage posts

Use client.posts to read and manage posts.

List posts

const page = await client.posts.list({
  limit: 25,
  status: "scheduled",
});

if (page.nextCursor) {
  const nextPage = await client.posts.list({
    cursor: page.nextCursor,
    limit: 25,
    status: "scheduled",
  });
}

Treat nextCursor as opaque text. Keep the same filters when you request the next page.

Check a plan

const result = await client.posts.check({
  content: {
    mode: "shared",
    text: "A safe release update.",
    destinations: [{ channelId }],
  },
  publication: { state: "draft" },
});

if (!result.ready) {
  console.log(result.issues);
}

The check does not create a post, queue work, contact a provider, or use an approval.

Use current tokens

Get the post before a command:

const post = await client.posts.get(postId);
const channel = post.channels.find((item) => item.channelId === channelId);

if (!channel) throw new Error("Channel is not on this post.");

Use post.editToken for an edit. Use channel.controlToken for reschedule, cancel, or retry. Each successful command returns a new token.

Edit

const edited = await client.posts.edit(
  postId,
  {
    confirmed: true,
    content: {
      segments: [{ blocks: [{ type: "text", text: "Updated copy." }] }],
    },
    editToken: post.editToken,
  },
  { idempotencyKey: crypto.randomUUID() },
);

Reschedule

const result = await client.posts.reschedule(
  postId,
  {
    channelId,
    confirmed: true,
    controlToken: channel.controlToken,
    publishAt: "2026-09-04T16:00:00.000Z",
  },
  { idempotencyKey: crypto.randomUUID() },
);

Cancel

await client.posts.cancel(
  postId,
  {
    channelId,
    confirmed: true,
    controlToken: channel.controlToken,
  },
  { idempotencyKey: crypto.randomUUID() },
);

Retry a failed destination

if (channel.status === "failed") {
  await client.posts.retry(
    postId,
    {
      channelId,
      confirmed: true,
      controlToken: channel.controlToken,
      publishAt: "2026-09-04T16:05:00.000Z",
    },
    { idempotencyKey: crypto.randomUUID() },
  );
}

Beacon rejects retry for publishing, checking, delayed, reconnect_required, partially_published, and published results. The SDK does not retry writes automatically.