GET /v1/projects/:projectId/social-accounts

GET/v1/projects/:projectId/social-accounts

Phase 1stable

Auth: Bearer
Scope: social:read

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 targets.

Path

projectId
stringrequired
Project whose accounts you want.

Query

platform
stringoptional
Filter to a single platform.
One of: tiktok, instagram
status
stringoptional
Filter by connection state.
One of: connected, reauth_required, disconnected
leased
booleanoptional
true returns only leased accounts, false excludes them.

Example request

curl "https://api.layers.com/v1/projects/prj_01HX9Y7K8M2P4RSTUV56789AB/social-accounts?platform=tiktok&status=connected" \
  -H "Authorization: Bearer lp_live_01HX9Y6K7EJ4T2_4QZpN..."

const { items } = await layers.social.listAccounts({
  projectId: "prj_01HX9Y7K8M2P4RSTUV56789AB",
  platform: "tiktok",
  status: "connected",
});

const publishable = items.filter((a) => a.status === "connected");

accounts = layers.social.list_accounts(
    project_id="prj_01HX9Y7K8M2P4RSTUV56789AB",
    platform="tiktok",
    status="connected",
)
publishable = [a for a in accounts["items"] if a["status"] == "connected"]

Response

200Account list

{
  "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
}

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 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` if the user wants back in.

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.

GET /v1/projects/:projectId/social-accounts

Example request

Response

Status values

Errors

See also

On this page