Social Accounts

A social account is a connected end-user account you publish to — an X profile, a Facebook Page, a LinkedIn organization, a YouTube channel, and so on. Accounts are connected through the hosted OAuth flow: you start it from Social Networks, the user authorizes your app, and we return a session token you finalize into one or more accounts.

Once connected, an account’s id is what you pass to accounts[] when creating a post. This page covers listing, retrieving, deleting, and inspecting the metrics and health of connected accounts, plus the two endpoints that complete the OAuth connect flow.

The social account object

Field	Type	Description
`id`	string	Unique identifier for the connected account.
`platform`	enum	The platform this account belongs to.
`tenant_id`	string \| null	Your end-tenant association, if one was supplied at connect time.
`social_network_id`	string	The BYOK network whose OAuth app connected this account.
`network_unique_id`	string	The platform’s own identifier for the account (e.g. page or user id).
`username`	string \| null	The account’s handle or username.
`display_name`	string \| null	Human-friendly name of the account.
`profile_image_url`	string \| null	URL of the account’s avatar.
`account_type`	string \| null	Account category (e.g. `page`, `profile`, `organization`).
`status`	enum	`active`, `disabled`, or another lifecycle state.
`scopes`	string[]	OAuth scopes granted for this account.
`token_expires_at`	timestamp \| null	When the current access token expires.
`last_synced_at`	timestamp \| null	When account metadata was last refreshed.
`created_at` / `updated_at`	timestamp	Creation and last-update timestamps.

List accounts

GET /social-accounts

Returns connected accounts for your organization, newest first, using keyset pagination (limit default 25 / max 100, cursor, next_cursor — see Pagination & filtering). Deleted accounts are excluded. Filters combine with AND.

Query parameter	Type	Required	Description
`id`	uuid	No	Return only the account with this id.
`tenant_id`	string	No	Only return accounts associated with this end tenant.
`platform`	enum	No	Only return accounts for this platform.
`username`	string	No	Exact-match account username.
`network_unique_id`	string	No	Exact-match platform-side account id (also accepted as `networkUniqueId`).

curl

curl "https://api.postfuze.com/api/v1/social-accounts?platform=x" \
  -H "Authorization: Bearer sk_live_…"

200 OK

{
  "data": [
    {
      "id": "a1b2c3d4-0000-4a9f-9b1c-2e7d6f0a1234",
      "platform": "x",
      "tenant_id": "tenant_42",
      "social_network_id": "f3c1b0a2-8d4e-4a9f-9b1c-2e7d6f0a1234",
      "network_unique_id": "1466912345678901234",
      "username": "acme",
      "display_name": "Acme Inc.",
      "profile_image_url": "https://pbs.twimg.com/profile_images/…",
      "account_type": "profile",
      "status": "active",
      "scopes": ["tweet.read", "tweet.write", "users.read", "offline.access"],
      "token_expires_at": "2026-06-09T14:00:00.000Z",
      "last_synced_at": "2026-06-09T12:00:00.000Z",
      "created_at": "2026-06-01T09:30:00.000Z",
      "updated_at": "2026-06-09T12:00:00.000Z"
    }
  ]
}

Retrieve an account

GET /social-accounts/{id}

Fetches a single connected account by id. Returns 404 if not found or deleted.

curl

curl https://api.postfuze.com/api/v1/social-accounts/a1b2c3d4-0000-4a9f-9b1c-2e7d6f0a1234 \
  -H "Authorization: Bearer sk_live_…"

200 OK

{
  "id": "a1b2c3d4-0000-4a9f-9b1c-2e7d6f0a1234",
  "platform": "x",
  "tenant_id": "tenant_42",
  "social_network_id": "f3c1b0a2-8d4e-4a9f-9b1c-2e7d6f0a1234",
  "network_unique_id": "1466912345678901234",
  "username": "acme",
  "display_name": "Acme Inc.",
  "profile_image_url": "https://pbs.twimg.com/profile_images/…",
  "account_type": "profile",
  "status": "active",
  "scopes": ["tweet.read", "tweet.write", "users.read", "offline.access"],
  "token_expires_at": "2026-06-09T14:00:00.000Z",
  "last_synced_at": "2026-06-09T12:00:00.000Z",
  "created_at": "2026-06-01T09:30:00.000Z",
  "updated_at": "2026-06-09T12:00:00.000Z"
}

Disconnect an account

DELETE /social-accounts/{id}

Soft-deletes the account and sets its status to disabled. The account is removed from your list and can no longer be targeted by new posts.

curl

curl -X DELETE https://api.postfuze.com/api/v1/social-accounts/a1b2c3d4-0000-4a9f-9b1c-2e7d6f0a1234 \
  -H "Authorization: Bearer sk_live_…"

200 OK

{
  "id": "a1b2c3d4-0000-4a9f-9b1c-2e7d6f0a1234",
  "deleted": true
}

Account metrics

GET /social-accounts/{id}/metrics

Returns metrics for the account (followers, following, post count, impressions, reach, and profile views). With no date range, it prefers a live pull from the platform (source: "live") and falls back to the most recent stored snapshot (source: "snapshot") if the platform is unreachable. If no snapshot exists yet either, a message is returned instead.

Pass since and/or until (each unix seconds or ISO 8601) to retrieve the full series of stored snapshots over that window instead of a single value — the response then carries a data array of snapshots, oldest first.

Query parameter	Type	Description
`since`	unix seconds or ISO 8601	Lower bound of the snapshot window. Presence switches the response to the series form.
`until`	unix seconds or ISO 8601	Upper bound of the snapshot window.

Field	Type	Description
`social_account_id`	string	The account the snapshot belongs to.
`network`	enum	The account’s platform.
`source`	enum	`live` (freshly fetched) or `snapshot` (most recent stored capture).
`followers` / `following`	number	Follower and following counts.
`posts_count`	number	Total posts on the account.
`impressions` / `reach` / `profile_views`	number	Aggregate engagement figures at capture time.
`raw`	object	The unmodified platform payload the snapshot was derived from.
`captured_at`	timestamp	When the snapshot was taken.

curl

curl https://api.postfuze.com/api/v1/social-accounts/a1b2c3d4-0000-4a9f-9b1c-2e7d6f0a1234/metrics \
  -H "Authorization: Bearer sk_live_…"

200 OK — live pull

{
  "social_account_id": "a1b2c3d4-0000-4a9f-9b1c-2e7d6f0a1234",
  "network": "x",
  "source": "live",
  "captured_at": "2026-06-14T12:10:00.000Z",
  "followers": 18420,
  "following": 312,
  "posts_count": 1894,
  "raw": { "public_metrics": { "followers_count": 18420 } }
}

With a date range (?since=…&until=…), the response is a series of stored snapshots:

200 OK — snapshot series

{
  "social_account_id": "a1b2c3d4-0000-4a9f-9b1c-2e7d6f0a1234",
  "source": "snapshot",
  "since": "2026-06-01T00:00:00.000Z",
  "until": "2026-06-14T00:00:00.000Z",
  "data": [
    {
      "social_account_id": "a1b2c3d4-…",
      "network": "x",
      "followers": 18012,
      "following": 309,
      "posts_count": 1880,
      "impressions": 232004,
      "reach": 88110,
      "profile_views": 5604,
      "raw": {},
      "captured_at": "2026-06-01T06:00:00.000Z"
    }
  ]
}

When no snapshot exists yet:

200 OK

{
  "social_account_id": "a1b2c3d4-0000-4a9f-9b1c-2e7d6f0a1234",
  "metrics": null,
  "message": "No metrics have been collected for this account yet."
}

Account health

GET /social-accounts/{id}/health

Reports whether the account is ready to publish. When the platform adapter supports it and the account isn’t disabled/revoked, this runs a live probe(refreshing the token if it’s near expiry, then making a lightweight identity call) so a hard 401 is caught even when the stored status looks fine; checked_live reports whether that live probe ran. Otherwise it falls back to a status + token-expiry check. A refresh failure during the probe flips the account to token_expired (and fires account.token_expired). Returns 404 if the account does not exist.

Field	Type	Description
`id`	string	The account identifier.
`network`	enum	The account’s platform.
`healthy`	boolean	`true` when the probe (or fallback check) succeeded.
`status`	enum	The account’s current lifecycle status (re-read after the probe).
`error_code`	string \| null	Classified failure reason when not healthy (e.g. `token_expired`), else `null`.
`token_expires_at`	timestamp \| null	When the access token expires.
`checked_live`	boolean	Whether a live platform probe ran (vs. a status-only check).
`checked_at`	timestamp	When this health check ran.

curl

curl https://api.postfuze.com/api/v1/social-accounts/a1b2c3d4-0000-4a9f-9b1c-2e7d6f0a1234/health \
  -H "Authorization: Bearer sk_live_…"

200 OK

{
  "id": "a1b2c3d4-0000-4a9f-9b1c-2e7d6f0a1234",
  "network": "x",
  "healthy": true,
  "status": "active",
  "error_code": null,
  "token_expires_at": "2026-06-14T14:00:00.000Z",
  "checked_live": true,
  "checked_at": "2026-06-14T12:10:00.000Z"
}

The OAuth connect flow

These two endpoints complete the hosted OAuth flow after a user approves your app. They are authenticated by the session token in the path (not your API key) and are issued once per connect attempt. When the provider returns several connectable accounts — for example multiple Facebook Pages or Google Business locations — we mint a session token and hand off to page selection. If the provider returns exactly one account, it is connected immediately and no session is created.

List pending pages

GET /social-accounts/pending/{sessionToken}

Returns the network and the set of availablePages the user can choose to connect. Returns 404 if the session is unknown or expired.

curl

curl https://api.postfuze.com/api/v1/social-accounts/pending/9f8e7d6c5b4a39281706 \
  -H "Content-Type: application/json"

200 OK

{
  "network": "facebook",
  "availablePages": [
    {
      "id": "102938475610293",
      "type": "page",
      "name": "Acme Storefront",
      "username": "acmestore",
      "profilePictureUrl": "https://graph.facebook.com/102938475610293/picture"
    },
    {
      "id": "564738291056473",
      "type": "page",
      "name": "Acme Support",
      "username": "acmesupport",
      "profilePictureUrl": "https://graph.facebook.com/564738291056473/picture"
    }
  ]
}

Finalize the connection

POST /social-accounts/pending/{sessionToken}/finalize

Connects the pages the user selected. The session is consumed (deleted) once finalized, so a token can only be used once. At least one page id is required.

Parameter	Type	Required	Description
`selectedPageIds`	string[]	Yes	The `id`s of the pages to connect (minimum one).

curl

curl https://api.postfuze.com/api/v1/social-accounts/pending/9f8e7d6c5b4a39281706/finalize \
  -H "Content-Type: application/json" \
  -d '{
    "selectedPageIds": ["102938475610293"]
  }'

200 OK

{
  "connectedAccounts": [
    {
      "id": "b7c8d9e0-1111-4a9f-9b1c-2e7d6f0a1234",
      "nickname": "acmestore",
      "username": "acmestore",
      "network": "facebook",
      "accountType": "page"
    }
  ]
}