# Buffer API Guide 2026: Keys, OAuth, Rate Limits and the MCP Server

> How the Buffer API works: GraphQL on every plan, API keys vs OAuth with PKCE, rate limits per plan, the MCP server, the CLI, the gaps and a first integration.

_Source: https://professionalstoolkit.com/articles/buffer-api — The Professional's Toolkit · updated October 2026_

---


**3,000** — API requests per 30 days on the Free plan; Essentials gets 7,500 and Team 15,000, shared with MCP.



- **Every plan** — API access, Free included
- **100 / 15 min** — request ceiling on all plans
- **1 / 3 / 5 keys** — Free, Essentials, Team


## What the Buffer API is, and who it serves

The Buffer API is a GraphQL interface with **one endpoint, api.buffer.com**, where every query and mutation goes out as a POST request carrying a Bearer token. There is no SDK to install, and Postman or Insomnia work fine for poking at it. It is included on every Buffer plan, Free among them [1]. Buffer says the public API is the same one that powers its own app, and it presents it as the replacement for the older REST API that lived at api.bufferapp.com.

The audience is wider than developers. Buffer pitches the API to people wiring up Zapier, Make, IFTTT or n8n, to builders using AI coding assistants, and to anyone who wants an AI agent to manage the queue. Its own counters on the API page claim 21.2M posts and 318.3K ideas created through the API. In practice the API covers three jobs well: pushing posts into Buffer from another system, capturing ideas, and reading back what is queued or sent. **It is a publishing API, not an analytics or engagement API**, and that shapes almost every decision below.

## Two ways in: a personal key or an OAuth app

### API keys for your own workflows

For scripts and automations that act on your own account, you create an API key under Settings, API in the web app and send it as a Bearer token in the Authorization header. Three rules gate this. Your account email must be verified. Only the organization owner can create keys or app clients, and teammates cannot even see the API limits. And each plan allows a fixed number of keys: one on Free, three on Essentials and five on Team, and downgrading to Free automatically revokes every key except the earliest-created one. A key expires after 7, 30, 60 or 90 days, or after a year, with 30 days as the default, and Buffer emails you when a key is created, shortly before it expires and once it has expired.

Each key carries its own permissions for posts, ideas, account data and post analytics, all ticked by default. You can untick everything except one, so a reporting script can run on a read-only key that cannot publish. Generating a replacement key revokes the old one immediately. One limit matters for agencies: **a personal key is account-wide**, reaching every organization and channel in the account, with no per-organization scoping at this time.

### OAuth 2.0 for apps other people sign in to

If you are building something other Buffer users will connect, you register an app client under the App Clients tab and use OAuth 2.0 with the Authorization Code flow and PKCE, which Buffer requires for every OAuth client. Public clients such as mobile, desktop and single-page apps get no client secret and rely on PKCE alone. Redirect URIs must be registered in advance, match character for character and use HTTPS even on localhost, with up to five per client. Access tokens last about an hour. Refresh tokens arrive only with the offline_access scope, rotate on every use, and reusing an old one revokes the whole grant. Users can revoke an app from their account settings at any time.


> 💡 **Use a read-only key for reports:** Each key carries its own permissions. Give scripts that only read data a key without posting rights, so a bug cannot publish anything.


## Rate limits: what each plan really allows

Limits are counted per client, meaning per personal key group or per app client, over three rolling windows. They are not counted per channel or per organization [2]. Two pooling rules matter. All personal keys share a single usage pool, so a second key on Essentials adds convenience, not capacity. Each OAuth app client, by contrast, gets its own separate limits.

| Plan | Keys / app clients | Per 15 minutes | Per 24 hours | Per 30 days |
| --- | --- | --- | --- | --- |
| Free | 1 / 1 | 100 | 250 | 3,000 |
| Essentials | 3 / 3 | 100 | 250 | 7,500 |
| Team | 5 / 5 | 100 | 500 | 15,000 |

On Free the 30-day cap binds first: 3,000 requests spread over 30 days averages 100 a day, by our arithmetic, well under the 250 the daily window would allow. The marketing page at buffer.com/api still lists 100 requests per 24 hours on Free, while the developer docs and the help center both say 250. The newer documentation wins here, but a Free integration that runs every day should budget for roughly 100 a day anyway.

### What happens when you hit the ceiling

Exceeding a window returns HTTP 429 with a Retry-After header and a body naming the exhausted window. A rejected 429 does not consume quota or extend the lockout, but every other request counts, successful or not. Every authenticated response carries RateLimit and RateLimit-Policy headers, one per window, and the API settings page shows live usage per client. There is no endpoint that reports limits on its own. Buffer's error guide also says GraphQL returns HTTP 200 with a RATE_LIMIT_EXCEEDED error in the errors array, so **handle both shapes** in your client. Developers who need more can email developersupport@buffer.com after trimming their request count, and Buffer may reduce or suspend access for clients that keep flooding it.

## What you can build: posts, scheduling, ideas and tags

### Posts and scheduling modes

The core mutation is createPost, and it targets **one channel per call**. Five channels mean five mutations, or one content item. Each post needs a channel ID, a scheduling type and a sharing mode. The scheduling type is automatic, where Buffer publishes for you, or notification, where Buffer sends a reminder and you finish the post in the app. The mode decides timing: add to the queue, which takes the channel's next free slot; share now; share next; or a custom time given as an ISO 8601 UTC timestamp. A draft is a post created with saveToDraft set to true. Posts from users whose channel role is set to Requires Approval land as drafts awaiting approval, so the API respects your team's approval rules.

Network extras ride along in metadata. You can build threads on X, Bluesky, Threads and Mastodon, add first comments on LinkedIn, Facebook and Instagram, pick the Instagram post type (post, story or reel), choose a Pinterest board, tag Instagram users on automatically published posts (not stories), and pick a video thumbnail frame on Instagram, TikTok or Pinterest. Alt text is required whenever you send image metadata. A dailyPostingLimits query reports each network's daily cap per channel, separate from your API quota.

### Ideas, tags and content items

Ideas belong to the organization rather than to a channel and hold an optional title and text, which suits a form or a chatbot that collects suggestions. Tags are organization-wide labels for posts and ideas, capped at 3 on Free and 250 on a paid plan, but the whole tag API is an early preview that can change without a deprecation period. Content items, also in preview, create channel-specific versions of one post for many channels in a single call under a shared title, tags and target date. Validation is all-or-nothing. If one channel's version fails, nothing is created. Note that the target date is a planning aid and schedules nothing.

### Character limits are counted in code units

Buffer validates text length before it schedules anything, and on most networks it counts UTF-16 code units. **Emoji and Unicode bold or italic letters count as two.** Instagram allows 2,196 characters and counts every line break as two, LinkedIn allows 3,000 and counts every URL as 24, X on a free account allows 280, Threads 500 and Bluesky 300, where graphemes are counted instead. An over-limit post comes back as HTTP 200 with a typed mutation error, not an HTTP failure, so check the payload rather than the status code.

## What the API will not do

The gaps are clear, and some will decide whether the API fits your project. **There are no webhooks**, so keeping another system in sync means polling, and every poll spends quota. There is no file upload endpoint: images, videos and documents must sit at a public URL that stays reachable until the post publishes [3]. Google Drive and Dropbox share links do not work, and signed or expiring URLs can make a scheduled post fail silently because Buffer fetches media at publish time. Buffer suggests hosts such as Cloudinary or Cloudflare R2 instead.

Analytics are thin. Post metrics exist only for personal keys, because the analytics scope cannot be requested through OAuth, and Buffer calls them an early preview not recommended for reporting. There is no analytics CSV export through the API. Reading or replying to comments is not possible, so Community stays in the app, and the help center says the API does not cover Start Page, although the MCP server's create_post tool lists Start Page among its channels. Several legacy REST features did not carry over: managing recurring time slots, general reordering or shuffling of the queue (an experimental movePostInQueue mutation can now move a queued post to the top or bottom of its channel queue), link share counts, a standalone platform configuration endpoint and a deauthorize endpoint. The API Terms add their own fences. The license covers internal use, and you may not build developer tools such as plug-ins or middleware on it.


> ⚠ **Retries can duplicate posts:** MCP write tools take no idempotency key, so a retried create_post whose response was lost can publish twice. Keep approval prompts on for agents.


## The Buffer MCP server: your queue inside an AI assistant

Since June 10, 2026, Buffer has run an official remote MCP server at mcp.buffer.com/mcp. It lets an assistant read channels, browse the queue and drafts, schedule and edit posts, capture ideas and pull post analytics [4]. Named tools include get_account, which returns each organization's plan limits and member count, create_post, list_posts and delete_post. Two generic tools, execute_query and execute_mutation, reach the rest of the GraphQL API, and introspect_schema lets the assistant read the schema. There is also a ready-made prompt for reviewing the week's posts.

Connection comes in two styles. Claude (web, desktop and Claude Code), ChatGPT and the Codex CLI, Cursor, Grok, Manus, Notion custom agents, Perplexity on the web, Raycast and Zapier's MCP client sign in with OAuth, according to Buffer's developer guides, although some older Buffer integration pages still show an API key for Cursor, Perplexity, Raycast and Zapier. ChatGPT web needs Developer mode switched on. n8n, Google's Antigravity, Perplexity Desktop through mcp-remote and any client that can send headers connect with an API key as a Bearer header instead. Raycast needs Raycast Pro. Our [guide to Buffer's AI Assistant](/articles/buffer-ai-assistant) covers the AI features inside the app itself.

### Guardrails before you connect an agent

The MCP connection covers the whole account, with no per-organization scoping. Its requests share the same rate-limit bucket as your personal keys, so connecting more assistants adds no quota. Write tools take no idempotency key. A retried create_post whose response was lost can publish a duplicate. Buffer advises keeping approval prompts on, because create_post can publish immediately and delete_post cannot be undone, and it warns that many MCP clients store API keys in plain-text config files. Check third-party one-click installers, too. The only official endpoint is mcp.buffer.com/mcp, and connected integrations can be reviewed and revoked under Settings, API.

## The CLI, and moving off the old REST API

The Buffer CLI ships as the npm package @bufferapp/cli and needs Node.js 18 or later. Its commands are generated from the public GraphQL schema and return structured JSON, which makes them easy to drop into a deploy script that posts release notes. Every mutation supports a dry-run flag that validates locally and prints the payload without calling the API. The CLI warns when you are down to 10% of your remaining quota, exits with code 3 on a 429, and keeps the API key only in global config, stripping it from repo config. It can also install skill files for Claude Code and Codex.

If you still run code against the legacy REST API, the migration guide maps the changes. Profiles are now channels and updates are now posts. Listing channels needs an organization ID from the account query, and createPost takes one channel ID where REST accepted an array of profiles. Pagination moves from page offsets to forward-only cursors, and errors come back as typed unions in the response body. Authentication gets simpler for personal workflows: a key replaces the old client ID and secret flow. Third-party apps acting for other users move to OAuth with PKCE.

## Your first integration, step by step

1. Verify your account email and confirm you are the organization owner; otherwise you cannot create a key.
2. Connect at least one channel, then create a key under Settings, API with only the permissions you need and a sensible expiry.
3. Store the key in an environment variable such as BUFFER_API_KEY, never in a chat window or a shared repo.
4. Run the account query in the browser-based API Explorer to get your organization ID, then list channels to get channel IDs.
5. Cache those IDs and your tags locally; Buffer says caching can cut request volume by an order of magnitude.
6. Create a draft with createPost and saveToDraft set to true, check it in the Buffer app, then switch to add to the queue.
7. Host any media at a stable public URL before you reference it.
8. Read the RateLimit headers on each response and stop on a 429 until Retry-After has passed.

Buffer estimates about five minutes for a first post, and this order keeps quota use low. It works for an AI agent too. Buffer's own agent setup guide tells agents to read the key only from the environment, to make read-only requests during setup and to ask for explicit approval before every mutation. That is good discipline for human-written scripts as well. Start with drafts, watch the queue for a few days, and only then let an automation publish on its own. Most early mistakes, from a wrong channel ID to an expired media link, show up harmlessly in a draft.


> 💡 **Start every automation with drafts:** Create posts with saveToDraft set to true and check them in the app for a few days. Switch to the queue once channel IDs and media links prove reliable.


## Is the Buffer API enough for your project?

For a small team that wants to feed Buffer from a spreadsheet, a CMS, a form or an AI assistant, the answer is usually yes. The API is free to start, the limits are published, the docs are thorough, and the MCP server makes conversational scheduling practical without code. It fits personal automations and simple internal tools best. Agencies should weigh the account-wide scope of keys and MCP connections before handing access to an agent. Apps that need two-way sync, uploaded media or reporting will hit the gaps quickly.

Skip it, or plan around it, if your project depends on webhooks, comment handling, dependable analytics or high-volume multi-user traffic beyond the published tiers. In those cases, talk to Buffer's developer support team about higher limits before you build, or treat Buffer as one publishing endpoint among several. Our [Buffer buyer's checklist](/articles/buffer-buyers-checklist) walks through the wider plan and feature questions.


## FAQ

**Is the Buffer API free?**

Yes. The API is available on every Buffer plan, including Free, which allows one API key and 3,000 requests per 30 days.

**How do I get a Buffer API key?**

Verify your account email, then create a key under Settings, API in the web app. Only the organization owner can create keys, and each key expires after 7 to 90 days or a year.

**What are the Buffer API rate limits?**

Limits are counted per client. Every plan allows 100 requests per 15 minutes. Free and Essentials allow 250 per 24 hours and Team 500, with 3,000, 7,500 and 15,000 per 30 days. All personal keys and MCP connections share one pool, while each OAuth app client gets its own.

**Does Buffer have an MCP server?**

Yes. The official server at mcp.buffer.com/mcp connects Claude, ChatGPT, Cursor, Perplexity and other clients through OAuth or, on some clients, an API key, and shares the same rate limits as your API keys.

**Can I upload images through the Buffer API?**

No. The API has no upload endpoint; media must sit at a public URL that stays reachable until the post publishes.

**Does the Buffer API support webhooks or analytics?**

There are no webhooks, so syncing requires polling. Post metrics are an experimental preview available only with personal API keys.


## The bottom line

The Buffer API is a clean, well-documented GraphQL publishing API that every plan gets, Free included, with an official MCP server and CLI on top. Use a personal key for your own automations and OAuth with PKCE for apps that others sign in to. Budget against the 30-day cap rather than the daily one, host your media publicly, and poll sparingly, since there are no webhooks. If you need analytics, comments or real-time sync, the API is not there yet; if you need to get posts into Buffer reliably from somewhere else, it does that job well.



## Sources

[1] Buffer Help: What is Buffer's API? — https://support.buffer.com/articles/what-is-buffers-api-GtIYIQilz5 (2026-10)
[2] Buffer Developers: guides / api limits — https://developers.buffer.com/guides/api-limits (2026-10)
[3] Buffer Developers: guides / hosting media — https://developers.buffer.com/guides/hosting-media (2026-10)
[4] Buffer Developers: guides / integrations / mcp — https://developers.buffer.com/guides/integrations/mcp (2026-10)
[5] Buffer pricing page — https://buffer.com/pricing
[6] Buffer Help Center — https://support.buffer.com/articles/buffer-pricing-and-features-6pJrOPuzIt
[7] Buffer changelog — https://buffer.com/changelog
[8] G2, Buffer reviews — https://www.g2.com/products/buffer/reviews