> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nekt.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Buffer as a data source

> Bring your Buffer organizations, channels, posts with their performance metrics, tags and ideas to Nekt.

Buffer is a social media management platform used to plan, schedule and publish posts on Instagram, Facebook, LinkedIn, X (Twitter), TikTok, YouTube, Threads, Pinterest, Bluesky and other networks, and to track how those posts perform. This connector reads your Buffer workspaces (organizations), their connected channels, every post (sent, scheduled, drafts, awaiting approval and failed) with its performance metrics, plus tags, ideas and content items.

## Configuring Buffer as a Source

In the [Sources](https://app.nekt.ai/sources) tab, click on the "Add source" button located on the top right of your screen. Then, select the Buffer option from the list of connectors.

Click **Next** and you'll be prompted to add your access.

### 1. Add account access

The connector uses a personal API key of your Buffer account.

1. Log in to [Buffer](https://buffer.com) with the account whose data you want to bring.
2. Go to **Settings > API** ([publish.buffer.com/settings/api](https://publish.buffer.com/settings/api)) and create a new API key.
3. Copy the key and paste it in Nekt.

The following configurations are available:

* **API Key**: (Required) The personal API key you created. It reads every organization and channel of your Buffer account, including post metrics.
* **Start Date**: (Optional) Only posts created or scheduled on or after this date are read. Leave it empty to read every post Buffer keeps.
* **Organization IDs**: (Optional) IDs of the Buffer organizations to read. Leave it empty to read every organization the API key can access. If you enter an ID the key cannot access, the run fails and lists the organizations it can access.

> [!NOTE]
>
> Post metrics are only available with a personal API key. Keys and AI assistants connected to the same Buffer account share one request limit (see [API Limits & Performance](#api-limits-performance)).

Once you're done, click **Next**.

### 2. Select streams

Choose which data streams you want to sync. For faster extractions, select only the streams that are relevant to your analysis.

> Tip: The stream can be found more easily by typing its name.

Select the streams and click **Next**.

### 3. Configure data streams

Customize how you want your data to appear in your catalog. Select the desired layer where the data will be placed, a folder to organize it inside the layer, a name for each table (which will effectively contain the fetched data) and the type of sync.

* **Layer**: choose between the existing layers on your catalog. This is where you will find your new extracted tables as the extraction runs successfully.
* **Folder**: a folder can be created inside the selected layer to group all tables being created from this new data source.
* **Table name**: we suggest a name, but feel free to customize it. You have the option to add a **prefix** to all tables at once and make this process faster!
* **Sync Type**: every Buffer stream is FULL\_TABLE: each extraction reads the current state of the data, so post status changes, metric updates and deletions made in Buffer show up in your tables.

Once you are done configuring, click **Next**.

### 4. Configure data source

Describe your data source for easy identification within your organization, not exceeding 140 characters.

To define your [Trigger](https://docs.nekt.com/runs/scheduling-and-triggers.md), consider how often you want data to be extracted from this source. Buffer refreshes post metrics once a day, so a daily extraction is usually enough.

Optionally, you can configure Delta Log Retention and determine for how long we should store old states of this table as it gets updated. Read more about this resource [here](https://docs.nekt.com/get-started/core-concepts/resource-control).

Once you are ready, click **Next** to finalize the setup.

### 5. Check your new source

You can view your new source on the [Sources](https://app.nekt.ai/sources) page. If needed, manually trigger the source extraction by clicking on the arrow button. Once executed, your data will appear in your Catalog.

> [!WARNING]
>
> For you to be able to see it on your [Catalog](https://app.nekt.ai/catalog), you need at least one successful source run.

# Streams and Fields

## Available streams

The table below lists every stream, its **slug** (the exact identifier to pass when creating the source via API), a short description and the Buffer data it needs. Every table has an `organization_id` column.

| Stream | Slug | Description | Buffer access needed |
| - | - | - | - |
| Organizations | `organizations` | Buffer organizations (workspaces) of the account, with their plan limits. | Account |
| Channels | `channels` | Connected social media channels (profiles, pages, accounts) and their posting schedule. | Account |
| Posts | `posts` | Every post (sent, scheduled, drafts, awaiting approval, failed) with its performance metrics. | Posts |
| Tags | `tags` | Tags (labels) applied to posts, ideas and content items. | Posts |
| Content Items | `content_items` | Pieces of content: channel-less drafts, or the group of channel posts created together. | Posts |
| Ideas | `ideas` | Ideas saved in the organization before they become posts. | Ideas |
| Idea Groups | `idea_groups` | Columns of the ideas board. | Ideas |

If the API key cannot read posts or ideas, the tables of that area are skipped (the run log says which ones) and the other tables keep syncing.

## Fields by stream

> [accordion] Organizations
>
> One row per Buffer organization (workspace) the API key reads.
>
> | Field | Type | Description |
> | - | - | - |
> | `id` | string | Unique identifier of the organization |
> | `name` | string | Name of the organization (workspace) |
> | `owner_email` | string | Email address of the organization's owner |
> | `channel_count` | integer | Total number of channels connected to the organization |
> | `member_count` | integer | Total number of team members, counting the owner |
> | `limits` | string (JSON) | Plan limits of the organization: maximum channels, members, scheduled posts, ideas and tags |

> [accordion] Channels
>
> One row per connected channel. Join `posts.channel_id` to `channels.id`.
>
> | Field | Type | Description |
> | - | - | - |
> | `id` | string | Unique identifier of the channel in Buffer |
> | `organization_id` | string | ID of the Buffer organization (workspace) the record belongs to |
> | `name` | string | Name of the channel on the social network (handle, username or page name) |
> | `display_name` | string | Display name of the channel |
> | `descriptor` | string | Formatted service and type of the channel, e.g. 'Instagram Business' or 'Facebook Page' |
> | `service` | string | Social network of the channel (instagram, facebook, linkedin, twitter, tiktok, youtube, threads, bluesky, ...) |
> | `type` | string | Type of the channel on the network (page, profile, business, group, account, channel) |
> | `service_id` | string | ID of the channel on the social network's own API |
> | `avatar` | string | URL of the channel's avatar image |
> | `external_link` | string | URL of the channel on the social network |
> | `timezone` | string | Time zone of the channel's posting schedule |
> | `is_disconnected` | boolean | True when the channel lost its connection to Buffer and needs to be reconnected |
> | `is_locked` | boolean | True when the channel is locked (usually after a plan downgrade) and cannot be used for posting |
> | `is_queue_paused` | boolean | True when the channel's queue is paused, so scheduled posts are not published |
> | `products` | array | Buffer products that support the channel |
> | `created_at` | datetime | When the channel was connected to Buffer |
> | `updated_at` | datetime | When the channel was last updated in Buffer |
> | `posting_schedule` | string (JSON) | Posting slots for each day of the week: day, times (HH:MM) and whether the day is paused |
> | `posting_goal` | string (JSON) | Posting goal of the channel for the current period: goal, sent and scheduled counts, status and period dates |

> [accordion] Posts
>
> One row per post. Metric columns are filled for sent posts once Buffer has collected them from the network (up to about 24 hours after publishing, then refreshed daily). A metric the network does not report is empty, not 0. Every reported metric is also in the `metrics` JSON column.
>
> | Field | Type | Description |
> | - | - | - |
> | `id` | string | Unique identifier of the post in Buffer |
> | `organization_id` | string | ID of the Buffer organization (workspace) the record belongs to |
> | `channel_id` | string | ID of the channel the post belongs to (see the channels table) |
> | `channel_service` | string | Social network of the post's channel (instagram, facebook, linkedin, ...) |
> | `status` | string | Lifecycle status of the post: draft, needs\_approval, scheduled, sending, sent or error |
> | `post_type` | string | Format of the post on its network: post, story, reel, short, thread, carousel, event, offer, ... |
> | `text` | string | Text content of the post |
> | `due_at` | datetime | When the post is (or was) scheduled to be published |
> | `sent_at` | datetime | When the post was published |
> | `created_at` | datetime | When the post was created in Buffer |
> | `updated_at` | datetime | When the post was last updated in Buffer |
> | `external_link` | string | URL of the published post on the social network |
> | `idea_id` | string | ID of the idea the post was created from, when it came from one (see the ideas table) |
> | `is_custom_scheduled` | boolean | True when the publishing time was chosen manually instead of taken from the queue |
> | `share_mode` | string | How the post was scheduled: addToQueue, shareNext, shareNow or customScheduled |
> | `shared_now` | boolean | True when the post was published with 'Share now' |
> | `scheduling_type` | string | How the post publishes: automatic (Buffer publishes it) or notification (a reminder to publish it by hand) |
> | `notification_status` | string | For notification posts: notified or markedAsPublished |
> | `via` | string | Where the post was created: buffer, api or network (published directly on the network) |
> | `author_id` | string | Buffer account ID of the person who created the post |
> | `author_name` | string | Name of the person who created the post |
> | `author_email` | string | Email address of the person who created the post |
> | `error_message` | string | Why the post could not be published (status error) |
> | `error_support_url` | string | Help article about the publishing error |
> | `tag_ids` | array | IDs of the tags applied to the post (see the tags table) |
> | `tags` | string (JSON) | Tags applied to the post: id, name and color |
> | `assets` | string (JSON) | Media attached to the post, in order: id, type (image, video, document, link), MIME type, file URL and thumbnail URL |
> | `metrics` | string (JSON) | Every performance metric Buffer reports for the post: type, name, value and unit (count or percentage). Only sent posts have metrics |
> | `metrics_updated_at` | datetime | When Buffer last refreshed the post's metrics from the network (once a day) |
> | `metric_reactions` | number | Reactions (likes and similar) on the post, normalized across networks |
> | `metric_comments` | number | Comments and replies on the post |
> | `metric_shares` | number | Times the post was shared or forwarded |
> | `metric_reposts` | number | Times the post was reposted (retweets, reblogs, Threads reposts) |
> | `metric_impressions` | number | Times the post was shown on screen (may count the same person more than once) |
> | `metric_reach` | number | Unique people who saw the post |
> | `metric_views` | number | Views of the post, on networks that report views separately (mostly video) |
> | `metric_clicks` | number | Clicks on the post |
> | `metric_engagement_rate` | number | Engagement rate of the post, in percent (0 to 100) |
> | `metric_saves` | number | Times the post was saved (Instagram, Pinterest) |
> | `metric_follows` | number | New followers attributed to the post (Instagram) |
> | `metric_quotes` | number | Times the post was quoted (Threads) |
> | `metric_likes` | number | Like reactions only (Facebook); metric\_reactions holds every reaction type |
> | `metric_viewers` | number | Unique video viewers (LinkedIn) |
> | `metric_total_time_watched` | number | Total time the video was watched, in minutes (LinkedIn, TikTok, Instagram Reels) |
> | `metric_average_time_watched` | number | Average time the video was watched, in seconds (TikTok, Instagram Reels) |
> | `metric_free_subscriptions` | number | Free subscriptions Substack attributes to the note |
> | `metric_paid_subscriptions` | number | Paid subscriptions Substack attributes to the note |

> [accordion] Tags
>
> One row per tag. Posts, ideas and content items list their tags in `tag_ids`.
>
> | Field | Type | Description |
> | - | - | - |
> | `id` | string | Unique identifier of the tag |
> | `organization_id` | string | ID of the Buffer organization (workspace) the record belongs to |
> | `name` | string | Display name of the tag |
> | `color` | string | Color of the tag as a hex triplet, e.g. #F523F1 |
> | `color_name` | string | Buffer palette name of the color; empty for a custom color |
> | `is_locked` | boolean | True when the tag is locked because the organization holds more tags than its plan allows (it can still be applied, not edited) |

> [accordion] Content Items
>
> One row per content item: either a channel-less draft, or the set of channel posts created from it (`post_ids`).
>
> | Field | Type | Description |
> | - | - | - |
> | `id` | string | Unique identifier of the content item |
> | `organization_id` | string | ID of the Buffer organization (workspace) the record belongs to |
> | `title` | string | Title of the content item |
> | `target_date` | datetime | Date the content is planned to go out (a planning aid; it does not schedule posts) |
> | `created_at` | datetime | When the content item was created |
> | `author_id` | string | Buffer account ID of the person who created the content item |
> | `author_name` | string | Name of the person who created the content item |
> | `tag_ids` | array | IDs of the tags applied to the content item as a whole (see the tags table) |
> | `tags` | string (JSON) | Tags applied to the content item: id, name and color |
> | `body_type` | string | draft (a channel-less draft) or posts (channel-specific posts were created from it) |
> | `draft_id` | string | ID of the channel-less draft, when the content item is a draft |
> | `draft_text` | string | Text of the channel-less draft |
> | `draft_ai_assisted` | boolean | True when the draft was written with the help of AI |
> | `draft_assets` | string (JSON) | Media attached to the draft: id, type, MIME type, file URL and thumbnail URL |
> | `post_ids` | array | IDs of the posts created from the content item, one per channel (see the posts table) |

> [accordion] Ideas
>
> One row per idea.
>
> | Field | Type | Description |
> | - | - | - |
> | `id` | string | Unique identifier of the idea |
> | `organization_id` | string | ID of the Buffer organization (workspace) the record belongs to |
> | `group_id` | string | ID of the idea group (board column) the idea is in; empty when unassigned (see the idea\_groups table) |
> | `position` | number | Position of the idea within its group |
> | `title` | string | Title of the idea |
> | `text` | string | Body text of the idea |
> | `target_date` | datetime | Date set on the idea by the user, often the intended publish date |
> | `ai_assisted` | boolean | True when AI tools were used to write the idea |
> | `services` | array | Social networks the idea is meant for |
> | `tag_ids` | array | IDs of the tags applied to the idea (see the tags table) |
> | `tags` | string (JSON) | Tags applied to the idea: id, name and color |
> | `media` | string (JSON) | Media attached to the idea: id, type, URL, thumbnail URL, alt text and size in bytes |
> | `created_at` | datetime | When the idea was created |
> | `updated_at` | datetime | When the idea was last modified |

> [accordion] Idea Groups
>
> One row per idea group (column of the ideas board). Primary key: `organization_id` + `id`.
>
> | Field | Type | Description |
> | - | - | - |
> | `id` | string | Unique identifier of the idea group |
> | `organization_id` | string | ID of the Buffer organization (workspace) the record belongs to |
> | `name` | string | Name of the idea group (board column) |
> | `is_locked` | boolean | True when the idea group is locked |

## Implementation Notes

### Data Quality Considerations

* Every table is rebuilt on each sync (FULL\_TABLE), so status changes (scheduled to sent), metric refreshes and deletions in Buffer are reflected.
* Buffer deletes sent and failed posts, with their media, two years after they go out. Those posts then leave the `posts` table too; keep your own copy (for example with [History](https://docs.nekt.com/histories/overview.md)) if you need a longer history.
* Buffer refreshes post metrics once a day; `metrics_updated_at` says when a post's metrics were last refreshed.
* Metrics are normalized across networks: `metric_reactions` holds Instagram and X likes, `metric_reposts` holds retweets, Mastodon reblogs and Threads reposts. On Facebook, `metric_likes` is the Like reaction only and `metric_reactions` is every reaction type.
* `metric_engagement_rate` is a percentage (0 to 100).
* When **Start Date** is set, posts created before it but scheduled after it are still read.
* Posts are read in order of creation. Buffer does not report the total number of posts, so after the first run compare the number of posts per channel and status with the Buffer app; if they differ, contact Nekt support.

### API Limits & Performance

* Buffer limits API requests per account, shared by every API key and AI assistant connected to it, in three windows: 15 minutes, 24 hours and 30 days. The limits depend on your Buffer plan (Free: 150 per 15 minutes and 600 per day; Essentials: 450 and 1,800; Team: 1,500 and 6,000).
* A sync uses about one request per 100 posts, tags, ideas and content items of each organization, plus two per organization for channels and idea groups.
* When the 15-minute window is nearly used up, the sync pauses until it resets, leaving room for your other Buffer tools.
* The sync never uses the last 10% of the daily or 30-day limit: when only that is left, or when what is left is not enough to read the next table whole, the run stops (tables not read keep their previous data) and the next run after the reset syncs normally. This keeps your other Buffer tools and AI assistants working.

## Troubleshooting

| Error or symptom | What it means | What to do |
| :- | :- | :- |
| "Buffer rejected the API key of this source" | The key is wrong, revoked or expired. | Create a new key in Buffer under **Settings > API** and update the source. |
| "This Buffer API key may not read ..." and some tables skipped | The key cannot read that area (posts or ideas), or cannot read it in the organization the message names. | Create a personal API key that can read it, set **Organization IDs** to the organizations that can be read (the message lists them), or deselect those tables. |
| "These Organization IDs ... are not organizations this Buffer API key can access" | An ID in **Organization IDs** is wrong or belongs to another Buffer account. | Use one of the IDs listed in the message, or leave the field empty. |
| "Your Buffer account has used up (or almost used up) its daily (or 30-day) API request limit", or "... requests left, and 'posts' needs about N" | The account's shared request limit ran out or is down to its last 10%, possibly because of other tools using the same Buffer account. | Wait for the reset (the message says when), schedule the source less often, or upgrade the Buffer plan. |
| Metric columns empty for a recently published post | Buffer collects metrics up to about 24 hours after publishing. | Wait for the next daily refresh. |
| Old sent posts disappeared from `posts` | Buffer deletes sent posts after two years. | Expected. Use History to keep older versions. |

## Skills for agents

<Snippet file="agent-skills-intro.mdx" />

> [card] [Download Buffer skills file](https://docs.nekt.com/sources/buffer.md)
>
> Buffer connector documentation as plain markdown, for use in AI agent contexts.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.