Python SDK Reference | SocialRails Documentation

Complete API reference for the socialrails Python package. All methods are available in both sync (SocialRails) and async (AsyncSocialRails) clients. Async examples use await — sync usage is identical without it.

Posts

`client.posts.create(...)`

post = client.posts.create(
    content="Check out our blog post!",
    platform="twitter",
    scheduled_for="2026-03-15T14:30:00Z",  # optional
    media=["workspace-id/api-uploads/images/uuid.jpg"],  # optional
    platform_settings={"selectedCommunities": ["12345"]},  # optional
)

Thread support (Twitter and Threads):

post = client.posts.create(
    content="Thread intro",
    platform="twitter",
    thread=["First tweet", "Second tweet", "Third tweet"],
    thread_delay=5,  # minutes between tweets
)

`client.posts.list(...)`

result = client.posts.list(
    status="scheduled",
    platform="twitter",
    sort="scheduled_for",
    from_date="2026-03-01",
    to_date="2026-03-31",
    limit=25,
    offset=0,
)

`client.posts.get(post_id)`

post = client.posts.get("550e8400-e29b-41d4-a716-446655440000")

`client.posts.update(post_id, ...)`

updated = client.posts.update(
    "550e8400-e29b-41d4-a716-446655440000",
    content="Updated content!",
    scheduled_for="2026-03-20T10:00:00Z",
)

`client.posts.delete(post_id)`

result = client.posts.delete("550e8400-e29b-41d4-a716-446655440000")
# {"id": "...", "deleted": True}

`client.posts.batch(...)`

result = client.posts.batch(
    content="Cross-platform announcement!",
    platforms=["twitter", "linkedin", "facebook"],
    scheduled_for="2026-03-15T14:30:00Z",
    platform_content={
        "twitter": "Short version for Twitter!",
        "linkedin": "Detailed professional version for LinkedIn.",
    },
)

Analytics

`client.analytics.get(...)`

# Aggregate analytics
analytics = client.analytics.get(period="30d")
print(analytics["total_posts"])
print(analytics["by_platform"])
 
# Filter by platform
analytics = client.analytics.get(platform="twitter", period="7d")
 
# Per-post analytics
post_analytics = client.analytics.get(post_id="550e8400-...")

Accounts

`client.accounts.list()`

accounts = client.accounts.list()
for account in accounts:
    print(f"{account['provider']}: {account['name']} ({account['status']})")

`client.accounts.get_settings(account_id)`

settings = client.accounts.get_settings("550e8400-...")
print(settings["capabilities"]["character_limit"])
print(settings["available_tools"])

`client.accounts.trigger_tool(account_id, tool)`

result = client.accounts.trigger_tool("550e8400-...", "pages")
for page in result["results"]:
    print(page)

AI

`client.ai.generate(...)`

result = client.ai.generate(
    prompt="Write a tweet about our new Python SDK launch",
    platform="twitter",
    tone="professional",
)
print(result["content"])

Workspace

`client.workspace.get()`

workspace = client.workspace.get()
print(f"Plan: {workspace['plan']}")
print(f"Posts this month: {workspace['usage']['posts_this_month']}")
print(f"Monthly limit: {workspace['limits']['max_posts_per_month']}")

Media

`client.media.upload(file, filename, ...)`

with open("photo.jpg", "rb") as f:
    media = client.media.upload(f, "photo.jpg")
print(media["key"])
 
# Upload a video thumbnail
with open("thumb.jpg", "rb") as f:
    thumb = client.media.upload(f, "thumb.jpg", media_type="thumbnail")

`client.media.upload_from_url(url, ...)`

media = client.media.upload_from_url(
    "https://example.com/image.jpg",
    media_type="image",
)
print(media["key"])

Webhooks

`client.webhooks.list()`

webhooks = client.webhooks.list()
for wh in webhooks:
    print(f"{wh['url']} -> {wh['events']}")

`client.webhooks.create(url, events)`

webhook = client.webhooks.create(
    url="https://example.com/webhook",
    events=["post.published", "post.failed"],
)
print(webhook["secret"])  # save this -- only shown once

`client.webhooks.delete(webhook_id)`

result = client.webhooks.delete("550e8400-...")