# List accounts

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


```http
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](/docs/api/create-post). Disconnected accounts are not returned; accounts that need reconnecting are returned with `status: "reconnect_required"`.

Accounts are connected in the dashboard under **[Integrations](https://social-publish-kappa.vercel.app/dashboard/integrations)**, by your users through a [connect link](/docs/api/create-connect-link) (OAuth platforms), or with [Connect Bluesky](/docs/api/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](/docs/groups). 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).

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

## Request

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

```ts tab="Node.js"
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");
```

```python tab="Python"
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

```json title="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](/docs/groups) the account belongs to; `null` is the default group. |
| `oauthAppId` | string \| null | Your own [OAuth app](/docs/oauth-apps) 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. |