Buffer
App · Social Media · 20 actions
Schedule, publish and manage social media posts across Instagram, Facebook, LinkedIn, X, Threads, Bluesky, Pinterest, TikTok, YouTube and more with Buffer: queue, schedule or draft posts with images and video, read and reorder the queue, track posting limits and post metrics, and manage ideas and tags.
Actions
| Action | What it does |
|---|---|
| Create idea | Save an idea to an organization's Ideas board, with a title, text, images, the networks it is meant for, a target date and a group. |
| Create post | Create a post on one channel: add it to the queue, put it at the top, publish it now, schedule it for a time, or save it as a draft. |
| Create tag | Create a tag in an organization. |
| Delete post | Delete a post from Buffer. |
| Delete tag | Delete a tag. |
| Edit post | Change a post's text, schedule, tags or media, or move it to drafts. |
| Get account | Read the Buffer account the API key belongs to: its id, email, name, avatar, timezone and when it was created. |
| Get channel | Read one channel: its network, name, timezone and posting schedule, and for a Pinterest channel its boards. |
| Get daily posting limits | For each channel, how many posts are scheduled and sent on a day against the network's daily cap, and whether the cap is reached. |
| Get post | Read one post: its text, status, times, channel, tags, media and any publishing error, plus its performance metrics once it has been sent (Buffer updates them about once a day). |
| Get post metrics summary | Totals across the posts sent between two dates (both included, up to a year): post count, reactions, comments and whatever else the networks report, optionally narrowed to some channels or tags. |
| Get tag | Read one tag: its name, colour and whether it is locked. |
| List channels | List the social accounts (channels) connected to an organization: network, name, timezone, posting schedule, and whether each is locked, disconnected or has its queue paused. |
| List idea groups | List the groups (columns) on an organization's Ideas board. |
| List ideas | List the ideas on an organization's Ideas board, optionally only those in some groups, in any group or in none, or carrying some tags. |
| List organizations | List every Buffer organization the account belongs to, with its owner, how many channels it has, and its plan limits on channels, ideas, idea groups, scheduled posts and tags. |
| List posts | List an organization's posts, filtered by channel, status, post type, tag, scheduled time and creation time, and sorted by scheduled or creation time. |
| List tags | List an organization's tags, sorted by name, with each one's colour and whether it is locked. |
| Move post in queue | Move a queued post to the top or the bottom of its channel's queue, which changes when it publishes. |
| Update tag | Rename or recolour a tag. |
Create idea
Save an idea to an organization's Ideas board, with a title, text, images, the networks it is meant for, a target date and a group.
Inputs
- Organization
organization_idtextRequired - The Buffer organization to work in.
- Title
titletext - The idea's headline.
- Text
texttext - The idea itself.
- Networks
networkslist - The networks the idea is meant for.One or more of:
bluesky,facebook,googlebusiness(Google Business Profile),instagram,linkedin,mastodon,pinterest,substack,threads,tiktok,twitter(X (Twitter)),youtube. - Target date
planned_fordate and time - When you plan to publish it.
- Image URLs
image_urlslist - Public links to images to keep with the idea.
- Group
group_idtext - The Ideas board group to put it in.
Outputs
ideaobject- The idea
Example output
{
"idea": {
"content": {
"aiAssisted": false,
"date": null,
"media": [],
"services": [
"instagram"
],
"tags": [],
"text": "A day in the studio.",
"title": "Behind the scenes"
},
"createdAt": 1760000000,
"groupId": null,
"id": "6650a0b1c2d3e4f5a6b7c8dd",
"organizationId": "6650a0b1c2d3e4f5a6b7c8d9",
"position": 1.0,
"updatedAt": 1760000000
}
}Create post
Create a post on one channel: add it to the queue, put it at the top, publish it now, schedule it for a time, or save it as a draft. Attach images or a video by public link, add tags, and set network options such as a first comment, a link preview, the Instagram or Facebook post type, the Pinterest board, or the YouTube title and category.
Inputs
- Channel
channel_idtextRequired - The connected social account (channel) to use.
- Text
texttext - What the post says.
- When to publish
modetext - Add to the channel's queue (its next free time slot), put it at the top of the queue, publish it now, or schedule it for a specific time.One of:
addToQueue(Add to the queue),shareNext(Share next (top of the queue)),shareNow(Share now),customScheduled(Schedule for a specific time). - Scheduled time
due_atdate and time - When to publish the post.Only when When to publish is Schedule for a specific time.
- Save as a draft
save_to_drafttrue/false - Turn on to keep the post as a draft: it is saved in Buffer but not published or queued.
- Publishing
scheduling_typetext - Publish automatically, or have Buffer send you a reminder to post it yourself from the Buffer app.One of:
automatic(Publish automatically),notification(Remind me to publish it by hand). - Tags
tag_idslist - Tags to put on the post.
- Image URLs
image_urlslist - Public links to the images to attach. Buffer downloads them, so each must open directly in a browser without signing in.
- Image description (alt text)
image_alt_texttext - Describes the images for people using screen readers.
- Video URL
video_urltext - A public link to one video to attach instead of images. It must open directly in a browser without signing in.
- Link
link_urltext - A link shown as a preview card on Bluesky, Facebook, LinkedIn and Threads (only on a post without images or video), or the pin's destination on Pinterest.
- First comment
first_commenttext - A comment Buffer adds right after publishing. Instagram, Facebook and LinkedIn only.
- Post type
network_post_typetext - Instagram and Facebook only: a feed post, a reel or a story.One of:
post,reel,story. - Pinterest board
pinterest_board_idtext - Pinterest only, and required there: the board to pin to.
- Title
titletext - The pin title on Pinterest, or the video title on YouTube (required there).
- YouTube category
youtube_categorytext - YouTube only, and required there: the video's category.One of:
1(Film & Animation),2(Autos & Vehicles),10(Music),15(Pets & Animals),17(Sports),19(Travel & Events),20(Gaming),22(People & Blogs),23(Comedy),24(Entertainment), and 5 more. - YouTube privacy
youtube_privacytext - YouTube only. Defaults to public.One of:
public,unlisted,private.
Outputs
postobject- The post
Example output
{
"post": {
"assets": [],
"author": {
"email": "sam@example.com",
"name": "Sam Rivera"
},
"channelId": "6650a0b1c2d3e4f5a6b7c8da",
"channelService": "linkedin",
"createdAt": "2026-10-09T09:12:44.000Z",
"dueAt": "2026-10-12T14:00:00.000Z",
"error": null,
"externalLink": null,
"id": "6650a0b1c2d3e4f5a6b7c8db",
"ideaId": null,
"isCustomScheduled": false,
"schedulingType": "automatic",
"sentAt": null,
"shareMode": "addToQueue",
"sharedNow": false,
"status": "scheduled",
"tags": [
{
"color": "#2C4BFF",
"id": "6650a0b1c2d3e4f5a6b7c8dc",
"name": "Launch"
}
],
"text": "Our autumn collection is live.",
"updatedAt": "2026-10-09T09:12:44.000Z",
"via": "api"
}
}Create tag
Create a tag in an organization. Names are unique per organization; the Free plan allows 3 tags.
Inputs
- Organization
organization_idtextRequired - The Buffer organization to work in.
- Name
nametextRequired - Up to 100 characters, unique in the organization (capitals count).
- Colour
colortextRequired - A hex colour of six digits.
Outputs
tagobject- The tag
Example output
{
"tag": {
"color": "#2C4BFF",
"colorName": "blue",
"id": "6650a0b1c2d3e4f5a6b7c8dc",
"isLocked": false,
"name": "Launch"
}
}Delete post
Delete a post from Buffer. A post already published stays on the social network. This cannot be undone.
Inputs
- Post ID
post_idtextRequired - The post's id, from 'List posts' or 'Create post'. A Buffer link containing the id works too.
Outputs
deletedtrue/false- Always true once deleted
idtext- The id of what was deleted
Example output
{
"deleted": true,
"id": "6650a0b1c2d3e4f5a6b7c8db"
}Delete tag
Delete a tag. It is removed from every post and idea carrying it. This cannot be undone.
Inputs
- Tag
tag_idtextRequired - The tag to use.
Outputs
deletedtrue/false- Always true once deleted
idtext- The id of what was deleted
Example output
{
"deleted": true,
"id": "6650a0b1c2d3e4f5a6b7c8dc"
}Edit post
Change a post's text, schedule, tags or media, or move it to drafts. Only the fields filled in are changed.
Inputs
- Post ID
post_idtextRequired - The post's id, from 'List posts' or 'Create post'. A Buffer link containing the id works too.
- New text
texttext - Replaces the post's text. Leave empty to keep it.
- Reschedule
modetext - Change when the post publishes. Leave empty to keep it.One of:
addToQueue(Add to the queue),shareNext(Share next (top of the queue)),shareNow(Share now),customScheduled(Schedule for a specific time). - Scheduled time
due_atdate and time - When to publish the post.Only when Reschedule is Schedule for a specific time.
- Move to drafts
save_to_drafttrue/false - Turn on to make the post a draft, so it does not publish.
- Tags
tag_idslist - Replaces the post's tags. Leave empty to keep them.
- Image URLs
image_urlslist - Replaces the post's media with these public image links. Leave empty to keep the current media.
- Image description (alt text)
image_alt_texttext - Describes the images for people using screen readers.
- Video URL
video_urltext - Replaces the post's media with this public video link. Leave empty to keep the current media.
Outputs
postobject- The post
Example output
{
"post": {
"assets": [],
"author": {
"email": "sam@example.com",
"name": "Sam Rivera"
},
"channelId": "6650a0b1c2d3e4f5a6b7c8da",
"channelService": "linkedin",
"createdAt": "2026-10-09T09:12:44.000Z",
"dueAt": "2026-10-12T14:00:00.000Z",
"error": null,
"externalLink": null,
"id": "6650a0b1c2d3e4f5a6b7c8db",
"ideaId": null,
"isCustomScheduled": false,
"schedulingType": "automatic",
"sentAt": null,
"shareMode": "addToQueue",
"sharedNow": false,
"status": "scheduled",
"tags": [
{
"color": "#2C4BFF",
"id": "6650a0b1c2d3e4f5a6b7c8dc",
"name": "Launch"
}
],
"text": "Our autumn collection is live.",
"updatedAt": "2026-10-09T09:12:44.000Z",
"via": "api"
}
}Get account
Read the Buffer account the API key belongs to: its id, email, name, avatar, timezone and when it was created.
Inputs
None.
Outputs
accountobject- The Buffer account
Example output
{
"account": {
"avatar": "https://example.com/sam.png",
"createdAt": "2024-02-01T09:00:00.000Z",
"email": "sam@example.com",
"id": "6650a0b1c2d3e4f5a6b7c8d0",
"name": "Sam Rivera",
"timezone": "Europe/London"
}
}Get channel
Read one channel: its network, name, timezone and posting schedule, and for a Pinterest channel its boards.
Inputs
- Channel
channel_idtextRequired - The connected social account (channel) to use.
Outputs
channelobject- The channel
warningslist- Present only when Buffer answered but left some fields out, with Buffer's reason for each
Example output
{
"channel": {
"avatar": "https://example.com/avatar.png",
"createdAt": "2026-01-05T10:00:00.000Z",
"descriptor": "LinkedIn Page",
"displayName": "Acme Inc",
"externalLink": "https://www.linkedin.com/company/acme",
"id": "6650a0b1c2d3e4f5a6b7c8da",
"isDisconnected": false,
"isLocked": false,
"isQueuePaused": false,
"metadata": null,
"name": "acme",
"organizationId": "6650a0b1c2d3e4f5a6b7c8d9",
"postingSchedule": [
{
"day": "mon",
"paused": false,
"times": [
"09:00",
"14:00"
]
}
],
"service": "linkedin",
"serviceId": "12345678",
"timezone": "Europe/London",
"type": "page",
"updatedAt": "2026-10-01T10:00:00.000Z"
}
}Get daily posting limits
For each channel, how many posts are scheduled and sent on a day against the network's daily cap, and whether the cap is reached.
Inputs
- Channels
channel_idslistRequired - The channels to check. They must all be in the same organization.
- Date
daydate - The day to check. Leave empty for today.
Outputs
countnumber- How many
limitslist- One entry per channel; 'limit' is empty when there is no cap
warningslist- Present only when Buffer answered but left some fields out, with Buffer's reason for each
Example output
{
"count": 1,
"limits": [
{
"channelId": "6650a0b1c2d3e4f5a6b7c8da",
"isAtLimit": false,
"limit": 25,
"scheduled": 2,
"sent": 1
}
]
}Get post
Read one post: its text, status, times, channel, tags, media and any publishing error, plus its performance metrics once it has been sent (Buffer updates them about once a day).
Inputs
- Post ID
post_idtextRequired - The post's id, from 'List posts' or 'Create post'. A Buffer link containing the id works too.
Outputs
postobject- The post
warningslist- Present only when Buffer answered but left some fields out, with Buffer's reason for each
Example output
{
"post": {
"assets": [],
"author": {
"email": "sam@example.com",
"name": "Sam Rivera"
},
"channelId": "6650a0b1c2d3e4f5a6b7c8da",
"channelService": "linkedin",
"createdAt": "2026-10-09T09:12:44.000Z",
"dueAt": "2026-10-12T14:00:00.000Z",
"error": null,
"externalLink": null,
"id": "6650a0b1c2d3e4f5a6b7c8db",
"ideaId": null,
"isCustomScheduled": false,
"metrics": null,
"metricsUpdatedAt": null,
"schedulingType": "automatic",
"sentAt": null,
"shareMode": "addToQueue",
"sharedNow": false,
"status": "scheduled",
"tags": [
{
"color": "#2C4BFF",
"id": "6650a0b1c2d3e4f5a6b7c8dc",
"name": "Launch"
}
],
"text": "Our autumn collection is live.",
"updatedAt": "2026-10-09T09:12:44.000Z",
"via": "api"
}
}Get post metrics summary
Totals across the posts sent between two dates (both included, up to a year): post count, reactions, comments and whatever else the networks report, optionally narrowed to some channels or tags.
Inputs
- Organization
organization_idtextRequired - The Buffer organization to work in.
- From
start_datedateRequired - The first day to include.
- To
end_datedateRequired - The last day to include.
- Channels
channel_idslist - Only count these channels. Leave empty for all.
- Tags
tag_idslist - Only count posts carrying any of these tags.
Outputs
end_datetext- Last day counted
metricslist- Each metric
metrics_updated_attext- When Buffer last refreshed the numbers
start_datetext- First day counted
totalsobject- Each metric's value keyed by its type
warningslist- Present only when Buffer answered but left some fields out, with Buffer's reason for each
Example output
{
"end_date": "2026-09-30",
"metrics": [
{
"description": "Posts sent in the period",
"name": "Posts",
"type": "postCount",
"unit": "count",
"value": 12.0
},
{
"description": "Likes and other reactions",
"name": "Reactions",
"type": "reactions",
"unit": "count",
"value": 340.0
}
],
"metrics_updated_at": "2026-10-09T03:00:00.000Z",
"start_date": "2026-09-01",
"totals": {
"postCount": 12.0,
"reactions": 340.0
}
}Get tag
Read one tag: its name, colour and whether it is locked.
Inputs
- Tag
tag_idtextRequired - The tag to use.
Outputs
tagobject- The tag
warningslist- Present only when Buffer answered but left some fields out, with Buffer's reason for each
Example output
{
"tag": {
"color": "#2C4BFF",
"colorName": "blue",
"id": "6650a0b1c2d3e4f5a6b7c8dc",
"isLocked": false,
"name": "Launch"
}
}List channels
List the social accounts (channels) connected to an organization: network, name, timezone, posting schedule, and whether each is locked, disconnected or has its queue paused.
Inputs
- Organization
organization_idtextRequired - The Buffer organization to work in.
- Locked
lockedtext - Buffer locks what is over the plan's limit after a downgrade. Leave empty to include everything.One of:
unlocked(Only unlocked),locked(Only locked).
Outputs
channelslist- The channels
countnumber- How many
warningslist- Present only when Buffer answered but left some fields out, with Buffer's reason for each
Example output
{
"channels": [
{
"avatar": "https://example.com/avatar.png",
"createdAt": "2026-01-05T10:00:00.000Z",
"descriptor": "LinkedIn Page",
"displayName": "Acme Inc",
"externalLink": "https://www.linkedin.com/company/acme",
"id": "6650a0b1c2d3e4f5a6b7c8da",
"isDisconnected": false,
"isLocked": false,
"isQueuePaused": false,
"name": "acme",
"organizationId": "6650a0b1c2d3e4f5a6b7c8d9",
"postingSchedule": [
{
"day": "mon",
"paused": false,
"times": [
"09:00",
"14:00"
]
}
],
"service": "linkedin",
"serviceId": "12345678",
"timezone": "Europe/London",
"type": "page",
"updatedAt": "2026-10-01T10:00:00.000Z"
}
],
"count": 1
}List idea groups
List the groups (columns) on an organization's Ideas board.
Inputs
- Organization
organization_idtextRequired - The Buffer organization to work in.
Outputs
countnumber- How many
idea_groupslist- The groups
warningslist- Present only when Buffer answered but left some fields out, with Buffer's reason for each
Example output
{
"count": 1,
"idea_groups": [
{
"id": "6650a0b1c2d3e4f5a6b7c8de",
"isLocked": false,
"name": "Q4"
}
]
}List ideas
List the ideas on an organization's Ideas board, optionally only those in some groups, in any group or in none, or carrying some tags.
Inputs
- Organization
organization_idtextRequired - The Buffer organization to work in.
- Groups
group_idslist - Only ideas in these groups.
- Grouped or not
groupingtext - Only ideas in some group, or in none. Use this or Groups, not both.One of:
grouped(Only ideas in a group),ungrouped(Only ideas in no group). - Tags
tag_idslist - Only ideas carrying any of these tags.
- Number of results
limitnumber - How many to return, 1-100. Defaults to 20.From 1 to 100. Default:
20. - Continue from
cursortext - The 'next_cursor' a previous run returned, to read the next page. Keep the other filters the same.
Outputs
countnumber- Records on this page
has_moretrue/false- Whether a page follows
ideaslist- The ideas
next_cursortext- Pass back as 'cursor' to read the next page
warningslist- Present only when Buffer answered but left some fields out, with Buffer's reason for each
Example output
{
"count": 1,
"has_more": false,
"ideas": [
{
"content": {
"aiAssisted": false,
"date": null,
"media": [],
"services": [
"instagram"
],
"tags": [],
"text": "A day in the studio.",
"title": "Behind the scenes"
},
"createdAt": 1760000000,
"groupId": null,
"id": "6650a0b1c2d3e4f5a6b7c8dd",
"organizationId": "6650a0b1c2d3e4f5a6b7c8d9",
"position": 1.0,
"updatedAt": 1760000000
}
],
"next_cursor": null
}List organizations
List every Buffer organization the account belongs to, with its owner, how many channels it has, and its plan limits on channels, ideas, idea groups, scheduled posts and tags.
Inputs
None.
Outputs
countnumber- How many
organizationslist- The organizations
warningslist- Present only when Buffer answered but left some fields out, with Buffer's reason for each
Example output
{
"count": 1,
"organizations": [
{
"channelCount": 3,
"id": "6650a0b1c2d3e4f5a6b7c8d9",
"limits": {
"channels": 3,
"ideaGroups": 3,
"ideas": 100,
"scheduledPosts": 10,
"tags": 3
},
"name": "Acme",
"ownerEmail": "sam@example.com"
}
]
}List posts
List an organization's posts, filtered by channel, status, post type, tag, scheduled time and creation time, and sorted by scheduled or creation time. Returns each post's text, status, times, channel, tags, media and any publishing error, a page at a time.
Inputs
- Organization
organization_idtextRequired - The Buffer organization to work in.
- Channels
channel_idslist - Only include these channels. Leave empty for all of them.
- Statuses
statuseslist - Only include posts in these states.One or more of:
draft,scheduled,sending,sent,error(Failed),needs_approval(Awaiting approval). - Post types
post_typeslist - Only include these kinds of post.One or more of:
post,reel,short,story,event(Event (Google Business)),offer(Offer (Google Business)),whats_new(What's new (Google Business)),ghost_post(Ghost post). - Tags
tag_idslist - Only include posts carrying any of these tags.
- Scheduled on or after
due_afterdate and time - Only posts scheduled at or after this time.
- Scheduled on or before
due_beforedate and time - Only posts scheduled at or before this time.
- Created on or after
created_afterdate and time - Only posts created at or after this time.
- Created on or before
created_beforedate and time - Only posts created at or before this time.
- Scheduled time
due_presencetext - Only posts that have, or have no, scheduled time.One of:
present(Has a scheduled time),absent(Has no scheduled time). - Sort by
sort_fieldtext - What to order the posts by. Defaults to scheduled time.One of:
dueAt(Scheduled time),createdAt(Created time). - Sort direction
sort_directiontext - Which way to order them. Defaults to newest first.One of:
desc(Newest first),asc(Oldest first). - Number of results
limitnumber - How many to return, 1-100. Defaults to 20.From 1 to 100. Default:
20. - Continue from
cursortext - The 'next_cursor' a previous run returned, to read the next page. Keep the other filters the same.
Outputs
countnumber- Records on this page
has_moretrue/false- Whether a page follows
next_cursortext- Pass back as 'cursor' to read the next page
postslist- The posts
warningslist- Present only when Buffer answered but left some fields out, with Buffer's reason for each
Example output
{
"count": 1,
"has_more": false,
"next_cursor": null,
"posts": [
{
"assets": [],
"author": {
"email": "sam@example.com",
"name": "Sam Rivera"
},
"channelId": "6650a0b1c2d3e4f5a6b7c8da",
"channelService": "linkedin",
"createdAt": "2026-10-09T09:12:44.000Z",
"dueAt": "2026-10-12T14:00:00.000Z",
"error": null,
"externalLink": null,
"id": "6650a0b1c2d3e4f5a6b7c8db",
"ideaId": null,
"isCustomScheduled": false,
"schedulingType": "automatic",
"sentAt": null,
"shareMode": "addToQueue",
"sharedNow": false,
"status": "scheduled",
"tags": [
{
"color": "#2C4BFF",
"id": "6650a0b1c2d3e4f5a6b7c8dc",
"name": "Launch"
}
],
"text": "Our autumn collection is live.",
"updatedAt": "2026-10-09T09:12:44.000Z",
"via": "api"
}
]
}List tags
List an organization's tags, sorted by name, with each one's colour and whether it is locked.
Inputs
- Organization
organization_idtextRequired - The Buffer organization to work in.
- Locked
lockedtext - Buffer locks what is over the plan's limit after a downgrade. Leave empty to include everything.One of:
unlocked(Only unlocked),locked(Only locked). - Number of results
limitnumber - How many to return, 1-100. Defaults to 20.From 1 to 100. Default:
20. - Continue from
cursortext - The 'next_cursor' a previous run returned, to read the next page. Keep the other filters the same.
Outputs
countnumber- Records on this page
has_moretrue/false- Whether a page follows
next_cursortext- Pass back as 'cursor' to read the next page
tagslist- The tags
total_countnumber- Tags in the organization
warningslist- Present only when Buffer answered but left some fields out, with Buffer's reason for each
Example output
{
"count": 1,
"has_more": false,
"next_cursor": null,
"tags": [
{
"color": "#2C4BFF",
"colorName": "blue",
"id": "6650a0b1c2d3e4f5a6b7c8dc",
"isLocked": false,
"name": "Launch"
}
],
"total_count": 1
}Move post in queue
Move a queued post to the top or the bottom of its channel's queue, which changes when it publishes.
Inputs
- Post ID
post_idtextRequired - The post's id, from 'List posts' or 'Create post'. A Buffer link containing the id works too.
- Move to
positiontextRequired - Where in the queue to put the post.One of:
top(Top of the queue),bottom(Bottom of the queue). Default:top.
Outputs
postobject- The post and its new time
Example output
{
"post": {
"dueAt": "2026-10-10T09:00:00.000Z",
"id": "6650a0b1c2d3e4f5a6b7c8db",
"status": "scheduled"
}
}Update tag
Rename or recolour a tag. Whichever is left empty keeps its current value.
Inputs
- Tag
tag_idtextRequired - The tag to use.
- New name
nametext - Leave empty to keep the current name.
- New colour
colortext - A hex colour of six digits. Leave empty to keep the current colour.
Outputs
tagobject- The tag
Example output
{
"tag": {
"color": "#2C4BFF",
"colorName": "blue",
"id": "6650a0b1c2d3e4f5a6b7c8dc",
"isLocked": false,
"name": "Launch"
}
}