# GET /v1/projects/:projectId/social-accounts (/docs/api/reference/social-accounts/list-social-accounts)



<Endpoint method="GET" path="/v1/projects/:projectId/social-accounts" auth="Bearer" scope="social:read" phase="1" />

List every social account attached to the project — OAuth-connected accounts from your end-customers and leased TikTok accounts provisioned by Layers. Both appear in the same list with a `leased` boolean so you can tell them apart.

Use this endpoint before scheduling a post — its `socialAccountId` values are what you pass into [`POST /v1/content/:id/schedule`](/docs/api/reference/publishing/schedule-content) targets.

<Parameters
  title="Path"
  rows="[
  { name: 'projectId', type: 'string', required: true, description: 'Project whose accounts you want.' },
]"
/>

<Parameters
  title="Query"
  rows="[
  { name: 'platform', type: 'string', enum: ['tiktok', 'instagram'], description: 'Filter to a single platform.' },
  { name: 'status', type: 'string', enum: ['connected', 'reauth_required', 'disconnected'], description: 'Filter by connection state.' },
  { name: 'leased', type: 'boolean', description: 'true returns only leased accounts, false excludes them.' },
]"
/>

## Example request [#example-request]

<Tabs items="['curl', 'TypeScript', 'Python']">
  <Tab value="curl">
    ```bash
    curl "https://api.layers.com/v1/projects/prj_01HX9Y7K8M2P4RSTUV56789AB/social-accounts?platform=tiktok&status=connected" \
      -H "Authorization: Bearer lp_live_01HX9Y6K7EJ4T2_4QZpN..."
    ```
  </Tab>

  <Tab value="TypeScript">
    ```ts
    const { items } = await layers.social.listAccounts({
      projectId: "prj_01HX9Y7K8M2P4RSTUV56789AB",
      platform: "tiktok",
      status: "connected",
    });

    const publishable = items.filter((a) => a.status === "connected");
    ```
  </Tab>

  <Tab value="Python">
    ```python
    accounts = layers.social.list_accounts(
        project_id="prj_01HX9Y7K8M2P4RSTUV56789AB",
        platform="tiktok",
        status="connected",
    )
    publishable = [a for a in accounts["items"] if a["status"] == "connected"]
    ```
  </Tab>
</Tabs>

## Response [#response]

<Response status="200" description="Account list">
  ```json
  {
    "items": [
      {
        "socialAccountId": "sa_01HXZ9P2M4N5KLM6TUV7WXYZ9A",
        "platform": "tiktok",
        "handle": "acmecoffee",
        "avatarUrl": "https://media.meetsift.com/tiktok/acmecoffee/avatar.jpg",
        "status": "connected",
        "leased": false,
        "connectedAt": "2026-04-18T19:06:42Z",
        "tokenExpiresAt": "2026-05-18T19:06:42Z"
      },
      {
        "socialAccountId": "sa_01HXZQ8N3C5R6STUV7WXYZ9AB",
        "platform": "tiktok",
        "handle": "coffee.reviews.daily",
        "avatarUrl": "https://media.meetsift.com/tiktok/coffee.reviews.daily/avatar.jpg",
        "status": "connected",
        "leased": true,
        "connectedAt": "2026-04-12T08:00:00Z",
        "tokenExpiresAt": null
      }
    ],
    "nextCursor": null
  }
  ```
</Response>

### Status values [#status-values]

| `status`          | Meaning                                                                                                                                                                                                                              | What to do                                                                                                     |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------- |
| `connected`       | Token valid, scheduling allowed.                                                                                                                                                                                                     | Normal operation.                                                                                              |
| `reauth_required` | Token expired or revoked upstream.                                                                                                                                                                                                   | Create a [reauth URL](/docs/api/reference/social-accounts/reauth-url) and send the user through consent again. |
| `disconnected`    | You or the user called DELETE, or a leased account was released. Scheduled posts were canceled. (The list endpoint excludes soft-deleted rows by default — disconnected accounts surface only via the DELETE response or audit log.) | Reconnect via [`oauth-url`](/docs/api/reference/social-accounts/oauth-url) if the user wants back in.          |

## Errors [#errors]

| Status | Code              | When                              |
| ------ | ----------------- | --------------------------------- |
| 401    | `UNAUTHENTICATED` | Missing or invalid key.           |
| 403    | `FORBIDDEN_SCOPE` | Key lacks `social:read`.          |
| 404    | `NOT_FOUND`       | Project not in your organization. |
| 429    | `RATE_LIMITED`    | Read budget exhausted.            |

## See also [#see-also]

* [`POST /v1/projects/:projectId/social/reauth-url`](/docs/api/reference/social-accounts/reauth-url) — fix a `reauth_required` account
* [`DELETE /v1/social-accounts/:socialAccountId`](/docs/api/reference/social-accounts/revoke-social-account) — disconnect an account
* [`GET /v1/leased-accounts`](/docs/api/reference/leased-accounts/list-leased-accounts) — leased accounts with billing detail