Listings APIListings API
サインイン

Social

client.socialを通じてブランドを管理し、ソーシャルアカウントを接続し、Facebook、Instagram、X、LinkedIn、Pinterestへの投稿を公開または予約します。

Social のすべてのメソッドは client.social 配下にあり、4 つの名前空間と 1 つのトップレベル呼び出しに分かれています。

名前空間管理対象
client.social.brandsブランド：接続済みアカウントと投稿を所有するコンテナ
client.social.connectionsブランドに紐づくSocialアカウント
client.social.posts個別の投稿：下書き、予約、公開、キャンセル、インサイト
client.social.bulk1 回のリクエストで非同期ジョブとして処理する複数の投稿
client.social.limits()接続数の上限と現在の使用数

ID、プラットフォーム、ステータス

ブランド、投稿、接続の ID は、通常の UUID 文字列です。拠点 ID とは異なり、Base64 でエンコードされることはなく、SDK も変換しません。

プラットフォームには、大文字の列挙値 FACEBOOK、INSTAGRAM、TWITTER（X を指します）、LINKEDIN、PINTEREST を使用します。投稿のステータスは DRAFT、PENDING、SCHEDULED、PUBLISHED、FAILED、ARCHIVED、REJECTED で、チャネルごとのステータスは SCHEDULED、SUCCESS、ERROR、ARCHIVED です。

すべての書き込み操作は success フラグを返します

Social の書き込み操作では、検証の失敗を 200 レスポンス内で success: false として報告し、その理由を error に格納します。SDK は通信エラーや認識可能なエラーペイロードに対して例外を発生させますが、success を自分で確認する習慣をつけてください。

Python
result = client.social.brands.create(profile_name="Jenny Home", timezone=tz)if not result.success:  raise RuntimeError(result.error.message)

公開処理は非同期です

action="PUBLISH" は投稿を受け付け、その id を返します。social.posts.retrieve() をポーリングし、connectedChannels[] からチャネルごとの status、liveLink、error を確認してください。同じ呼び出しでも、あるプラットフォームでは投稿に成功し、別のプラットフォームでは失敗する場合があります。

social.brands.create

ブランドを作成します。必須なのは profile_name と timezone のみです。

Python
client.social.brands.create(    *,    profile_name: str,    timezone: dict,    business_intent: str | None = None,    categories: list[str] | None = None,    site_url: str | None = None,    logo: str | None = None,    country_iso: str | None = None,    bio: str | None = None,    brand_hashtags: list[str] | None = None,    competitor_hashtags: list[str] | None = None,    content_preferred_language: str | None = None,) -> APIObject
引数型説明
profile_namestrブランドの表示名です。必須です。
timezonedict{"label", "tzCode", "name", "utc"}。tzCode は、このブランドのすべての schedule_date / schedule_time を解釈する際に使用する IANA タイムゾーンです。必須です。
business_intentstrコンテンツの提案に使用する事業内容です。デフォルトは general です。
categorieslist[str]事業のカテゴリです。デフォルトは空のリストです。
site_urlstrブランドのウェブサイトです。設定すると、サイトの読み取りがキューに追加されます。
logostrブランドロゴの公開 https URL です。
country_isostr2 文字の ISO 国コードです。
biostrブランドの簡単な紹介文です。
brand_hashtagslist[str]投稿作成画面で候補として表示するハッシュタグです。
competitor_hashtagslist[str]追跡する競合他社のハッシュタグです。
content_preferred_languagestr生成コンテンツの言語で、e.g です。en。
Python
result = client.social.brands.create(  profile_name="Jenny Home",  timezone={      "label": "(GMT-05:00) Eastern Time",      "tzCode": "America/New_York",      "name": "Eastern Standard Time",      "utc": "-05:00",  },  business_intent="A family-run home furnishings store selling handmade furniture.",  categories=["Furniture Store"],  site_url="https://jennyhome.example",)brand_id = result.socialProfile.id  # a plain UUID string

API プランではブランド数に制限がないため、この操作が上限を理由に失敗することはありません。使用数が計測されるのは接続です。social.limits() はブランドの作成前ではなく、接続リンクの発行前に確認してください。

social.brands.list

オフセット方式のページネーションでブランドを一覧取得します。フィルターを送信する場合、その中に statuses が必須です。

Python
client.social.brands.list(    *,    statuses: list[str] | None = None,    profile_name: str | None = None,    page: int | None = None,    size: int | None = None,) -> APIObject
Python
result = client.social.brands.list(page=1, size=25)for brand in result.profiles:  print(brand.id, brand.profileName, brand.connectedChannelCount)print(result.pageInfo.total, result.pageInfo.hasNextPage)

social.brands.retrieve

UUID を指定して 1 つのブランドを取得します。

Python
client.social.brands.retrieve(brand_id: str) -> APIObject
Python
brand = client.social.brands.retrieve("6f2c9a41-7b0e-4d55-9a2f-3c8e1d47b902")print(brand.profileName, brand.timezone.tzCode)

social.brands.update

ブランドを更新します。必須なのは profile_id のみで、変更するフィールドだけを送信してください。

Python
client.social.brands.update(    profile_id: str,    *,    profile_name: str | None = None,    timezone: dict | None = None,    business_intent: str | None = None,    categories: list[str] | None = None,    site_url: str | None = None,    logo: str | None = None,    country_iso: str | None = None,    bio: str | None = None,    brand_hashtags: list[str] | None = None,    competitor_hashtags: list[str] | None = None,    content_preferred_language: str | None = None,) -> APIObject

categories、brand_hashtags、competitor_hashtags を送信すると、保存済みのリストが置き換えられます。[] を渡すと、リストが空になります。

Python
client.social.brands.update(  "6f2c9a41-7b0e-4d55-9a2f-3c8e1d47b902",  profile_name="Jenny Home & Co.",)

social.brands.archive

ブランドとその接続をアーカイブします。ブランドの作成から 90 日以上経過している必要があります。

Python
client.social.brands.archive(social_profile_id: str) -> APIObject
Python
result = client.social.brands.archive("6f2c9a41-7b0e-4d55-9a2f-3c8e1d47b902")print(result.status)  # ARCHIVED or TENURE_NOT_MET

作成から 90 日未満のブランドの場合、success: False と status: "TENURE_NOT_MET" が返され、何も変更されません。この期間を満たしている場合、アーカイブは即時に実行されます。同じ呼び出しでブランドとそれに紐づくすべての接続がアーカイブされ、公開処理は直ちに停止しますが、手動で接続を解除した場合と同様に、請求サイクルが終了するまで接続枠は占有されたままになります。

エンドユーザーが 1 つのプラットフォームをブランドに接続する手順を進めるための、有効期間の短いホスト型 URL を発行します。ユーザーを url にリダイレクトしてください。

Python
client.social.connections.link(    brand_id: str,    *,    channel: str,    redirect_url: str,    error_url: str | None = None,    state: str | None = None,) -> APIObject
Python
link = client.social.connections.link(  "6f2c9a41-7b0e-4d55-9a2f-3c8e1d47b902",  channel="INSTAGRAM",  redirect_url="https://app.example.com/social/connected",  error_url="https://app.example.com/social/connect-failed",  state="sess_9f2c1e64",)print(link.url, link.expiresIn)

ユーザーは、status、brandId、platform、指定した state、および成功時には connectedAccountId が付加された redirect_url に戻ります。接続が実際に作成されるまで少し時間がかかるため、最初の読み取り結果が空でも失敗と判断せず、social.connections.list() を数秒間ポーリングしてください。Instagram では、Facebook ページに紐づくビジネスアカウントまたはクリエイターアカウントが必要です。

social.connections.list

ブランドに紐づくソーシャルアカウントを一覧取得します。

Python
client.social.connections.list(brand_id: str) -> APIObject
Python
result = client.social.connections.list("6f2c9a41-7b0e-4d55-9a2f-3c8e1d47b902")for channel in result.socialConnected:  print(channel.id, channel.platform, channel.displayName)print(result.channelCount)

channel.id は、他のすべての呼び出しで指定する接続 UUID です。referenceId はプラットフォーム独自のアカウント識別子で、入力としては一切受け付けられません。

social.connections.disconnect

接続を削除します。この操作は元に戻せず、復元するには新たに social.connections.link() が必要です。

Python
client.social.connections.disconnect(social_profile_connected_channel_id: str) -> APIObject
Python
client.social.connections.disconnect("b81d5b3c-4a90-4f6a-9c11-71e0dd2fa4a7")

そのチャネルを対象とする予約済みの投稿は、キャンセルされません。公開時に SY95045 で失敗します。先に social.posts.cancel() でキャンセルしてください。

social.posts.create

1 つのブランドについて、接続済みのチャネルにまたがる 1 件の投稿を作成します。

Python
client.social.posts.create(    *,    social_profile_id: str,    name: str,    platforms: list[str],    content: str,    action: str,    media_urls: list[str] | None = None,    video_urls: list[str] | None = None,    link: str | None = None,    scheduled_at: str | None = None,    schedule_date: str | None = None,    schedule_time: str | None = None,    connected_channel_ids: list[str] | None = None,    client_reference: str | None = None,) -> APIObject
引数型説明
social_profile_idstrブランドの UUID です。必須です。
namestr閲覧者には表示されない内部用の名前です。必須です。
platformslist[str]FACEBOOK、INSTAGRAM、TWITTER、LINKEDIN、PINTEREST。それぞれについて、そのブランドに接続がすでに存在している必要があります。必須です。
contentstr投稿の本文です。必須です。
actionstrDRAFT、SCHEDULE、または PUBLISH です。必須です。
media_urlslist[str]画像の公開 https URL です。Instagram と Pinterest では必須です。
video_urlslist[str]動画の公開 https URL です。
linkstrプラットフォームがリンクの添付に対応している場合に添付するリンクです。
scheduled_atstrオフセット付きの ISO-8601 形式です。日付と時刻の組み合わせの代わりに使用します。
schedule_datestrYYYY-MM-DD で、ブランドのタイムゾーンで解釈されます。schedule_time と一緒に送信してください。
schedule_timestrHH:MM で、ブランドのタイムゾーンで解釈されます。schedule_date と一緒に送信してください。
connected_channel_idslist[str]特定の接続に制限します。
client_referencestr独自の識別子で、一括処理ジョブの結果にそのまま返されます。

action="SCHEDULE" では、scheduled_at または schedule_date + schedule_time のいずれか 1 つの形式で予約日時を指定する必要があります。両方を送信すると、SY95046 で拒否されます。

Python
result = client.social.posts.create(  social_profile_id="6f2c9a41-7b0e-4d55-9a2f-3c8e1d47b902",  name="Autumn collection launch",  platforms=["INSTAGRAM", "FACEBOOK"],  content="Our autumn collection lands today. Solid oak, hand-finished.",  media_urls=["https://cdn.example.com/social/autumn.jpg"],  action="SCHEDULE",  schedule_date="2026-10-02",  schedule_time="09:30",)print(result.success, result.socialPostId)

social.posts.retrieve

チャネルごとの公開状態を含む 1 件の投稿を取得します。作成後にこれをポーリングしてください。

Python
client.social.posts.retrieve(post_id: str) -> APIObject
Python
post = client.social.posts.retrieve("c47a1e58-2b93-4f10-a6d7-58e0c9b12345")print(post.status)for channel in post.connectedChannels:  print(channel.platform, channel.status, channel.liveLink, channel.error)

social.posts.list

フィルターを指定し、オフセット方式のページネーションでブランドの投稿を一覧取得します。

Python
client.social.posts.list(    brand_id: str,    *,    filters: dict | None = None,    page: int | None = None,    size: int | None = None,    fetch_post_content: bool | None = None,) -> APIObject

filters は、name、platforms、status、start_date、end_date、social_connected_channel_id、approval_state、view_mode、filter_by_user を受け付けます。

Python
result = client.social.posts.list(  "6f2c9a41-7b0e-4d55-9a2f-3c8e1d47b902",  filters={"status": ["SCHEDULED"], "startDate": "2026-10-01", "endDate": "2026-10-31"},  page=1,  size=50,)for post in result.socialPosts:  print(post.socialPostId, post.name, post.status)print(result.pageInfo.total)

social.posts.cancel

予約済みまたは下書きの投稿をキャンセルし、公開されないようにします。

Python
client.social.posts.cancel(social_post_id: str) -> APIObject
Python
client.social.posts.cancel("c47a1e58-2b93-4f10-a6d7-58e0c9b12345")

公開済みの投稿はキャンセルできず、どのプラットフォームからも削除されません。そのような投稿に対して、この呼び出しは success: False を返します。

social.posts.insights

1 つのチャネルで公開済みの 1 件の投稿に対するエンゲージメントとコメントです。両方のフィールドは、プラットフォーム独自のペイロードを含む JSON 文字列として返されます。

Python
client.social.posts.insights(    post_id: str,    *,    social_connected_channel_id: str,) -> APIObject
Python
import json result = client.social.posts.insights(  "c47a1e58-2b93-4f10-a6d7-58e0c9b12345",  social_connected_channel_id="b81d5b3c-4a90-4f6a-9c11-71e0dd2fa4a7",)insights = json.loads(result.insights)comments = json.loads(result.comments)print(insights.get("impressions"), len(comments))

内部のキーはプラットフォーム独自のもので、プラットフォームごとに異なるため、キーの有無や値の形式を確認しながら読み取ってください。

social.bulk.create

1 回のリクエストで最大 500 件の投稿を検証し、キューに追加します。行ごとに異なるブランドを対象にできます。

Python
client.social.bulk.create(    posts: list[dict],    *,    name: str | None = None,) -> APIObject

各行は、social.posts.create と同じフィールドを camelCase 形式で受け付けます。1 行でも無効な行がある場合、何も作成されません。success は False になり、error に SY95050 が返され、job.results[] には各無効行の 0 始まりの index とその clientReference が示されます。

Python
result = client.social.bulk.create([  {      "socialProfileId": "6f2c9a41-7b0e-4d55-9a2f-3c8e1d47b902",      "name": "Autumn week 1",      "platforms": ["INSTAGRAM", "FACEBOOK"],      "content": "Week one of the autumn collection.",      "mediaUrls": ["https://cdn.example.com/social/autumn-w1.jpg"],      "action": "SCHEDULE",      "scheduleDate": "2026-10-02",      "scheduleTime": "09:30",      "clientReference": "campaign-4471-slot-01",  },])if not result.success:  for row in result.job.results:      print(row.index, row.clientReference, row.errors)else:  job_id = result.job.id

social.bulk.retrieve

ステータスが最終状態になるまで、一括処理ジョブをポーリングします。

Python
client.social.bulk.retrieve(bulk_job_id: str) -> APIObject
Python
job = client.social.bulk.retrieve("9b3f18d0-7a26-4c51-8e94-1f0d5c6b7a82")print(job.status, job.processedCount, "/", job.totalCount)for row in job.results:  print(row.clientReference, row.status, row.socialPostId)

status は、QUEUED、PROCESSING、COMPLETED、COMPLETED_WITH_ERRORS、または FAILED です。行が CREATED に達した場合、その投稿が存在することを意味し、公開済みであることは意味しません。socialPostId を social.posts.retrieve() に渡して、チャネルごとの結果を確認してください。

social.limits

1 回の呼び出しで、接続数の上限と現在の使用数を取得します。

Python
client.social.limits() -> APIObject
Python
limits = client.social.limits()print(limits.maxConnections, limits.usage.connections)     # pool vs usedprint(limits.brands)                                       # None — brands are unlimitedprint(limits.usage.brands)                                 # brands that exist, uncapped

接続枠はブランドごとの割り当てではなく、アカウント全体で共有されます。Social Launch では 20、Social Growth では 125 で、月額 $25 の接続パックごとに 5 が追加されます。SY95042 の代わりにアップグレード方法を表示できるよう、接続リンクを発行する前に確認してください。すべての API プランで、limits.brands は None です。

関連情報