Buffer API
Account
Queries 1
Retrieves the authenticated user's account information
Example Response
{
"data": {
"account": {
"id": "...",
"email": "...",
"backupEmail": "...",
"avatar": "..."
}
}
}Outputs 1
Account is a representation of a Buffer user.
Fields 10
id : ID!
Unique identifier for the account
email : String!
Primary email address for the account
backupEmail : String
Backup email address for account recovery
avatar : String!
URL to the account's avatar image
createdAt : DateTime
Date the account was created in the Core DB. For older customers, it's possible a Publish account existed in the Publish DB for this customer before this date
organizations (filter: OrganizationFilterInput) : [Organization!]!
timezone : String
The account-level timezone - this is used as a default input for streaks, posting plans, and new channel channel connections.
name : String
The account name, different from the organization name
preferences : Preferences
The accounts preferences
connectedApps : [ConnectedApp!]
The connected apps for the account
Types 2
Connected App
Fields 6
clientId : ID!
The id of the connectedApp.
userId : ID!
The id of the user that has granted access to the app.
name : String!
The name of the connected app.
description : String!
A brief description of the connected app.
website : String!
The website URL of the connected app.
createdAt : DateTime!
The date and time when the connected app was created.
Account preferences
Fields 3
defaultScheduleOption : ScheduleOption!
Enums 1
Scalars 2
The `AccountId` scalar represents the MongoDB ObjectId of a Buffer Account
The `DateTime` scalar represents a date and time following the ISO 8601 standard.
Channels
Queries 2
Fetches a single channel using the provided ID
Arguments
| Name | Type | Description |
|---|---|---|
| input Required | ChannelInput! | Query's input. |
Example Response
{
"data": {
"channel": {
"id": "...",
"allowedActions": [
"backfillChannel"
],
"scopes": [
"..."
],
"avatar": "..."
}
}
}Fetch all channels for the organization taking into account the current's user permissions
Arguments
| Name | Type | Description |
|---|---|---|
| input Required | ChannelsInput! | Query's input. |
Example Response
{
"data": {
"channels": [
{
"id": "...",
"allowedActions": [
"backfillChannel"
],
"scopes": [
"..."
],
"avatar": "..."
}
]
}
}Outputs 1
Channel entity
Fields 27
id : ChannelId!
The ID of the channel
allowedActions : [ChannelAction!]!
The allowed actions for the current user
scopes : [String]!
Scopes requested for a given channel - empty array if we don't have them tracked
avatar : String!
The avatar URL of the channel
createdAt : DateTime!
The creation date of the channel
descriptor : String!
Formatted name of the channel service and type: e.g. 'Twitter Profile' or 'Facebook Page'
displayName : String
The display name of the channel - nullable (reason?)
isDisconnected : Boolean!
Indicates if the channel is properly connected to Buffer
isLocked : Boolean!
Indicates if the channel is locked - Locked channels can't be used for posting. A channel can be locked when the organization downgrades and reduces the channel quantity of their plan.
isNew : Boolean!
Indicates if the channel was recently created (in less than 10 seconds). This is used to determine the redirect modal after channel authorization
postingSchedule : [ScheduleV2!]!
Provides the posting slots for each day of the week
isQueuePaused : Boolean!
Indicates is the queue is paused for the channel. A paused queue means schedules posts won't be published.
showTrendingTopicSuggestions : Boolean!
Indicates if trending topic suggestions should be shown in the composer. When false, users can still access trends via the trending icon button. Defaults to true for backward compatibility.
metadata : ChannelMetadata
Metadata or settings depending on the service type - such as the server URL for Mastodon or Location data for Facebook/GPB
name : String!
The name of the channel - the handle name, username, etc.
organizationId : OrganizationId!
The organization ID of the channel
products : [Product!]
Products that support a given channel
service : Service!
Represents the social network
serviceId : String!
Represents the external ID of the channel on social network API
timezone : String!
The timezone of the channel - Default if not set is Europe/London
type : ChannelType!
The type of the channel - Page, Profile, Business, Group, Account, etc.
updatedAt : DateTime!
The last time the channel was updated
hasActiveMemberDevice : Boolean!
Whether at least one member of the orginization who have access to this channel also has a user device registered for push notifications
postingGoal : PostingGoal
The posting goal for the channel
externalLink : String
The channel's URL on the social network (e.g. instagram.com/username or facebook.com/page) Returns null if the channel is not supported
linkShortening : ChannelLinkShortening!
Link Shortening settings for the channel
weeklyPostingLimit : WeeklyPostingLimit
Weekly posting limit for the channel
Types 17
Settings for link shortening
Fields 2
config : LinkShorteningConfig
Configuration of link shortening integration. Null if disabled.
isEnabled : Boolean!
If link shortening is enabled for the channel
Link Shortening Configuration
Fields 2
domain : String!
Domain of the link shortener - eg buff.ly, dub.co, or the user's custom domain.
name : String!
Human readable string to describe the link shortening service.
Location data about the channel
Fields 3
location : String
Location of the business associated with the channel
mapsLink : String
Link to the map
googleAccountId : String
Google Account Id of the business
A Pinterest board
Fields 6
id : String!
The ID of the board
serviceId : String!
The ID of the service
name : String!
The board name
url : String!
The board URL
description : String
The board description
avatar : String
The board avatar
Posting schedule for a specific day of the week
Fields 3
day : DayOfWeek!
The day of the week: mon, tue, wed, thu, fri, sat, sun
times : [String!]!
The times the channel is scheduled to post on the day: HH:MM
paused : Boolean!
Indicates if this day is paused in the posting schedule.
Inputs 5
Input for the channel query
Fields 1
id : ChannelId!
The ID of the channel to be retrieved
Filter to pass when fetching channels.
Fields 2
isLocked : Boolean
If not defined, it returns all channels Else, if true, it only returns locked channels if false, it only returns not locked channels
product : Product
If not passed, it return all channels Else, it filters the channels based on what the product supports.
Input to pass when fetching channels.
Fields 2
organizationId : OrganizationId!
The Organization id to fetch channels for
filter : ChannelsFiltersInput
A list of option filters - passing null means we don't want to filter
Enums 6
List of possible actions that can be performed on a Channel
Channel is a representation of a social media account or page that can be connected to Buffer.
Buffer products, buffer is used as all products
The list of services that can be authorized.
Scalars 1
The `ChannelId` scalar represents the MongoDB ObjectId of a Buffer Channel
Posts
Queries 4
Aggregate normalized post metrics across a filtered post set. Useful for yearly summaries, channel-level rollups, and BI exports without paginating through thousands of posts.
For per-post metrics, use posts(input) or post(input) with a
metrics { … } selection — this query is purely for aggregation.
The result always contains a baseline trio of entries: postCount
(number of matched posts in the window), reactions, and comments.
Posts on networks that don't track reactions or comments contribute 0
to those totals.
Beyond the baseline, additional metric types are returned only when every channel in the filter set supports them. A single-network filter surfaces that network's richer metrics (e.g. impressions, reach, engagementRate on LinkedIn); a mixed-network filter trims the extras to those common to every network in the set.
Arguments
| Name | Type | Description |
|---|---|---|
| input Required | AggregatedPostMetricsInput! | Query's input: organization, date range, optional channel and tag filters. Date range is capped to 365 days. |
Example Response
{
"data": {
"aggregatedPostMetrics": {
"metrics": [
{
"type": "reactions",
"name": "...",
"description": "...",
"value": 0
}
],
"metricsUpdatedAt": "..."
}
}
}Returns daily posting limit status for the given channels on the specified date.
Arguments
| Name | Type | Description |
|---|---|---|
| input Required | DailyPostingLimitsInput! | Query's input. |
Example Response
{
"data": {
"dailyPostingLimits": [
{
"channelId": "...",
"sent": 0,
"scheduled": 0,
"limit": 0
}
]
}
}Fetches a post by PostID for the given organization: first and last can be set for forward pagination using Relay convention
Arguments
| Name | Type | Description |
|---|---|---|
| input Required | PostInput! | Query's input. |
Example Response
{
"data": {
"post": {
"id": "...",
"ideaId": "...",
"status": "draft",
"via": "buffer"
}
}
}Fetches posts for the given organization: first and last can be set for forward pagination using Relay convention
Arguments
| Name | Type | Description |
|---|---|---|
| input Required | PostsInput! | Query's input. |
| first Optional | Int | The number of posts to return |
| after Optional | String | The cursor of the post to start fetching from |
Example Response
{
"data": {
"posts": {
"edges": [
{
"node": {},
"cursor": "..."
}
],
"pageInfo": {
"startCursor": "...",
"endCursor": "...",
"hasPreviousPage": true,
"hasNextPage": true
}
}
}
}Mutations 3
Create post for channel
Arguments
| Name | Type | Description |
|---|---|---|
| input Required | CreatePostInput! | The mutation's input |
Example Response
{
"data": {
"createPost": {}
}
}Delete a post by id.
Arguments
| Name | Type | Description |
|---|---|---|
| input Required | DeletePostInput! | No description |
Example Response
{
"data": {
"deletePost": {}
}
}Edit post for channel
Arguments
| Name | Type | Description |
|---|---|---|
| input Required | EditPostInput! | The mutation's input |
Example Response
{
"data": {
"editPost": {}
}
}Outputs 6
Aggregated post metrics across a filtered post set. Each entry in `metrics` mirrors the shape of a `Post.metrics` entry; the total number of matched posts is carried as a regular `PostMetric` entry with `type: postCount`.
Fields 2
metrics : [PostMetric!]!
Normalized metric aggregates across the matched posts. Always includes a baseline trio (`postCount`, `reactions`, `comments`) — posts on networks that don't track reactions or comments contribute 0 to those totals. Beyond the baseline, additional metric types are included only when every channel in the filter set supports them.
metricsUpdatedAt : DateTime
The latest `metricsUpdatedAt` across the matched posts, indicating the freshness of the aggregate. Metrics are refreshed daily, so values can be up to ~24h behind the source network. Null when no posts matched the filter.
Status of daily posting limits for a channel on a given day.
Fields 5
channelId : ChannelId!
The channel ID this status refers to.
sent : Int!
Number of posts already sent on this day.
scheduled : Int!
Number of posts scheduled for this day.
limit : Int
The network daily posting limit. Null means unlimited.
isAtLimit : Boolean!
Whether the channel has reached its daily posting limit.
Post entity
Fields 27
id : PostId!
ObjectId of the post
ideaId : IdeaId
Is set when the Post is generated from an Idea
status : PostStatus!
status
via : PostVia!
Indicates if the post is created from Buffer or the API
schedulingType : SchedulingType
Scheduling type can be null if the post was created natively on the social network without using notification publishing or automatic publishing
author : Author
Represents the user who created the post
isCustomScheduled : Boolean!
Indicates whether time to publish was manually selected by the user
createdAt : DateTime!
Date when the post was created
updatedAt : DateTime!
Date when the post was updated
dueAt : DateTime
Date when the post is scheduled to be published
sentAt : DateTime
Date when the post is published
text : String!
Text content of the Post
externalLink : String
The external URL of the post at the destination service
metadata : PostMetadata
Metadata of the post which differs based on the social network/service @see post.metadata.graphql
channelId : ChannelId!
channel ID (faster than resolving the channnel.id)
channelService : Service!
channel service (faster than resolving the channnel.service)
channel : Channel!
channel
tags : [Tag!]!
tags - sorted by name in ascending order
notificationStatus : NotificationStatus
notificationStatus: notified or markedAsPublished
error : PostPublishingError
error
assets : [Asset!]!
assets
metrics : [PostMetric!]
Metrics for the sent post. If post is not yet sent, this field will be null
metricsUpdatedAt : DateTime
Timestamp of when `metrics` were last refreshed from the network. Null until the daily ingestion job has processed the post. Buffer pulls fresh metrics once per day, so this can lag the network value by ~24h.
allowedActions : [PostAction!]!
Indicates what actions the current account can perform on the post
sharedNow : Boolean!
Indicates whether the post was shared via publish now action
shareMode : ShareMode!
Indicates the share mode of the post (e.g., addToQueue, shareNext, shareNow, customScheduled)
Results for the posts query.
Fields 2
edges : [PostsEdge!]
The list of posts that match the query.
pageInfo : PaginationPageInfo!
Information to aid in pagination.
All possible response types for the deletePost mutation.
Create post's request response payload.
Types 44
Annotation representing all the entities in the text
Fields 5
type : AnnotationType!
The type of the annotation
indices : [Int!]!
The indices of the annotation in the text
content : String!
The content of the annotation. Annotations can sometimes be different from the actual text content. E.g., Mastodon mentions have 'text: @buffer', but includes the server name in the content, 'content: @buffer@threads.net'
text : String!
The text representation of the annotation, eg '@buffer'
url : String!
The URL the annotation points to
Represent the author of a post or note.
Fields 5
id : AccountId!
The unique identifier of the author.
email : String!
The email address of the author.
avatar : String!
The avatar URL of the author.
isDeleted : Boolean!
Indicates whether the author is a deleted.
name : String
The name of the author. Null if the user has not yet set a name.
Bluesky post metadata
Fields 5
type : PostType!
The channel-specific type of the post, eg, post, story, reel for Instagram
annotations : [Annotation!]!
Annotations representing entities in the text
thread : [ThreadedPost!]!
The list of threaded posts (not paginated)
threadCount : Int!
The number of threaded posts
linkAttachment : LinkAttachment
Link attachment
deletePost success response returns the post id that was deleted.
Fields 1
id : PostId!
Post id that was delete.
Facebook post metadata
Fields 5
type : PostType!
The channel-specific type of the post, eg, post, story, reel for Instagram
annotations : [Annotation!]!
Annotations representing entities in the text
linkAttachment : LinkAttachment
Link attachment
title : String
Title of Facebook reel
firstComment : String
Facebook post's first comment
Google Business Profile post metadata @deprecated: pending proposal for specific GBP post types: update, offer and event metadata types
Fields 4
type : PostType!
The channel-specific type of the post, eg, post, story, reel for Instagram
title : String
Title if available in the given GBP post type: event and offer
annotations : [Annotation!]!
Annotations representing entities in the text
details : GoogleBusinessPostDetails
Details of the metadata
Instagram Geolocation
Fields 2
id : String
The id of this location
text : String
The name of this location
Instagram post metadata
Fields 7
firstComment : String
Instagram post's first comment
link : String
Shop Grid link for the post
type : PostType!
The channel-specific type of the post, eg, post, story, reel for Instagram
annotations : [Annotation!]!
Annotations representing entities in the text
geolocation : InstagramGeolocation
Geolocation of the post
shouldShareToFeed : Boolean!
Indicates whether post should be shared to feed
stickerFields : InstagramStickerFields
Sticker fields for reminder-based publishing
Instagram fields for reminder-based publishing. Upon the reminder for publishing, the user is prompted to copy and paste these fields into the Instagram app to complete the post.
Fields 5
text : String
Text for the Story or Reel
music : String
Placeholder text for the post's music
products : String
Placeholder text for the post's linked products
topics : String
Placeholder text for the post's topics (Reels only)
other : String
Additional field for any other post content
Link attachment
Fields 6
url : String!
URL that the link asset has been built from
expandedUrl : String
Full URL that the link asset has been built from
text : String!
Description for the scraped link
thumbnails : [String!]!
Thumbnails of media available in the link
thumbnail : String
Selected thumbnail for this link preview
title : String!
Title for the link attachment
LinkedIn post metadata
Fields 4
type : PostType!
The channel-specific type of the post, eg, post, story, reel for Instagram
annotations : [Annotation!]!
Annotations representing entities in the text
firstComment : String
LinkedIn post's first comment
linkAttachment : LinkAttachment
Link attachment
Mastodon post metadata
Fields 5
type : PostType!
The channel-specific type of the post, eg, post, story, reel for Instagram
annotations : [Annotation!]!
Annotations representing entities in the text
thread : [ThreadedPost!]!
The list of threaded posts (not paginated)
threadCount : Int!
The number of threaded posts
spoilerText : String
Spoiler text hiding the root text of this post
Note entity
Fields 7
id : NoteId!
The unique identifier of the note.
text : String!
The content of the note.
type : NoteType!
The type of the note.
author : Author!
The author of the note - null if the user is deleted or left the organization.
createdAt : DateTime!
The date and time when the note was created.
updatedAt : DateTime
The date and time when the note was last edited.
allowedActions : [NoteAction!]!
The allowed actions a user can perform on the note.
Error returned when the resource is not found
Fields 1
message : String!
Error message
Pinterest post metadata
Fields 5
type : PostType!
The channel-specific type of the post, eg, post, story, reel for Instagram
title : String
The title of the Pin
url : String
The Pin destination link
board : PinterestBoard
The board the Pin is saved to
annotations : [Annotation!]!
Annotations representing entities in the text
Success response returns the full up-to-date post from after the action was performed.
Fields 1
post : Post!
Post on which the action was successfully performed.
Represents a posting goal for a channel, including target, progress, and status information.
Fields 6
goal : Int!
The target number of posts for this goal.
sentCount : Int!
The number of posts that have been sent (published or ingested) for this goal.
scheduledCount : Int!
The number of posts that are scheduled to be sent for this goal.
status : PostingGoalStatus!
The current status of the posting goal.
periodStart : DateTime!
The start date of the period for this posting goal.
periodEnd : DateTime!
The end date of the period for this posting goal.
A single metric for a post (or an entry in an aggregated metrics response).
Fields 5
type : PostMetricType!
The type of metric. Cross-network metrics use unified naming (`reactions`, `comments`, etc.); network-specific metrics retain their network's vocabulary (`saves`, `quotes`, etc.). See `PostMetricType` for the full catalog including deprecated values.
name : String!
The human-readable name of the metric (e.g. "Reactions", "Eng. Rate").
description : String!
A human-readable description of what the metric represents.
value : Float!
The metric value. Defaults to 0 when the network did not report the metric.
unit : PostMetricUnit!
The unit (count vs percentage) of `value`.
Post publishing error
Fields 3
message : String!
Error message to display
supportUrl : String
Link to a help center article to help resolve the error
rawError : String
The original error from the publishing service (internal use only)
Represent a node in the pagination result using the Connect Relay convention.
Fields 2
node : Post!
Represents the current post in the list.
cursor : String!
Opaque cursor to be used in pagination to fetch from current node.
Tag associated with a post
Fields 3
color : String!
Hex color for tag e.g #F523F1
Error proxied from the REST API response
Fields 3
message : String!
An error message from the REST API response that we proxied here
link : String
Link to our Help center from the REST API response
code : Int
Error code from the REST API response - https://buffer.com/developers/api/errors
Tag entity
Fields 4
id : TagId!
ObjectId of the tag
color : String!
Hex color for tag e.g '#F523F1'
name : String!
Name of the tag e.g 'Summer sales'
isLocked : Boolean!
Locked tag cannot be assigned to new items in the UI. A Tag is locked after a customer downgrades and has more tags than the free plan limit allows
A post authored by the user which is posted to a thread. This is commonly used for long-format twitter and meta threads posts to allow authored content to span multiple threads. Threads are represented as a list of replies, each replying to the previous one.
Fields 3
text : String!
The text body content of the threaded post
assets : [Asset!]!
Media assets of the threaded post
linkAttachment : LinkAttachment
Link attachment for the threaded post
Threads post metadata
Fields 8
type : PostType!
The channel-specific type of the post, eg, post, story, reel for Instagram
annotations : [Annotation!]!
Annotations representing entities in the text
thread : [ThreadedPost!]!
The list of threaded posts (not paginated)
threadCount : Int!
The number of threaded posts
linkAttachment : LinkAttachment
Link attachment
topic : String
Topic associated with the post
locationId : String
LocationId associated with the post
locationName : String
Location name associated with the post
Tiktok post metadata
Fields 4
type : PostType!
The channel-specific type of the post, eg, post, story, reel for Instagram
annotations : [Annotation!]!
Annotations representing entities in the text
title : String
The title of the TikTok post (for photo posts)
isAiGenerated : Boolean!
Whether the post discloses AI-generated content (TikTok video only)
Twitter post metadata
Fields 6
type : PostType!
The channel-specific type of the post, eg, post, story, reel for Instagram
retweet : RetweetMetadata
The details of the tweet being retweeted
annotations : [Annotation!]!
Annotations representing entities in the text
thread : [ThreadedPost!]!
The list of threaded posts (not paginated)
threadCount : Int!
The number of threaded posts
isAiGenerated : Boolean!
Whether the post discloses AI-generated content
User tag in the image
Fields 3
handle : String!
The handle (username) of the tagged account, without the leading @.
x : Float!
Horizontal position of the tag as a normalized decimal float between 0.0 and 1.0 - the fraction of the image width from the left edge (0.5 is the horizontal center).
y : Float!
Vertical position of the tag as a normalized decimal float between 0.0 and 1.0 - the fraction of the image height from the top edge (0.5 is the vertical center).
Error implementation that allows clients to resolve the MutationError on mutations that do not currently have typed errors. This allows clients to automatically handle errors that may be added to a mutation in future. Do not directly throw this error, use a custom typed error instead
Fields 1
message : String!
Error message
Weekly posting limit for a channel
Fields 3
sent : Int!
The number of posts the channel has sent this week
scheduled : Int!
The number of posts the channel has scheduled for this week
limit : Int!
The weekly posting limit for the channel
Youtube post metadata
Fields 10
type : PostType!
The channel-specific type of the post, eg, post, story, reel for Youtube
annotations : [Annotation!]!
Annotations representing entities in the text
title : String
Title of the Youtube post
privacy : YoutubePrivacy
Privacy setting for post
category : YoutubeCategory
Post category
license : YoutubeLicense
Video license
notifySubscribers : Boolean!
Indicates whether to notify subscribers on publish video
embeddable : Boolean!
Indicates whether the video allows embedding
madeForKids : Boolean!
Indicates whether the video is suitable for kids
isAiGenerated : Boolean!
Whether the post discloses AI-generated content
Asset interface with common fields
Fields 5
id : ID
The ID of the asset in the database
type : AssetType!
The type of the asset
mimeType : String!
The MIME type of the asset
source : String!
URL to the file source
thumbnail : String!
URL to the static thumbnail of the asset
Common properties for all post metadata types
Fields 2
type : PostType!
The channel-specific type of the post, eg, post, story, reel for Instagram
annotations : [Annotation!]!
Annotations representing entities in the text
Common properties for all posts that support threaded replies. See ThreadedPost for more details.
Fields 2
thread : [ThreadedPost!]!
The list of threaded posts (not paginated)
threadCount : Int!
The number of threaded posts
GoogleBusiness Metadata details
Post metadata union type. Contains all possible types of post metadata.
Inputs 43
Input for the `aggregatedPostMetrics` query.
Fields 5
organizationId : OrganizationId!
The organization ID
startDateTime : DateTime!
Start of the aggregation window. Consumers typically pass UTC midnight of the first calendar day in the window, for example `2026-01-01T00:00:00Z`.
endDateTime : DateTime!
End of the aggregation window. Consumers typically pass UTC midnight of the last calendar day in the window (the backend treats the range as inclusive of that day), for example `2026-01-31T00:00:00Z`. Date range is capped to 365 days.
channelIds : [ChannelId!]
Optional list of channel IDs to filter by. When omitted (null), the aggregate spans every channel in the organization the actor has insights access to. When set to an empty array, no channels match and the result is empty.
tags : TagComparator
Filter to posts with specific tags. When omitted, all posts are included regardless of tags.
Annotation representing all the entities in the text
Fields 4
content : String!
The content of the annotation, e.g. '107509875938399'
indices : [Int!]!
The indices of the annotation in the text, e.g. [6, 9] (from 6 to 9 characters in the text)
text : String!
The text representation of the annotation, eg 'Buffer'
url : String!
The URL the annotation points to, e.g. https://www.facebook.com/107509875938399
Annotation representing all the entities in the text
Fields 7
id : String!
The id of the annotation, e.g. 1521226
link : String!
The link of the annotation, e.g. https://www.linkedin.com/company/bufferapp
entity : String!
The entity of the annotation, e.g. urn:li:organization:1521226
vanityName : String!
The vanity name of the annotation, e.g. bufferapp
localizedName : String!
The localized name of the annotation, e.g. Buffer
start : Int!
The start of the annotation, e.g. 5
length : Int!
The length of the annotation, e.g. 6
A single entity's asset. Exactly one variant must be provided.
Fields 4
image : ImageAssetInput
Image asset
video : VideoAssetInput
Video asset
document : DocumentAssetInput
Document asset
link : LinkAssetInput
Link asset
Bluesky post metadata
Fields 2
thread : [ThreadedPostInput!]
The ordered list of posts that make up the thread (not paginated). This array is the source of truth for what gets published: every post in the thread, including the root post, must be provided here. Posts are published in order, each replying to the previous one. The first item is the root post and should match the top-level `text` on the post input.
linkAttachment : LinkAttachmentInput
Link attachment. Mutually exclusive with assets.videos — if both are provided, the video is ignored.
Create post's request input. Note: `assets.videos` and `metadata.{service}.linkAttachment` are mutually exclusive. If both are provided, the video is ignored.
Fields 13
ideaId : IdeaId
Is set when the Post is generated from an Idea
draftId : DraftId
Is set when the Post is generated from a Draft
schedulingType : SchedulingType!
Scheduling type to indicate notification publishing or automatic publishing
dueAt : DateTime
Date when the post is scheduled to be published
text : String
Text content of the Post. Note: for threaded posts, this needs to match the first item in the `thread` array.
metadata : PostInputMetaData
Metadata of the post which differs based on the social network/service
channelId : ChannelId!
Channel's Id for which we want to create the post
tagIds : [TagId!]
List of tag IDs
assets : [AssetInput!]!
Ordered list of assets on this post.
mode : ShareMode!
How the post is being scheduled.
source : String
source where the composer was initiated from, used for tracking.
aiAssisted : Boolean
If this post was created with the help of AI
saveToDraft : Boolean
If true, saves the post as a draft instead of scheduling it. When saving as draft: - Post status will be 'draft' instead of 'buffer' - Posting limits are not checked - The post will not be published until explicitly scheduled
Input for the dailyPostingLimits query.
Comparator for filtering by date
deletePost mutation deletes a post by id.
Fields 1
id : PostId!
Post id to delete.
Document asset
Fields 3
url : String!
Document URL
title : String!
Document title
thumbnailUrl : String!
Document thumbnail URL
Edit post's request input. Note: `assets.videos` and `metadata.{service}.linkAttachment` are mutually exclusive. If both are provided, the video is ignored.
Fields 13
id : PostId!
ID of the post to edit
ideaId : IdeaId
Is set when the Post is generated from an Idea
draftId : DraftId
Is set when the Post is generated from a Draft
schedulingType : SchedulingType!
Scheduling type to indicate notification publishing or automatic publishing
dueAt : DateTime
Date when the post is scheduled to be published
text : String
Text content of the Post. Note: for threaded posts, this needs to match the first item in the `thread` array.
metadata : PostInputMetaData
Metadata of the post which differs based on the social network/service
assets : [AssetInput!]
Ordered list of assets on this post. Omit to preserve the existing list, pass an empty array to clear it
mode : ShareMode!
How the post is being scheduled.
source : String
source where the composer was initiated from, used for tracking.
aiAssisted : Boolean
If this post was edited with the help of AI
saveToDraft : Boolean
If true, saves the post as a draft instead of keeping it scheduled. When saving as draft: - Post status will be 'draft' instead of 'buffer' - The post will not be published until explicitly scheduled
Facebook post metadata
Fields 4
type : PostTypeFacebook!
The channel-specific type of the post, eg, post, story, reel for Facebook
annotations : [AnnotationInputFacebook!]
Annotations representing entities in the text
linkAttachment : LinkAttachmentInput
Link attachment. Mutually exclusive with assets.videos — if both are provided, the video is ignored.
firstComment : String
Facebook post's first comment
Google Business Profile post metadata @deprecated: pending proposal for specific GBP post types: update, offer and event metadata types
Fields 5
type : PostTypeGoogleBusiness!
The channel-specific type of the post, eg, post, offer, event for Google Business Profile
title : String
Title if available in the given GBP post type: event and offer
detailsOffer : GoogleBusinessOfferMetaDataInput
Details of the Offer metadata
detailsEvent : GoogleBusinessEventMetaDataInput
Details of the Event metadata
detailsWhatsNew : GoogleBusinessWhatsNewMetaDataInput
Details of the Whats new metadata
Image asset
Fields 3
url : String!
URL to the file source
thumbnailUrl : String
URL to the static thumbnail of the asset
metadata : ImageMetadataInput
Image specific metadata
Image dimensions
Fields 2
width : Int!
Image width in pixels
height : Int!
Image height in pixels
Instagram Geolocation
Fields 2
id : String
The id of this location
text : String
The name of this location
Instagram post metadata
Fields 6
type : PostType!
The channel-specific type of the post, eg, post, story, reel for Instagram
firstComment : String
Instagram post's first comment
link : String
Shop Grid link for the post
geolocation : InstagramGeolocationInput
Geolocation of the post
shouldShareToFeed : Boolean!
Indicates whether post should be shared to feed
stickerFields : InstagramStickerFieldsInput
Sticker fields for reminder-based publishing
Instagram fields for reminder-based publishing. Upon the reminder for publishing, the user is prompted to copy and paste these fields into the Instagram app to complete the post.
Fields 5
text : String
Text for the Story or Reel
music : String
Placeholder text for the post's music
products : String
Placeholder text for the post's linked products
topics : String
Placeholder text for the post's topics (Reels only)
other : String
Additional field for any other post content
Link attached to the post
Fields 4
url : String!
URL to the link
title : String
Title of the link
description : String
Description of the link
thumbnailUrl : String
Thumbnail URL of the link
Link attachment
Fields 1
url : String!
URL that the link asset has been built from
LinkedIn post metadata
Fields 3
annotations : [AnnotationInputLinkedIn!]
Annotations representing entities in the text
firstComment : String
LinkedIn post's first comment
linkAttachment : LinkAttachmentInput
Link attachment. Mutually exclusive with assets.videos — if both are provided, the video is ignored.
Mastodon post metadata
Fields 2
thread : [ThreadedPostInput!]
The ordered list of posts that make up the thread (not paginated). This array is the source of truth for what gets published: every post in the thread, including the root post, must be provided here. Posts are published in order, each replying to the previous one. The first item is the root post and should match the top-level `text` on the post input.
spoilerText : String
Spoiler text hiding the root text of this post
Pinterest post metadata
Fields 3
title : String
The title of the Pin
url : String
The Pin destination link
boardServiceId : String
The board ID of the Pin, can be obtained when fetching the channel details with the following query: ``` query GetChannelWithSubprofiles { channel(input: { id: "[CHANNEL_ID_HERE]" }) { metadata { ... on PinterestMetadata { boards { serviceId } } } } } ``` Required on create; optional on edit (omitted preserves existing board).
Input for the post query
Fields 1
id : PostId!
The ID of the post to be retrieved
Metadata of the post which differs based on the social network/service
Fields 11
instagram : InstagramPostMetadataInput
Metadata for Instagram post
facebook : FacebookPostMetadataInput
Metadata for Facebook post
linkedin : LinkedInPostMetadataInput
Metadata for LinkedIn post
twitter : TwitterPostMetadataInput
Metadata for Twitter post
pinterest : PinterestPostMetadataInput
Metadata for Pinterest post
google : GoogleBusinessPostMetadataInput
Metadata for Google Business Profile post
youtube : YoutubePostMetadataInput
Metadata for Youtube post
mastodon : MastodonPostMetadataInput
Metadata for Mastodon post
threads : ThreadsPostMetadataInput
Metadata for Threads post
bluesky : BlueskyPostMetadataInput
Metadata for Bluesky post
tiktok : TikTokPostMetadataInput
Metadata for TikTok post
Filter to apply to the posts query
Fields 8
channelIds : [ChannelId!]
When set, it will filter posts by channel
startDate : DateTime
When set, it will return posts with createdAt or dueAt date after startDate
endDate : DateTime
When set, it will return posts with createdAt or dueAt date before endDate
status : [PostStatus!]
When set, it will filter posts by status
tags : TagComparator
Filter posts by tags. Supports specific tags, untagged posts, or union of both.
tagIds : [TagId!]
When set, it will filter posts by tag
dueAt : DateTimeComparator
When set, it will filter posts by their scheduled posting date
createdAt : DateTimeComparator
When set, it will filter posts by the date they were created
Input for the posts query
Fields 3
organizationId : OrganizationId!
The Organization id to fetch posts for
filter : PostsFiltersInput
The filters to apply to the posts query
sort : [PostSortInput!]
The sort to apply to the posts results
Sort order of post results. List multiple to create tie-breaking order.
Fields 2
field : PostSortableKey!
The field to sort by.
direction : SortDirection!
The direction to sort by.
Comparator for filtering by tags
Fields 2
in : [TagId!]!
Include results that have any of the specified tags (union/OR).
isEmpty : Boolean!
When true, include results that have no tags assigned. Can be combined with 'in' for union filtering. Defaults to false if not specified.
Input type for tag information used in idea creation
Fields 3
A post authored by the user which is posted to a thread. This is commonly used for long-format twitter and meta threads posts to allow authored content to span multiple threads. Threads are represented as a list of replies, each replying to the previous one. The first item in the list is the root post of the thread and should match the top-level `text` on the post input; the remaining items are replies.
Fields 2
text : String
The text body content of the threaded post
assets : [AssetInput!]!
Ordered list of assets on this threaded post
Threads post metadata
Fields 6
type : PostType
The type of the post
thread : [ThreadedPostInput!]
The ordered list of posts that make up the thread (not paginated). This array is the source of truth for what gets published: every post in the thread, including the root post, must be provided here. Posts are published in order, each replying to the previous one. The first item is the root post and should match the top-level `text` on the post input.
linkAttachment : LinkAttachmentInput
Link attachment. Mutually exclusive with assets.videos — if both are provided, the video is ignored.
topic : String
Topic associated with the post
locationId : String
LocationId associated with the post
locationName : String
Location name associated with the post
TikTok post metadata
Fields 2
title : String
The title of the TikTok post (for photo posts)
isAiGenerated : Boolean
Whether the post discloses AI-generated content (TikTok video only)
Twitter post metadata
Fields 3
retweet : RetweetMetadataInput
The details of the tweet being retweeted
thread : [ThreadedPostInput!]
The ordered list of posts that make up the thread (not paginated). This array is the source of truth for what gets published: every post in the thread, including the root post, must be provided here. Posts are published in order, each replying to the previous one. The first item is the root post and should match the top-level `text` on the post input.
isAiGenerated : Boolean
Whether the post discloses AI-generated content
User tag in the image
Fields 3
handle : String!
The handle (username) of the account to tag, without the leading @.
x : Float!
Horizontal position of the tag as a normalized decimal float between 0.0 and 1.0 - the fraction of the image width from the left edge (0.5 is the horizontal center). Pass a number, not a string, and do not use pixel coordinates; to convert, divide the pixel X by the image width.
y : Float!
Vertical position of the tag as a normalized decimal float between 0.0 and 1.0 - the fraction of the image height from the top edge (0.5 is the vertical center). Pass a number, not a string, and do not use pixel coordinates; to convert, divide the pixel Y by the image height.
Video asset
Fields 3
url : String!
URL to the file source
thumbnailUrl : String
URL to the thumbnail of the video
metadata : VideoMetadataInput
Video specific metadata
Youtube post metadata
Fields 8
title : String
Title of the Youtube post. Required on create; optional on edit (omitted preserves existing value).
privacy : YoutubePrivacy
Privacy setting for post (default: public)
categoryId : String
Youtube Category ID, one ID of this list: ID: 1 -> Film & Animation ID: 2 -> Autos & Vehicles ID: 10 -> Music ID: 15 -> Pets & Animals ID: 17 -> Sports ID: 19 -> Travel & Events ID: 20 -> Gaming ID: 22 -> People & Blogs ID: 23 -> Comedy ID: 24 -> Entertainment ID: 25 -> News & Politics ID: 26 -> Howto & Style ID: 27 -> Education ID: 28 -> Science & Technology ID: 29 -> Nonprofits & Activism Required on create; optional on edit (omitted preserves existing value).
license : YoutubeLicense
Video license (default: youtube)
notifySubscribers : Boolean
Indicates whether to notify subscribers on publish video (default: true)
embeddable : Boolean
Indicates whether the video allows embedding (default: true)
madeForKids : Boolean
Indicates whether the video is suitable for kids (default: false)
isAiGenerated : Boolean
Whether the post discloses AI-generated content
Enums 21
List of possible types for an annotation
List of possible types for GBP cta
List of possible actions that can be performed on a note
List of possible statuses for a notification
List of possible actions that can be performed on a Post
PostingGoalStatus is used to track the status of a posting goal.
List of possible metrics available for a Post. Values fall into three groups: - **Cross-network normalized** (reactions, comments, shares, reposts, reach, impressions, views, clicks, engagementRate): Used wherever a concept maps cleanly across networks. Per-network adapters normalize their native names (e.g., Instagram `likes` → `reactions`, Twitter `retweets` → `reposts`). - **Network-specific** (saves, follows, quotes, viewers, totalTimeWatched, likes): Real metrics that don't have a cross-network equivalent. `likes` is intentionally distinct from `reactions` on Facebook — Facebook's Graph API surfaces them separately. - **Aggregation-only** (postCount): Meaningful only on aggregate endpoints; never emitted per-post. Deprecated values are pre-normalization legacy or tied to features being removed. They're kept in the enum for backwards compatibility until clients migrate.
The unit representing the value of a PostMetric.
Key of collection to use for sorting
List of possible statuses for a Post
List of possible types for a Post. Some services may have different types (e.g., Instagram has story, reel, post but Twitter has only post)
List of specific post types available for Facebook
List of specific post types available for Google Business profiles
List of possible ways to create a Post
Indicates whether the post was scheduled for notification publishing or automatic publishing
Direction to sort the results by.
Scalars 5
The `DraftId` scalar represents the MongoDB ObjectId of a Buffer Draft
The `NoteId` scalar represents the MongoDB ObjectId of a Buffer Note
The `PostGroupId` scalar represents the MongoDB ObjectId of a Buffer Post Group.
The `PostId` scalar represents the MongoDB ObjectId of a Buffer Post
The `TagId` scalar represents the MongoDB ObjectId of a Buffer Tag
Ideas
Mutations 1
Create a new idea with the given content and metadata
Arguments
| Name | Type | Description |
|---|---|---|
| input Required | CreateIdeaInput! | Input to create an idea |
Example Response
{
"data": {
"createIdea": {}
}
}Outputs 1
createIdea response (including errors)
Types 7
Ideas are the main entity in the create space
Fields 7
id : ID!
Unique identifier for the idea
organizationId : ID!
ID of the organization that owns this idea
content : IdeaContent!
The actual content and metadata of the idea
groupId : ID
ID of the group this idea belongs to (if any)
position : Float
Numerical position for ordering within a group
createdAt : Int!
Unix timestamp of when the idea was created
updatedAt : Int!
Unix timestamp of when the idea was last modified
Content of an idea
Fields 7
title : String
Title or headline of the idea
text : String
Main body text or description of the idea
media : [IdeaMedia!]
List of media items attached to the idea
tags : [PublishingTag!]!
Tags used to categorize and organize the idea
aiAssisted : Boolean!
Indicates whether AI tools were used in creating this idea
services : [Service!]!
Services tagged by the user - this is typically used to annotate ideas with their target services
date : DateTime
DateTime set by user associated with the idea - this often reflects a target publish date.
createIdea response type
Fields 2
idea : Idea
The affected idea
refreshIdeas : Boolean!
If true, the client should refresh the ideas list because other ideas might have been moved
Error returned when the input is invalid
Fields 1
message : String!
Error message
Error returned when the limit is reached
Fields 1
message : String!
Error message
Error returned when unexpected error occurs
Fields 1
message : String!
Error message
Inputs 3
createIdea input type
Fields 5
organizationId : ID!
Organization ID that will own the idea
content : IdeaContentInput!
Content and metadata for the new idea
cta : String
Call-to-action identifier for analytics tracking
group : IdeaGroupInput
Group placement (null for unassigned group)
templateId : String
Template ID used to create the idea
content input for creating/updating an idea
Fields 7
title : String
Title or headline of the idea
text : String
Main body text or description
media : [IdeaMediaInput!]
List of media items to attach
tags : [TagInput!]
Tags to categorize the idea
aiAssisted : Boolean
Whether AI tools were used in creation
services : [Service!]
Services associated with the idea for targeting specific platforms
date : DateTime
Target date for the idea, often used for planning publish schedules
idea group input for create/update
Fields 2
groupId : ID
Target group ID (null for unassigned group)
placeAfterId : ID
ID of idea to place after (null for top position)
Scalars 1
The `IdeaId` scalar represents the MongoDB ObjectId of a Buffer Idea
Organizations
Types 3
Represents the members connection edge. Later, we can add the list of members with the page info to follow our connection edge pattern.
Fields 1
totalCount : Int!
The total count of team members counting the org owner and team members from the Publish DB.
Organization is a representation of a Buffer Organization.
Fields 7
id : OrganizationId!
The ID of the organization.
channelCount : Int!
The total number of channels connected to the organization.
limits : OrganizationLimits!
The limits of the organization. Can be used to check if the organization has reached the limit of channels, members, etc.
members : MemberConnection!
The members of the organization. Can be used to check the total number of members in the organization. In the future, it might contain more information about the members.
name : String!
The name of the organization.
ownerEmail : String!
The owner email of the organization.
shouldEnforce2FASetup : Boolean!
Whether the requesting actor should be sent through 2FA setup before they can use this organization. Derived: true only when the org has `settings.enforce2FA` ON, the `organization-enforced-2fa` rollout Split is ON for the org, and the actor has no 2FA configured on their own account. This is the single source of truth for the forced-2FA gate; app-shell and publish-frontend redirect to the setup flow when it's true. Exposed to the API gateway so any stitched consumer reads the same value.
Resource limits for an organization including channels, members, and content limits
Fields 10
scheduledThreadsPerChannel : Int!
scheduledStoriesPerChannel : Int!
Inputs 1
Allow retrieving a specific Organization
Fields 1
Enums 1
List of possible actions that can be performed on a Organization
Scalars 1
The `OrganizationId` scalar represents the MongoDB ObjectId of a Buffer Organization
Other
Types 8
Document asset
Fields 6
id : ID
The ID of the asset in the database
type : AssetType!
The type of the asset
mimeType : String!
The MIME type of the asset
source : String!
URL to the file source
thumbnail : String!
URL to the static thumbnail of the asset
document : DocumentMetadata!
Document specific metadata
Image asset
Fields 6
id : ID
The ID of the asset in the database
type : AssetType!
The type of the asset
mimeType : String!
The MIME type of the asset
source : String!
URL to the file source
thumbnail : String!
URL to the static thumbnail of the asset
image : ImageMetadata!
Image specific metadata
Video asset
Fields 6
id : ID
The ID of the asset in the database
type : AssetType!
The type of the asset
mimeType : String!
The MIME type of the asset
source : String!
URL to the file source
thumbnail : String!
URL to the static thumbnail of the asset
video : VideoMetadata!
Video specific metadata
Base Mutation Error type
Fields 1
message : String!
Error message
Link data for link preview
Fields 3
url : String!
URL that the link asset has been built from
text : String!
Description for the scraped link
thumbnails : [String!]!
Thumbnails of media available in the link
Scalars 2
The `InvitationId` scalar represents the MongoDB ObjectId of a pending team invitation
The `Uuid` scalar represents an RFC 4122 v4 UUID, e.g. `550e8400-e29b-41d4-a716-446655440000`.
Directives 1
Indicates exactly one field must be supplied and this field must not be null.
Locations: INPUT_OBJECT