echoia

API Reference

Accounts

The social accounts connected to this workspace. Usually the first call you make — other endpoints refer to these by id.

GET/api/v1/accounts

Requires the read scope. Takes no parameters.

Request

curl
curl https://app.echoia.io/api/v1/accounts \
  -H "Authorization: Bearer $ECHOIA_API_KEY"

Response

200
{
  "accounts": [
    {
      "id": "cmq7f2x8b0001sl3k9a2vd8pq",
      "platform": "instagram",
      "username": "yourbrand",
      "followers": 1842,
      "isActive": true,
      "needsReconnect": false
    },
    {
      "id": "cmq7f2x8b0002sl3k4c1te7mz",
      "platform": "x",
      "username": "yourbrand",
      "followers": null,
      "isActive": true,
      "needsReconnect": true
    }
  ]
}

Account object

idstringoptional
Echoia's id for the connection. Pass this as accountId when replying to a comment.
platformstringoptional
One of the ten platform identifiers.
usernamestring | nulloptional
The handle or page name, as the platform reports it. Null if the platform does not expose one.
followersnumber | nulloptional
Follower count, cached for an hour. null means the last fetch failed — usually a token needing reconnection.
isActivebooleanoptional
False when the connection has been disabled, for instance during an account-deletion grace period.
needsReconnectbooleanoptional
True when the platform token has expired. Publishing and reading will fail until someone reconnects it in Settings.

An empty list is not an error

A workspace with nothing connected returns { "accounts": [] } and a 200. A bad token returns 401 — the two are easy to confuse when debugging.

Why call it first

Creating a post for a platform with no active connection is rejected, so listing accounts is how you find out what is legitimately targetable. It is also how you detect an account that has quietly expired: needsReconnect flips to true long before anyone notices posts failing.

node
const { accounts } = await echoia("/accounts");

const usable = accounts
  .filter((a) => a.isActive && !a.needsReconnect)
  .map((a) => a.platform);

const stale = accounts.filter((a) => a.needsReconnect);
if (stale.length) {
  console.warn("Reconnect needed:", stale.map((a) => a.platform).join(", "));
}

Not a credential endpoint

Platform access tokens are never returned by the API, in any form. If you need to act on a platform, do it through Echoia's endpoints rather than trying to obtain the underlying credential.
Was this page helpful?