Accounts

List accounts

Return the social accounts connected to your project, with the IDs you use as post targets.

GET https://social-publish-api.onrender.com/v1/accounts

Returns every connected social account in the API key's project. Use an account's id as targets[].accountId when you create a post. Disconnected accounts are not returned; accounts that need reconnecting are returned with status: "reconnect_required".

Accounts are connected in the dashboard under Integrations, by your users through a connect link (OAuth platforms), or with Connect Bluesky.

Headers

Header	Required	Description
`x-access-key`	Yes*	Your API key. *Or send `Authorization: Bearer <key>`.

Query parameters

Parameter	Type	Required	Description
`groupId`	string (UUID)	No	Only return accounts in this social group. Copy a group's ID from Integrations → Groups. An invalid UUID returns `400 validation_error`.

All matching accounts are returned in one response (no pagination).

curl "https://social-publish-api.onrender.com/v1/accounts?groupId=b1a2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d"   -H "x-access-key: $RELAYCAST_API_KEY"

Request

cURLNode.jsPython

curl https://social-publish-api.onrender.com/v1/accounts \
  -H "x-access-key: $RELAYCAST_API_KEY"

const res = await fetch("https://social-publish-api.onrender.com/v1/accounts", {
  headers: { "x-access-key": process.env.RELAYCAST_API_KEY! },
});
const { data: accounts } = await res.json();
const active = accounts.filter((a: { status: string }) => a.status === "active");

import os, requests

res = requests.get(
    "https://social-publish-api.onrender.com/v1/accounts",
    headers={"x-access-key": os.environ["RELAYCAST_API_KEY"]},
)
accounts = res.json()["data"]
active = [a for a in accounts if a["status"] == "active"]

Response

Response 200

{
  "data": [
    {
      "id": "6f1c2a7e-4b8d-4f7a-9a51-2d3c4b5a6e7f",
      "platform": "twitter",
      "handle": "acme",
      "displayName": "Acme Inc.",
      "avatarUrl": "https://pbs.twimg.com/profile_images/1234567890/avatar_400x400.jpg",
      "status": "active",
      "groupId": null,
      "oauthAppId": null,
      "createdAt": "2026-09-14T10:22:31.512Z"
    },
    {
      "id": "7c6b5a49-3827-4e1d-8c0b-9a8f7e6d5c4b",
      "platform": "bluesky",
      "handle": "acme.bsky.social",
      "displayName": null,
      "avatarUrl": null,
      "status": "reconnect_required",
      "groupId": "b1a2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
      "oauthAppId": null,
      "createdAt": "2026-09-20T08:05:12.004Z"
    }
  ]
}

Account fields

Field	Type	Description
`id`	string (UUID)	Relaycast account ID. Use as `targets[].accountId`.
`platform`	string	`twitter`, `instagram`, `facebook`, `linkedin`, `tiktok`, `youtube`, `threads`, `pinterest`, `bluesky` or `google_business`.
`handle`	string	Username shown as `@handle` (for Facebook Pages and Business Profile locations, a name-based handle).
`displayName`	string \| null	Display name from the platform.
`avatarUrl`	string \| null	Profile image URL from the platform.
`status`	string	`active`, or `reconnect_required` when the platform revoked access. Posts to non-active accounts are rejected with `account_inactive`.
`groupId`	string \| null	Social group the account belongs to; `null` is the default group.
`oauthAppId`	string \| null	Your own OAuth app the account was connected through; `null` means the built-in app.
`createdAt`	string	When the account was first connected (ISO 8601).

Tokens and app passwords are stored encrypted and are never returned.

Errors

Status	Code	When
401	`unauthorized`	Missing or invalid API key.
429	`rate_limited`	Rate limit exceeded for this key.

This page is also available as Markdown.