List Social Accounts

Retrieve connected social accounts for your workspace

Published ·Updated

GET
/v1/social/accounts
curl -X GET "https://api.orshot.com/v1/social/accounts" \
  -H "Authorization: Bearer <ORSHOT_API_KEY>"

List all connected social media accounts in your workspace. Use this to find account IDs for the publish parameter when rendering templates, or for the Publish to Social endpoint.

Multiple accounts from the same platform are returned as separate entries with different id values. Always store and publish with the account id, not only the platform name.

You can also find account IDs in the dashboard. Open Social Posting → Accounts, then use Copy ID in an account's ⋯ menu.

Endpoint#

GET /social/accounts#

Endpoint
https://api.orshot.com/v1/social/accounts

Request Example#

JavaScript
await fetch("https://api.orshot.com/v1/social/accounts", {
  method: "GET",
  headers: {
    Authorization: "Bearer <ORSHOT_API_KEY>",
  },
});

With Account Health#

Pass include_health=true to check if any accounts need reconnection (e.g., expired tokens).

JavaScript
await fetch("https://api.orshot.com/v1/social/accounts?include_health=true", {
  method: "GET",
  headers: {
    Authorization: "Bearer <ORSHOT_API_KEY>",
  },
});

Filter by Your Reference#

Accounts connected through a connect link carry the external_id you gave. Filter on it to find one person's account.

JavaScript
await fetch("https://api.orshot.com/v1/social/accounts?external_id=office_142", {
  method: "GET",
  headers: {
    Authorization: "Bearer <ORSHOT_API_KEY>",
  },
});

Response Example#

JSON
{
  "data": [
    {
      "id": 1,
      "platform": "twitter",
      "account_name": "Acme HQ",
      "account_username": "acmehq",
      "account_avatar": "https://pbs.twimg.com/profile_images/.../avatar.jpg",
      "connected_at": "2026-03-15T10:30:00.000Z",
      "external_id": null,
      "connect_source": null,
      "provider": "zernio"
    },
    {
      "id": 2,
      "platform": "linkedin",
      "account_name": "Acme Inc",
      "account_username": "acme-inc",
      "account_avatar": "https://media.licdn.com/.../avatar.jpg",
      "connected_at": "2026-03-16T14:00:00.000Z",
      "external_id": "office_142",
      "connect_source": "api",
      "provider": "zernio"
    }
  ]
}

Response Fields#

FieldTypeDescription
idIntegerAccount ID — use this in the publish.accounts array
platformStringPlatform name (twitter, instagram, linkedin, facebook, tiktok, youtube, pinterest, reddit, bluesky, threads, telegram, snapchat, googlebusiness, whatsapp, discord)
account_nameStringDisplay name of the account
account_usernameStringUsername/handle on the platform
account_avatarStringAvatar image URL
connected_atStringISO timestamp when the account was connected
requires_reconnectBooleanWhether the account needs reconnection (only with include_health=true)
external_idStringYour reference from the connect link that created the account, else null
connect_sourceStringapi or mcp for accounts connected through a connect link, null for the dashboard
providerStringThe publishing provider the account routes through (zernio)
limitsObjectX accounts only: link_posts (posts with a link this month: 25, 80 or 100 by plan) and posts_today (15 a day), each with used, limit, left and resets_at. See X limits

Rate Limits#

This endpoint is rate limited to 20 requests per minute per workspace. Rate limit headers are included in every response:

HeaderDescription
X-RateLimit-LimitMaximum requests per minute
X-RateLimit-RemainingRemaining requests in the current window
Retry-AfterSeconds to wait (only on 429 responses)

Error Responses#

CodeDescription
401Invalid or expired API key
403Missing Authorization header
429Rate limit exceeded
Was this page helpful?

Ready to automate?

Start rendering images, PDFs and videos from your templates in under 2 minutes. Free plan, no credit card.

Get your API key
  • Image, PDF and video generation via API
  • Visual editor with AI and smart layouts
  • Zapier, Make, MCP and 40+ integrations
  • White-label embed for your own app
  • 100 free credits a month, no credit card required