ai.social-api/socialapi

Initiate connecting a new social media account. For OAuth2 platforms (instagram, facebook) returns an auth_url the user must visit to authorize access. After authorization, the account is connected automatically — no follow-up call needed. Present the auth_url link to the user and ask them to let you know once they've completed the authorization. For direct-auth platforms, stores credentials immediately and returns the new account_id.

Create a new brand to group social accounts for a business, client, or project. Each brand can connect one account per platform. The number of brands is limited by your plan tier.

Create an analytics export for a connected account. Enqueues an async job that collects post data, engagement metrics, and optionally video transcripts and AI vision analysis into a downloadable Excel report and shareable report page. Subject to plan limits: exports per month, cooldown hours between exports for the same account, and max one concurrent export. Use social_api_get_export to poll for completion. Free plan: 2 exports/mo, 7-day cooldown, 30 videos max. Paid plans have higher limits.

Create a platform invite link for a brand. The invite allows someone to connect a social media account to the brand via a one-time URL. expires_in_days must be one of: 1, 3, 7, 14, 30 (defaults to 7). Returns the invite token and shareable URL.

Generate a new API key (prefixed sapi_key_) for programmatic API access. The raw key is returned exactly once in the response and cannot be retrieved later -- store it securely immediately. All keys for a user share the same monthly quota pool. Provide a descriptive name to identify the key's purpose later.

Create or schedule a post to one or more connected social media accounts. Omit targets and scheduled_at to create a draft. Provide targets to publish; omit scheduled_at for immediate publish, or provide an RFC3339 timestamp to schedule. Attach media by first uploading via social_api_get_media_upload_url, verifying with social_api_verify_media_upload, then passing the media_ids here. Consumes 1 post credit.

Register a new webhook endpoint to receive real-time event notifications. The URL must be HTTPS. Specify which event types to subscribe to (comment.received, dm.received, review.received, mention.received, post.published, post.failed, post.scheduled). The signing secret is returned once -- store it securely to verify payload signatures (HMAC-SHA256).

Delete a brand and disconnect all its connected social accounts. This is irreversible.

Permanently delete a comment from the platform and remove it from the inbox database. This action is irreversible. Supported on Instagram, Facebook, and YouTube.

Permanently delete the authenticated user account and ALL associated data including API keys, connected social accounts, usage logs, webhook endpoints, and OAuth consents. This action is completely irreversible -- all API keys for this user stop working immediately. Confirm the user's intent explicitly before calling this tool.

Permanently delete a media file from the media library and object storage. This is irreversible. If the media is referenced by any post, the post will lose that attachment. Use social_api_list_media to find the media_id.

Delete a published post from the social media platform, or cancel a scheduled/failed post before it is published. For published posts, this removes the post from the platform (irreversible). Provide the post_id.

Delete a business reply to a review. Requires account_id and the platform review_id. Supported on Google Business. Returns 501 for platforms that do not support deleting review replies. This action is irreversible.

Permanently delete a webhook endpoint. Future events will no longer be delivered to this URL. Any in-flight deliveries may still complete. This is irreversible. Use social_api_list_webhooks to find the webhook_id.

Disconnect a connected social media account. Removes the stored OAuth tokens and disassociates the account from the user. Any scheduled posts targeting this account will fail on publish. This is irreversible — to reconnect, use social_api_connect_account again. Use social_api_list_accounts to find the account_id.

Get aggregated event counts for a time window. Returns total events, failure count broken down by error category, counts by event category (post, inbox, account, api, webhook), inbox breakdown (comment vs DM vs mention), and the plan's retention window in days. Use to check system health, recent failures, or inbox activity volume.

Complete an OAuth2 account connection by exchanging the authorization code received after the user authorized access. Requires platform, the authorization code, and metadata including redirect_uri and state (from social_api_connect_account). For Facebook, a single user token may yield multiple Page accounts.

Get platform-specific API usage limits and quotas for a connected account, as reported by the platform itself (e.g., Instagram daily posting limits). Returns a map of quota keys to remaining counts. Not all platforms expose usage limits -- returns 501 for Facebook and platforms that do not provide this data. These are the platform's own rate limits, separate from SocialAPI billing quotas.

List replies to a specific comment. The interaction_id must be a comment ID starting with sapi_cmt_ (from social_api_get_comments). Returns reply interaction objects in the same format. Supports pagination via cursor and since filter. Max 100 results (default 20). Supported on Instagram and Facebook.

Get platform-specific content constraints for post creation. Returns per-platform limits including max text length, max media count, supported media types, max file sizes, aspect ratio requirements, and video duration limits. Use before creating a post to validate content will be accepted.

Get details for a single DM conversation including participant info, unread count, status (active/archived), and last message preview. The conversation_id comes from social_api_list_conversations.

Fetch creator-facing profile details for a connected account: display name, username, profile picture, bio, follower/following counts, and platform-specific publishing capabilities (e.g. TikTok privacy levels, duet/stitch permissions). Use this before building a post UI so defaults and options match what the platform allows for this account. Use social_api_list_accounts to find the account_id.

Get the status and result of an analytics export. Returns status (pending, processing, completed, failed), progress (total_videos, processed_videos), and for completed exports: a presigned Excel download URL (valid 15 minutes) and a shareable report page URL. Poll this after social_api_create_export to check completion.

Get the cached video data from a completed analytics export. Returns the full video array with per-video analytics (views, likes, comments, shares, duration, transcripts, vision analysis). The export must be in 'completed' status. Use social_api_get_export to check status first.

Get the authenticated user's profile. Returns id (UUID), email, plan tier (free, starter, pro, business, or enterprise), onboarding status (true if onboarding is incomplete), and avatar_url. Use this to check the current plan tier before performing plan-gated operations.

Get a presigned S3-compatible URL for uploading a media file to attach to a post. Provide the MIME type (e.g., image/jpeg, image/png, video/mp4) and the original filename. Upload workflow: (1) call this tool to get upload_url and media_id, (2) upload the file to the upload_url using a PUT request with the file bytes as body and Content-Type header matching the media_type (e.g. via curl: curl -X PUT -H 'Content-Type: image/jpeg' --data-binary @photo.jpg '<upload_url>'), (3) call social_api_verify_media_upload with the media_id, (4) pass the media_id to social_api_create_post in media_ids. The upload URL expires in 15 minutes.

List brand mentions and tags for a connected account -- posts by other users that mention or tag your account. Returns interaction objects with id (prefixed sapi_mnt_), author, text, media_url, and timestamp. Supported on Instagram (@mentions and tags) and Facebook (page mentions). Returns 501 for platforms without mention tracking. Supports pagination.

Get full details for a single post including text, status, scheduled/published timestamps, per-platform delivery details with engagement metrics (likes, comments, shares, saves), and media IDs. Use the post_id from social_api_list_posts or social_api_create_post.

Fetch live engagement metrics for a published post from each target platform. Returns per-platform metrics including like_count, comments_count, shares_count, saves_count, impressions, reach, and platform-specific extra_metrics. Triggers a real-time refresh from platform APIs.

List reviews across connected accounts (applicable to Google Business, Trustpilot, and similar review platforms). Fan-out queries all matching accounts in parallel. Returns review interaction objects with id, reviewer name, rating, text, and timestamp. Use social_api_reply_to_review to respond. Returns 501 for Instagram, Facebook, and platforms without review support. Supports account_id or platform filter and pagination.

Get storage usage and quota for the authenticated user's media library. Returns used_bytes, limit_bytes (-1 if unlimited), and file_count. Storage limits vary by plan: Free (100 MB), all paid plans (unlimited).

Get resource usage for the current billing period. Returns counts and limits for brands (brand slots), posts (create_post and retry_post operations), and interactions (reply and send_dm operations), plus period_start and period_end timestamps. Use before billed operations to check remaining quota. Free plan: 2 brands, 10 posts/mo, 50 interactions/mo. All paid plans (Starter, Pro, Business, Enterprise): unlimited posts and interactions. Brand limits vary by plan. -1 means unlimited.

Get details for a single webhook endpoint including URL, subscribed events, is_active status, a secret hint (last 4 chars only -- the full secret is returned once at creation), and delivery stats for the last 24 hours and last 7 days (delivered vs failed counts). Use social_api_list_webhooks to find the webhook_id.

Get full details of a single webhook delivery attempt: request payload, response body, response headers, HTTP status code, attempt count, and any error message. Use social_api_list_webhook_deliveries to find the delivery_id. Essential for diagnosing why a delivery failed.

Hide a comment from public view on the platform. The comment remains in the database but is marked hidden. Reversible — use social_api_unhide_comment to restore. Supported on Instagram, Facebook, and Threads.

Like a comment on behalf of the connected account. Supported on Facebook and Twitter. Returns 501 for platforms without like support.

List pages (e.g. Facebook Pages) for a connected account. Returns page IDs, names, default/active status. Use the returned page IDs as the page_id parameter in publishing and inbox tools.

List all connected social media accounts for the authenticated user. Returns account details including platform name, username, connection status, and platform-specific metadata (follower_count, video_count, avatar_url, etc.). Use the returned account IDs as the account_id parameter in all other tools.

List all brands for the authenticated user. Each brand groups social accounts for one business, client, or project. Returns brand id, name, connected accounts count, and timestamps.

List inbox DM conversations for the authenticated user, sorted by most recently active. Optionally filter by connected account, platform, or status (active/archived). Returns conversation objects with id, participant name/picture, last message preview, and unread count. Supports pagination via cursor. Max 100 results (default 25). Supported on Instagram and Facebook (Messenger).

List developer events (unified activity log). Filter by category (post, webhook, inbox, api, account), status, platform, action, account, or resource. Shows publishing attempts, webhook deliveries, inbound platform events, API calls, and account lifecycle events. Sorted newest first.

List the 50 most recent analytics exports for the authenticated user, newest first. Optionally filter by status (pending, processing, completed, failed). Returns export ID, account, platform, status, progress, and timestamps.

List inbox posts (posts that have received comments) for the authenticated user. Optionally filter by account, platform, minimum comment count, or updated-since timestamp. Sorted newest first by default (sort_by=date). Use social_api_list_post_comments to fetch comments for a specific post. Supports pagination via cursor. Max 100 results (default 25).

List all platform invites for a brand, ordered by creation date (newest first). Returns both active and expired/used invites. Use is_active to filter in the response.

List all API keys for the authenticated user. Returns key metadata including id, name, preview (first characters of the key), is_active status, last_used_at timestamp, and created_at. The full key value is never shown after creation. Use this to audit active keys or find a key_id for revocation.

List uploaded media files in the user's media library. Returns media objects with id, filename, content_type, size_bytes, status (pending/ready), and created_at. Use media IDs from here or from social_api_get_media_upload_url when creating posts. Supports pagination via cursor.

List messages in a DM conversation, sorted newest first. The conversation_id comes from social_api_list_conversations. Returns message objects with id, direction (incoming/outgoing), text, sender info, and timestamp. Supports pagination via cursor. Max 200 results (default 50).

List comments for a specific inbox post, sorted oldest-first. The inbox_post_id comes from social_api_list_inbox_posts. Requires the account_id that owns the post. Returns comment objects with text, author info, like_count, reply_count, is_hidden, and is_liked flags. Supports pagination via cursor. Max 100 results (default 25).

List all posts (drafts, scheduled, published, failed) with rich filtering. Supports filtering by status, platform, account_ids, date range, text search. Returns posts with per-platform delivery details and engagement metrics. Use cursor for pagination.

List recent delivery attempts for a webhook endpoint. Each delivery includes id, event_type, status (pending, delivered, failed), HTTP response code, attempt count, and timestamps. Filter by status or event_type. Keyset cursor pagination via the cursor field. Use this to debug failing webhook endpoints.