Search loads only when you use it. Browse all categories below.

Accounts and workspaces

List connected accounts

List the social accounts (Instagram, Threads, Facebook, YouTube) connected to a Workspace, with connection health and capability facts. Use their ids as social_account_id when scheduling or commenting. Pass workspace_id: a request without it is refused once explicit targeting is enforced.

POST /identity-api/user/social-accounts/list

Contract reviewed: · sha256:563d2d581da0ad29

Overview

List the social accounts (Instagram, Threads, Facebook, YouTube) connected to a Workspace, with connection health and capability facts. Use their ids as social_account_id when scheduling or commenting. Pass workspace_id: a request without it is refused once explicit targeting is enforced.

A successful HTTP response can mean that a request was accepted rather than completed. For background work, save the returned ID and check the same operation until it finishes. A scheduled or accepted post is published only when the platform confirms it; a client timeout does not establish the result.

Authentication and permissions

Accepted credential classes
user_session, delegated_oauth, personal_access_token
Delegated capability
agent:operate
Minimum workspace role
No workspace-role minimum in this contract; ownership and grant checks still apply.
Access scope
Resources this user is authorized to access
All-workspace consent required
No
Changes state
No
When the operation is complete
synchronous_http_response

A token can use only the rights held by its owner. Each request checks workspace membership, resource ownership, selected workspaces and granted capabilities. Core and full profiles change which tools are displayed; they do not grant access.

Request fields

Required means required inside its parent object and selected branch. A required child does not make an optional parent required. Rules and field names below are copied from the contract.

Request fields
Field / branchType / requiredConstraints
$objectRequired in parent
  • additionalProperties: false
workspace_idstringOptional / item
  • format: "uuid"
  • pattern: "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
include_authorization_grantbooleanOptional / item—
Complete JSON Schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "workspace_id": {
      "type": "string",
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
    },
    "include_authorization_grant": {
      "type": "boolean"
    }
  },
  "additionalProperties": false
}

Response and completion

Success HTTP statuses: 200. When the operation is complete: synchronous_http_response.

A successful HTTP response can mean that a request was accepted rather than completed. For background work, save the returned ID and check the same operation until it finishes. A scheduled or accepted post is published only when the platform confirms it; a client timeout does not establish the result.

Required means required inside its parent object and selected branch. A required child does not make an optional parent required. Rules and field names below are copied from the contract.

Response and completion
Field / branchType / requiredConstraints
$objectRequired in parent—
accountsarrayRequired in parent—
accounts[]objectOptional / item—
accounts[].idstringRequired in parent
  • format: "uuid"
  • pattern: "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
accounts[].platformstringRequired in parent
  • enum: ["instagram","threads","facebook","tiktok","linkedin","youtube","x"]
accounts[].handlestring | nullRequired in parent—
accounts[].handleanyOf 1stringRequired in parent—
accounts[].handleanyOf 2nullRequired in parent—
accounts[].statusstringRequired in parent
  • enum: ["valid","expiring_soon","expired","disconnected"]
accounts[].expires_atstring | nullRequired in parent—
accounts[].expires_atanyOf 1stringRequired in parent—
accounts[].expires_atanyOf 2nullRequired in parent—
accounts[].created_atstringRequired in parent—
accounts[].avatar_urlstring | nullOptional / item—
accounts[].avatar_urlanyOf 1stringOptional / item—
accounts[].avatar_urlanyOf 2nullOptional / item—
accounts[].follower_countinteger | nullOptional / item—
accounts[].follower_countanyOf 1integerOptional / item
  • minimum: 0
  • maximum: 9007199254740991
accounts[].follower_countanyOf 2nullOptional / item—
accounts[].post_countinteger | nullOptional / item—
accounts[].post_countanyOf 1integerOptional / item
  • minimum: 0
  • maximum: 9007199254740991
accounts[].post_countanyOf 2nullOptional / item—
accounts[].auto_sync_enabledbooleanOptional / item—
accounts[].last_synced_atstring | nullOptional / item—
accounts[].last_synced_atanyOf 1stringOptional / item—
accounts[].last_synced_atanyOf 2nullOptional / item—
accounts[].workspace_idstring | nullOptional / item—
accounts[].workspace_idanyOf 1stringOptional / item
  • format: "uuid"
  • pattern: "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
accounts[].workspace_idanyOf 2nullOptional / item—
accounts[].platform_user_idstring | nullOptional / item—
accounts[].platform_user_idanyOf 1stringOptional / item
  • minLength: 1
accounts[].platform_user_idanyOf 2nullOptional / item—
accounts[].instagram_login_modestring | nullOptional / item—
accounts[].instagram_login_modeanyOf 1stringOptional / item
  • enum: ["instagram_login","facebook_login"]
accounts[].instagram_login_modeanyOf 2nullOptional / item—
accounts[].facebook_page_idstring | nullOptional / item—
accounts[].facebook_page_idanyOf 1stringOptional / item
  • minLength: 1
accounts[].facebook_page_idanyOf 2nullOptional / item—
accounts[].blocked_untilstring | nullOptional / item—
accounts[].blocked_untilanyOf 1stringOptional / item—
accounts[].blocked_untilanyOf 2nullOptional / item—
accounts[].block_reasonstring | nullOptional / item—
accounts[].block_reasonanyOf 1stringOptional / item
  • enum: ["transient","account_block","auth_invalid","permanent"]
accounts[].block_reasonanyOf 2nullOptional / item—
accounts[].block_subcodeinteger | nullOptional / item—
accounts[].block_subcodeanyOf 1integerOptional / item
  • minimum: -9007199254740991
  • maximum: 9007199254740991
accounts[].block_subcodeanyOf 2nullOptional / item—
accounts[].block_countintegerOptional / item
  • minimum: 0
  • maximum: 9007199254740991
accounts[].last_block_atstring | nullOptional / item—
accounts[].last_block_atanyOf 1stringOptional / item—
accounts[].last_block_atanyOf 2nullOptional / item—
accounts[].health_statestringRequired in parent
  • enum: ["ready","action_required","temporarily_unavailable","publishing_restricted","disconnected","unknown"]
accounts[].health_messagestringRequired in parent
  • minLength: 1
  • maxLength: 500
accounts[].health_observed_atstring | nullRequired in parent—
accounts[].health_observed_atanyOf 1stringRequired in parent—
accounts[].health_observed_atanyOf 2nullRequired in parent—
accounts[].authorization_grantobjectOptional / item—
accounts[].authorization_grantoneOf 1objectOptional / item—
accounts[].authorization_grant.granted_permissionsoneOf 1arrayRequired in parent—
accounts[].authorization_grant.granted_permissions[]oneOf 1stringOptional / item
  • minLength: 1
accounts[].authorization_grant.inventory_sourceoneOf 1stringRequired in parent
  • enum: ["oauth_token_response","provider_token_debug","provider_permissions_endpoint"]
accounts[].authorization_grant.inventory_exactoneOf 1booleanRequired in parent
  • const: true
accounts[].authorization_grant.observed_atoneOf 1stringRequired in parent
  • minLength: 1
accounts[].authorization_grant.provider_api_versiononeOf 1stringRequired in parent
  • minLength: 1
  • maxLength: 40
accounts[].authorization_grant.oauth_provideroneOf 1stringRequired in parent
  • enum: ["instagram","threads","meta","google"]
accounts[].authorization_grant.oauth_subject_idoneOf 1stringRequired in parent
  • minLength: 1
accounts[].authorization_grantoneOf 2objectOptional / item—
accounts[].authorization_grant.granted_permissionsoneOf 2arrayRequired in parent
  • minItems: 0
  • maxItems: 0
accounts[].authorization_grant.granted_permissions[]oneOf 2any JSON valueOptional / item—
accounts[].authorization_grant.inventory_sourceoneOf 2stringRequired in parent
  • const: "unavailable"
accounts[].authorization_grant.inventory_exactoneOf 2booleanRequired in parent
  • const: false
accounts[].authorization_grant.observed_atoneOf 2nullRequired in parent—
accounts[].authorization_grant.provider_api_versiononeOf 2nullRequired in parent—
accounts[].authorization_grant.oauth_provideroneOf 2string | nullRequired in parent—
accounts[].authorization_grant.oauth_provideroneOf 2 / anyOf 1stringRequired in parent
  • enum: ["instagram","threads","meta","google"]
accounts[].authorization_grant.oauth_provideroneOf 2 / anyOf 2nullRequired in parent—
accounts[].authorization_grant.oauth_subject_idoneOf 2string | nullRequired in parent—
accounts[].authorization_grant.oauth_subject_idoneOf 2 / anyOf 1stringRequired in parent
  • minLength: 1
accounts[].authorization_grant.oauth_subject_idoneOf 2 / anyOf 2nullRequired in parent—
accounts[].current_capability_snapshot_idstring | nullRequired in parent—
accounts[].current_capability_snapshot_idanyOf 1stringRequired in parent
  • format: "uuid"
  • pattern: "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
accounts[].current_capability_snapshot_idanyOf 2nullRequired in parent—
accounts[].capability_factsarrayRequired in parent—
accounts[].capability_facts[]objectOptional / item—
accounts[].capability_facts[].capabilitystringRequired in parent
  • enum: ["can_publish_text","can_publish_image","can_publish_video","can_publish_reel","can_publish_carousel","can_publish_first_comment","can_publish_topic_tag","can_publish_link","can_upload_video","can_set_title","can_set_description","can_set_thumbnail","can_set_privacy_status","can_publish_story","can_invite_collaborators","can_tag_products","can_publish_trial_reel","can_publish_partnership","can_delete_media","can_publish_reply","can_quote_post","can_repost","can_publish_poll","can_publish_gif","can_publish_text_attachment","can_publish_ghost_post","can_tag_location","can_crossshare_to_instagram","can_auto_publish_text","can_delete_post","can_publish_multi_image","can_target_post","can_backdate_post","can_manage_native_schedule","can_update_video","can_delete_video","can_set_brand_partner"]
accounts[].capability_facts[].observed_allowedboolean | nullRequired in parent—
accounts[].capability_facts[].observed_allowedanyOf 1booleanRequired in parent—
accounts[].capability_facts[].observed_allowedanyOf 2nullRequired in parent—
accounts[].capability_facts[].availabilitystringRequired in parent
  • enum: ["available","unavailable","unknown","documented_ambiguous"]
accounts[].capability_facts[].reason_codestringRequired in parent
  • pattern: "^[a-z0-9_]+$"
accounts[].capability_facts[].observed_atstringRequired in parent—
accounts[].capability_facts[].valid_untilstringRequired in parent—
accounts[].capability_facts[].provider_api_versionstringRequired in parent
  • minLength: 1
  • maxLength: 40
accounts[].capability_facts[].required_permissionsarrayRequired in parent—
accounts[].capability_facts[].required_permissions[]stringOptional / item
  • minLength: 1
accounts[].capability_facts[].granted_permissionsarrayRequired in parent—
accounts[].capability_facts[].granted_permissions[]stringOptional / item
  • minLength: 1
accounts[].capability_facts[].account_eligibilityobjectRequired in parent
  • additionalProperties: {}
accounts[].capability_facts[].account_eligibility.*any JSON valueOptional / item—
Complete JSON Schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "accounts": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
          },
          "platform": {
            "type": "string",
            "enum": [
              "instagram",
              "threads",
              "facebook",
              "tiktok",
              "linkedin",
              "youtube",
              "x"
            ]
          },
          "handle": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ]
          },
          "status": {
            "type": "string",
            "enum": [
              "valid",
              "expiring_soon",
              "expired",
              "disconnected"
            ]
          },
          "expires_at": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ]
          },
          "created_at": {
            "type": "string"
          },
          "avatar_url": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ]
          },
          "follower_count": {
            "anyOf": [
              {
                "type": "integer",
                "minimum": 0,
                "maximum": 9007199254740991
              },
              {
                "type": "null"
              }
            ]
          },
          "post_count": {
            "anyOf": [
              {
                "type": "integer",
                "minimum": 0,
                "maximum": 9007199254740991
              },
              {
                "type": "null"
              }
            ]
          },
          "auto_sync_enabled": {
            "type": "boolean"
          },
          "last_synced_at": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ]
          },
          "workspace_id": {
            "anyOf": [
              {
                "type": "string",
                "format": "uuid",
                "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
              },
              {
                "type": "null"
              }
            ]
          },
          "platform_user_id": {
            "anyOf": [
              {
                "type": "string",
                "minLength": 1
              },
              {
                "type": "null"
              }
            ]
          },
          "instagram_login_mode": {
            "anyOf": [
              {
                "type": "string",
                "enum": [
                  "instagram_login",
                  "facebook_login"
                ]
              },
              {
                "type": "null"
              }
            ]
          },
          "facebook_page_id": {
            "anyOf": [
              {
                "type": "string",
                "minLength": 1
              },
              {
                "type": "null"
              }
            ]
          },
          "blocked_until": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ]
          },
          "block_reason": {
            "anyOf": [
              {
                "type": "string",
                "enum": [
                  "transient",
                  "account_block",
                  "auth_invalid",
                  "permanent"
                ]
              },
              {
                "type": "null"
              }
            ]
          },
          "block_subcode": {
            "anyOf": [
              {
                "type": "integer",
                "minimum": -9007199254740991,
                "maximum": 9007199254740991
              },
              {
                "type": "null"
              }
            ]
          },
          "block_count": {
            "type": "integer",
            "minimum": 0,
            "maximum": 9007199254740991
          },
          "last_block_at": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ]
          },
          "health_state": {
            "type": "string",
            "enum": [
              "ready",
              "action_required",
              "temporarily_unavailable",
              "publishing_restricted",
              "disconnected",
              "unknown"
            ]
          },
          "health_message": {
            "type": "string",
            "minLength": 1,
            "maxLength": 500
          },
          "health_observed_at": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ]
          },
          "authorization_grant": {
            "oneOf": [
              {
                "type": "object",
                "properties": {
                  "granted_permissions": {
                    "type": "array",
                    "items": {
                      "type": "string",
                      "minLength": 1
                    }
                  },
                  "inventory_source": {
                    "type": "string",
                    "enum": [
                      "oauth_token_response",
                      "provider_token_debug",
                      "provider_permissions_endpoint"
                    ]
                  },
                  "inventory_exact": {
                    "type": "boolean",
                    "const": true
                  },
                  "observed_at": {
                    "type": "string",
                    "minLength": 1
                  },
                  "provider_api_version": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 40
                  },
                  "oauth_provider": {
                    "type": "string",
                    "enum": [
                      "instagram",
                      "threads",
                      "meta",
                      "google"
                    ]
                  },
                  "oauth_subject_id": {
                    "type": "string",
                    "minLength": 1
                  }
                },
                "required": [
                  "granted_permissions",
                  "inventory_source",
                  "inventory_exact",
                  "observed_at",
                  "provider_api_version",
                  "oauth_provider",
                  "oauth_subject_id"
                ]
              },
              {
                "type": "object",
                "properties": {
                  "granted_permissions": {
                    "minItems": 0,
                    "maxItems": 0,
                    "type": "array",
                    "items": {
                      "not": {}
                    }
                  },
                  "inventory_source": {
                    "type": "string",
                    "const": "unavailable"
                  },
                  "inventory_exact": {
                    "type": "boolean",
                    "const": false
                  },
                  "observed_at": {
                    "type": "null"
                  },
                  "provider_api_version": {
                    "type": "null"
                  },
                  "oauth_provider": {
                    "anyOf": [
                      {
                        "type": "string",
                        "enum": [
                          "instagram",
                          "threads",
                          "meta",
                          "google"
                        ]
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "oauth_subject_id": {
                    "anyOf": [
                      {
                        "type": "string",
                        "minLength": 1
                      },
                      {
                        "type": "null"
                      }
                    ]
                  }
                },
                "required": [
                  "granted_permissions",
                  "inventory_source",
                  "inventory_exact",
                  "observed_at",
                  "provider_api_version",
                  "oauth_provider",
                  "oauth_subject_id"
                ]
              }
            ]
          },
          "current_capability_snapshot_id": {
            "anyOf": [
              {
                "type": "string",
                "format": "uuid",
                "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
              },
              {
                "type": "null"
              }
            ]
          },
          "capability_facts": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "capability": {
                  "type": "string",
                  "enum": [
                    "can_publish_text",
                    "can_publish_image",
                    "can_publish_video",
                    "can_publish_reel",
                    "can_publish_carousel",
                    "can_publish_first_comment",
                    "can_publish_topic_tag",
                    "can_publish_link",
                    "can_upload_video",
                    "can_set_title",
                    "can_set_description",
                    "can_set_thumbnail",
                    "can_set_privacy_status",
                    "can_publish_story",
                    "can_invite_collaborators",
                    "can_tag_products",
                    "can_publish_trial_reel",
                    "can_publish_partnership",
                    "can_delete_media",
                    "can_publish_reply",
                    "can_quote_post",
                    "can_repost",
                    "can_publish_poll",
                    "can_publish_gif",
                    "can_publish_text_attachment",
                    "can_publish_ghost_post",
                    "can_tag_location",
                    "can_crossshare_to_instagram",
                    "can_auto_publish_text",
                    "can_delete_post",
                    "can_publish_multi_image",
                    "can_target_post",
                    "can_backdate_post",
                    "can_manage_native_schedule",
                    "can_update_video",
                    "can_delete_video",
                    "can_set_brand_partner"
                  ]
                },
                "observed_allowed": {
                  "anyOf": [
                    {
                      "type": "boolean"
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "availability": {
                  "type": "string",
                  "enum": [
                    "available",
                    "unavailable",
                    "unknown",
                    "documented_ambiguous"
                  ]
                },
                "reason_code": {
                  "type": "string",
                  "pattern": "^[a-z0-9_]+$"
                },
                "observed_at": {
                  "type": "string"
                },
                "valid_until": {
                  "type": "string"
                },
                "provider_api_version": {
                  "type": "string",
                  "minLength": 1,
                  "maxLength": 40
                },
                "required_permissions": {
                  "type": "array",
                  "items": {
                    "type": "string",
                    "minLength": 1
                  }
                },
                "granted_permissions": {
                  "type": "array",
                  "items": {
                    "type": "string",
                    "minLength": 1
                  }
                },
                "account_eligibility": {
                  "type": "object",
                  "propertyNames": {
                    "type": "string"
                  },
                  "additionalProperties": {}
                }
              },
              "required": [
                "capability",
                "observed_allowed",
                "availability",
                "reason_code",
                "observed_at",
                "valid_until",
                "provider_api_version",
                "required_permissions",
                "granted_permissions",
                "account_eligibility"
              ]
            }
          }
        },
        "required": [
          "id",
          "platform",
          "handle",
          "status",
          "expires_at",
          "created_at",
          "health_state",
          "health_message",
          "health_observed_at",
          "current_capability_snapshot_id",
          "capability_facts"
        ]
      }
    }
  },
  "required": [
    "accounts"
  ]
}

Errors and safe retries

Check the HTTP status and response body. A 400 validation error may contain a ZodError; handler errors use error, message and code fields. Keep request_id or x-request-id for diagnosis, without credentials. Fix 401/403 access errors before retrying, and follow Retry-After for 429. If a write is uncertain or returns 5xx, read the existing result first. Reuse an idempotency key only where supported; retry behaviour varies by operation and does not guarantee exactly-once delivery.

Troubleshooting guide

Examples

These examples use fictional values checked against the schemas. Replace the IDs with ones you are authorized to use, the media with ready assets and the dates with your confirmed publishing time. Check the account’s eligibility before submitting a write. This page sends no API requests.

Set SOSOAPI_ACCESS_TOKEN on your server to a credential accepted by this operation, and keep it out of browser code. For an agent, use sosoapi auth login to sign in through the browser and let the CLI refresh its credentials.

request.json

{}

cURL

curl --request POST \
  "https://gqeshlawtcexsapabaui.supabase.co/functions/v1/identity-api/user/social-accounts/list" \
  -H "Authorization: Bearer $SOSOAPI_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  --data-binary @request.json

JavaScript

// Server-side JavaScript. Do not print tokens or credential-bearing responses.
const token = process.env.SOSOAPI_ACCESS_TOKEN;
if (!token) throw new Error("Set an accepted credential for this operation");
const response = await fetch("https://gqeshlawtcexsapabaui.supabase.co/functions/v1/identity-api/user/social-accounts/list", {
  method: "POST",
  headers: { "Content-Type": "application/json", Authorization: "Bearer " + token },
  body: JSON.stringify({})
});
const result = await response.json();
// Check response.ok, the operation-specific body and completion state before continuing.

CLI

npx sosoapi api post /identity-api/user/social-accounts/list < request.json

Synthetic response example

{
  "accounts": []
}

MCP: sosoapi_list_connected_accounts