Join Buffer’s first Build Contest. October 28 - November 13

Register
API Status Get API Key

Posts & Scheduling

Posts are the core content type in Buffer. Here's how they work, from creation through delivery.

What is a post?

A post is a piece of content scheduled or published through Buffer. Every post belongs to a specific channel (a connected social media profile) and goes through a lifecycle from creation to delivery.

Key fields on a post:

  • id - unique identifier
  • text - the post content
  • channelId - which channel this post belongs to
  • dueAt - when the post is scheduled to publish
  • status - current lifecycle state (scheduled, sent, etc.)
  • assets - attached images or media

Scheduling types

When creating a post, you choose how it should be scheduled:

addToQueue

We'll add the post to the next available time slot from your posting schedule. This is the simplest option.

mutation {
  createPost(
    input: {
      text: "Automatically scheduled post"
      channelId: "your_channel_id"
      schedulingType: automatic
      mode: addToQueue
    }
  ) {
    ... on PostActionSuccess {
      post {
        id
        dueAt
      }
    }
    ... on MutationError {
      message
    }
  }
}

customScheduled

You specify an exact date and time using the dueAt field in ISO 8601 format (UTC):

mutation {
  createPost(
    input: {
      text: "Scheduled for a specific time"
      channelId: "your_channel_id"
      schedulingType: automatic
      mode: customScheduled
      dueAt: "2026-03-10T15:00:00.000Z"
    }
  ) {
    ... on PostActionSuccess {
      post {
        id
        dueAt
      }
    }
    ... on MutationError {
      message
    }
  }
}

Post status lifecycle

A post moves through the following states:

  • Scheduled the post is in the queue, waiting for its dueAt time
  • Sent the post was successfully published to the social platform
  • Error the post could not be published (e.g., the channel was disconnected)

Creating posts

Use the createPost mutation. Required fields:

  • text - the post content
  • channelId - the target channel
  • schedulingType - how to schedule (automatic)

Always include both PostActionSuccess and MutationError in your response:

mutation {
  createPost(
    input: {
      text: "Hello from the API"
      channelId: "your_channel_id"
      schedulingType: automatic
      mode: addToQueue
    }
  ) {
    ... on PostActionSuccess {
      post {
        id
        text
        dueAt
        assets {
          id
          mimeType
        }
      }
    }
    ... on MutationError {
      message
    }
  }
}

See Create a Text Post and Create an Image Post for complete examples.

Channel-specific configuration

Beyond the shared fields above, the API supports channel-specific configuration through the metadata field on createPost. Each network has its own metadata input, so you can do things like create a thread on X (Twitter), Bluesky, Threads, or Mastodon, add a first comment on LinkedIn, Facebook, or Instagram, set the post type (post, story, reel) on Instagram, or attach a board to a Pinterest pin. You only need to provide the metadata for the network the channel belongs to. To learn more about the available configurations for each network, see the PostInputMetaData reference.

A few options are configured on the assets themselves rather than in the network metadata. For example, Instagram user tags are positioned per image via image.metadata.userTags - see Create an Instagram Post with User Tags for a complete example.

Retrieving posts

Query posts for a specific organization, filtered by channel and status:

query {
  posts(
    first: 20
    input: {
      organizationId: "your_org_id"
      filter: { status: [sent], channelIds: ["your_channel_id"] }
    }
  ) {
    edges {
      node {
        id
        text
        dueAt
        channelId
      }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

Posts are returned using cursor-based pagination. Use first and after to page through results.

See Get Posts for Channels and Get Paginated Posts for more examples.

Buffer keeps sent and failed posts for two years. After two years, a post and the media attached to it are permanently deleted, and the posts query no longer returns it. Drafts and scheduled posts are not affected. Deleting a post from Buffer does not remove it from the social network it was published to. If you need a longer history, save your own copy of the posts you want to keep.

Metrics

Once a post is sent, the network reports performance data — reactions, impressions, reach, and so on. Buffer normalizes those values across networks and exposes them on Post.metrics. Reading metrics is available for personal workflows and automations only, using a personal API key.

See Post Metrics for the full guide and Get Post Metrics for a single-post query.

Supported platforms

The API can create posts for the following platforms:

  • Instagram
  • Threads
  • LinkedIn
  • X (Twitter)
  • Facebook
  • Google Business Profiles
  • Mastodon
  • YouTube
  • Pinterest
  • Bluesky
  • TikTok
  • Substack

The service field on a Channel tells you which platform it's connected to.

Next steps