Listings APIListings API
로그인
GET/api/v4/social/limits

Social 요금제 한도 및 사용량 조회

계정의 Social 연결 한도와 함께 현재 청구 기간의 청구 대상, 활성 및 해제된 연결 사용량을 반환합니다.

API 키가 필요합니다. 헤더 형식과 키 교체는 인증을 참고하세요.

매개변수

이 엔드포인트는 매개변수를 받지 않습니다.

응답

200The account's Social caps and current usage. `brands` is null because brands are unlimited on API plans. Here 118 connections are billable: 112 still connected, plus 6 disconnected during this period whose slots are held until renewal.
Response
{  "data": {    "fetchAccountLimits": {      "brands": null,      "connections": 135,      "maxConnections": 135,      "users": 10,      "aiCredits": 500,      "usage": {        "brands": 31,        "connections": 118,        "connectionsActive": 112,        "connectionsReleased": 6      }    }  }}
401Unauthenticated, missing or invalid API key.

Social 요금제에서 허용하는 용량과 사용한 용량을 알려 줍니다. 연결 링크를 발급하기 전에 조회하면, 쓰기 작업 실패로 발생한 SY95042를 표시하는 대신 고객에게 남은 용량이 없다고 안내할 수 있습니다.

필드의미
brands브랜드 허용량입니다. 모든 API 요금제에서 null이며, 이는 무제한을 의미합니다. 이 값이 null이면 0이 아니라 "한도 없음"으로 처리합니다.
connections구독 등급에 포함된 연결 수와 추가로 구매한 연결 팩에 포함된 연결 수를 합한 값입니다.
maxConnections연결을 설정할 때 실제로 적용되는 한도입니다. API 요금제에서는 connections와 같습니다.
users요금제에 포함된 사용자 수입니다.
aiCredits현재 기간에 포함된 콘텐츠 생성 크레딧입니다.
usage.brands현재 존재하는 브랜드 수입니다. 참고용 정보이며, 비교할 한도는 없습니다.
usage.connections청구 대상 수이며, 한도가 적용되는 유일한 수치입니다. 현재 청구 기간 중 한 번이라도 사용한 연결을 중복 없이 센 값으로, 아직 연결된 항목과 이번 기간에 해제된 항목을 합한 수입니다. 이 값을 maxConnections와 비교합니다.
usage.connectionsActive현재 연결되어 있는 연결 수입니다. 항상 usage.connections보다 작거나 같습니다. 고객에게 현재 활성 상태인 연결을 보여 주는 데 유용하며, 요금이 청구되는 수는 아닙니다.
usage.connectionsReleased현재 청구 기간에 연결이 해제되었지만 슬롯은 계속 점유하고 있는 연결 수입니다. 이 용량은 구독 갱신 시 다시 사용할 수 있습니다.

usage.connections는 정확히 usage.connectionsActive + usage.connectionsReleased입니다.

해제된 슬롯은 기간이 끝날 때까지 계속 점유됩니다

채널의 연결을 해제하면 즉시 오프라인 상태가 되지만, 슬롯을 반환하지는 않습니다. 청구 기간 내에는 연결이 유지되는지와 관계없이 사용한 연결을 중복 없이 세어 한도에 반영하므로, 구독이 갱신될 때까지 해당 슬롯은 사용된 상태로 유지됩니다. 코드에 반영해야 할 사항은 다음 3가지입니다.

  • 남은 용량은 maxConnections - usage.connections이며, 절대로 maxConnections - usage.connectionsActive가 아닙니다. 활성 연결 수를 사용하면 실제로는 용량이 없는데도 고객에게 용량이 남아 있다고 안내하게 되며, 다음 연결 링크 요청은 SY95042를 반환합니다.
  • 동일한 계정을 동일한 브랜드에 다시 연결하는 것은 무료입니다. 고객이 이번 기간에 해당 브랜드에서 연결을 해제했던 Page를 다시 연결하면, 이미 점유 중인 슬롯을 재사용합니다. 이때 connectionsActive는 증가하고, connectionsReleased는 감소하며, connections는 변하지 않습니다. 동일한 Page를 다른 브랜드에 연결하면 별도의 슬롯을 사용하며, 기존 슬롯은 갱신 시까지 계속 점유됩니다.
  • connectionsReleased는 갱신 시 반환될 용량의 예상치입니다. 이는 청구 주기가 바뀔 때 공용 용량으로 반환되는 슬롯 수와 정확히 일치하므로, 갱신을 기다릴지 지금 팩을 구매할지 결정하는 고객에게 보여 주어야 하는 값입니다.

이는 나머지 청구 모델과 같은 방식입니다. 구매한 용량은 즉시 사용할 수 있고, 포기한 용량은 청구 주기가 끝날 때 제거됩니다. 요금제 및 추가 기능을 참조하세요.

사용 사례: 온보딩 흐름의 사전 확인. 고객에게 "계정 연결" 버튼을 제공하기 전에 connectionsActive가 아닌 청구 대상 수인 usage.connections를 maxConnections와 비교합니다. 남은 용량이 없으면 POST /social/brands/{brandId}/connections/link가 실패하도록 두는 대신 추가 기능이나 업그레이드 방법을 안내합니다. 브랜드에는 이에 해당하는 확인 절차가 없습니다. POST /social/brands로 브랜드를 생성할 때는 용량이 부족해지는 일이 없습니다.

사용 사례: 다음에 구매할 추가 기능 규모 산정. 연결 팩은 5개 단위로 판매되므로, maxConnections - usage.connections는 추가로 연결할 수 있는 네트워크 수를 바로 알려 주고, ceil((needed - headroom) / 5)는 구매할 팩 수를 나타냅니다.

참고 사항.

  • 브랜드는 무제한이며 사용량을 계량하지 않습니다. listingsAPI 계정에서는 brands가 null로 반환됩니다. 이 값을 정수형 한도로 처리하던 클라이언트 코드는 null을 처리해야 하며, "남은 브랜드 0개"를 표시해서는 안 됩니다.
  • 연결 용량은 브랜드별 허용량이 아니라 계정 전체에서 공유하는 용량입니다. 공유 용량에 여유가 있으면, 브랜드는 지원하는 5개 네트워크 범위 내에서 원하는 만큼 연결을 보유할 수 있습니다. 요금제 및 추가 기능을 참조하세요.
  • 이 엔드포인트는 Social 구독만 다룹니다. 사업장 한도는 Listings 구독에 속하며 POST /locations에서 별도로 적용됩니다. 계정에 Listings 요금제가 전혀 없으면 사업장 생성 엔드포인트가 SY10155를 반환합니다.
  • 셀프서비스 계정은 구매한 팩 수와 관계없이 연결 수가 250개로 제한됩니다. 이를 초과하려면 계정을 Enterprise로 전환해야 합니다.
  • 남은 용량이 있어도 Instagram 연결이 보장되지는 않습니다. Instagram은 Facebook Page에 연결된 Business 또는 Creator 계정만 허용하며, 개인 계정은 이 한도가 아니라 Meta의 동의 화면에서 거부됩니다. 고객에게 여기서 확인한 남은 용량이 있는데도 Instagram의 연결 링크가 계속 실패한다면, 용량을 늘리는 대신 계정 유형을 전환해야 합니다.
  • 수치는 실시간으로 반영되지만, 해제가 환불을 의미하지는 않습니다. disconnect로 연결을 해제하거나 브랜드를 보관 처리하면 다음 조회 시 여기에 반영되어, usage.connectionsActive가 감소하고 usage.connectionsReleased가 같은 만큼 증가합니다. 슬롯은 기간이 끝날 때까지 계속 점유되므로 usage.connections는 변하지 않습니다. 두 해제 방식은 동일하게 동작합니다.
Request
curl -X GET 'https://listingsapi.com/api/v4/social/limits' \  -H "Authorization: API $LISTINGSAPI_KEY"
Run in playground