Get Social plan limits and usage

Reports what your Social plan allows and how much of it you have used. Read it before issuing a connection link, so you can tell a customer they are out of room instead of surfacing a SY95042 from a failed write.

usage.connections is exactly usage.connectionsActive + usage.connectionsReleased.

A released slot is held until the period ends

Disconnecting a channel takes it offline immediately, but it does not hand the slot back. Within a billing period the cap counts the distinct connections you have used, whether or not they are still connected, so the slot stays spent until the subscription renews. Three consequences worth coding for:

• Headroom is maxConnections - usage.connections, never maxConnections - usage.connectionsActive. Using the active count will tell a customer they have room they do not have, and the next connection link will come back SY95042.
• Relinking the same account to the same brand is free. If a customer reconnects a Page they disconnected from that brand earlier in the period, it reuses the slot it already holds: connectionsActive goes up, connectionsReleased goes down, and connections does not move. Attaching that same Page to a different brand is a separate slot, and the original stays held until renewal.
• connectionsReleased is your renewal forecast. It is precisely how many slots return to the pool when the cycle turns, which is what to show a customer deciding between waiting for renewal and buying a pack today.

This is the same shape as the rest of the billing model: capacity you buy is available at once, and capacity you give up leaves at the end of the cycle. See Plans and add-ons.

Use case: a pre-flight check in your onboarding flow. Before offering a customer the "connect an account" button, compare usage.connections — the billable count, not connectionsActive — with maxConnections. If there is no headroom, show them the add-on or upgrade path rather than letting POST /social/brands/{brandId}/connections/link fail. There is no equivalent check for brands: creating one with POST /social/brands never runs out of room.

Use case: sizing the next add-on. Connection packs are sold in fives, so maxConnections - usage.connections tells you directly how many networks you can still connect, and ceil((needed - headroom) / 5) is how many packs to buy.

Notes.

• Brands are unlimited and unmetered. brands comes back null for dev-portal accounts. Client code that treated it as an integer cap must handle null, and should not render "0 brands remaining".
• Connections are an account-wide pool, not a per-brand allowance. A brand can hold as many connections as you like, up to the five networks it supports, as long as the pool has room. See Plans and add-ons.
• This endpoint covers the Social subscription only. Location caps belong to the Listings subscription and are enforced separately at POST /locations, which returns SY10155 when the account has no Listings plan at all.
• Self-serve accounts are capped at 250 connections however many packs are purchased. Above that, the account has to move to Enterprise.
• Spare capacity does not guarantee Instagram will connect. Instagram only allows a Business or Creator account linked to a Facebook Page; a personal account is refused at Meta's consent screen, not by this cap. If a customer has room here and the connection link still fails for Instagram, the account needs converting rather than more capacity.
• The numbers are live, but a release is not a refund. Disconnecting with disconnect, or archiving a brand, is reflected here on the next read — as a fall in usage.connectionsActive and a matching rise in usage.connectionsReleased. usage.connections is unchanged, because the slot is held until the period ends. Both release paths behave identically.