Accounts & connections · Accounts

List accounts

Returns accounts, one page at a time.

GEThttps://api.pozy.ai/v1/accounts

listAccounts

Guides: Connecting accounts, Hosted connect pages, Account health

Request

Send your API key as Authorization: Bearer pz_live_.... Read-only keys can call it. Keys with the accounts resource group disabled get 403 resource_group_disabled. Authentication

Query parameters

Name	Type	Notes
`profileId`	string
`platform`	string
`status`	string	One of `connected`, `disconnected`
`search`	string	Up to 100 characters
`category`	string	One of `social`, `ads`, `communication`, `blogs`, `crm`, `analytics`
`sort`	string	One of `account`, `platform`, `profile`, `status`, `connected`
`order`	string	One of `asc`, `desc`Default `asc`
`includeOverLimit`	boolean	Default `false`
`excludeHidden`	boolean	Default `false`
`adAccountRows`	boolean	Default `false`
`includeCreatorAccounts`	boolean	Default `false`
`includeSandbox`	boolean	Default `false`
`includeStatusCounts`	boolean	Default `false`
`page`	integer	At least 1
`limit`	integer	1 to 500
`cursor`	string
`profileIds`	string
`perProfile`	integer	1 to 24

Example

curl -X GET "https://api.pozy.ai/v1/accounts?limit=1" \
  -H "Authorization: Bearer $POZY_API_KEY"

const res = await fetch("https://api.pozy.ai/v1/accounts?limit=1", {
  headers: { Authorization: `Bearer ${process.env.POZY_API_KEY}` },
});
const data = await res.json();
if (!res.ok) throw new Error(data?.error ?? `Request failed with status ${res.status}`);
console.log(data);

import os
import requests

resp = requests.get(
    "https://api.pozy.ai/v1/accounts",
    headers={"Authorization": f"Bearer {os.environ['POZY_API_KEY']}"},
    params={
        "limit": 1,
    },
    timeout=30,
)
resp.raise_for_status()
print(resp.json())

Response

200 on success

accountsarray of objectrequired
19 child fields
- _idstringrequired
- platformstringrequired
  One of tiktok, instagram, facebook, youtube, linkedin, twitter, threads, pinterest, reddit, bluesky, googlebusiness, telegram, snapchat, discord, slack, whatsapp, shopify, wordpress, wix, linkedinads, metaads, pinterestads, tiktokads, xads and 15 more.
- profileIdstring or objectrequired
  One of:
  string
  Profile (11 fields)
  _idstring
  userIdstring
  namestring
  descriptionstring
  colorstring
  timezonestring
  Can be null.
  externalIdstring
  Can be null.
  isDefaultboolean
  isOverLimitboolean
  accountCountinteger
  createdAtstring (date-time)
- usernamestring
- displayNamestring
- platformUserIdstring
- scopeAreasarray of string
  Can be null.
- oauthAppIdstring
  Can be null.
- tiktokAccountTypestring
  One of business, personal, unknown.
- profilePicturestring
  Can be null.
- profileUrlstring
- isActivebooleanrequired
- needsReconnectionboolean
- followersCountnumber
- followersLastUpdatedstring (date-time)
- parentAccountIdstring
  Can be null.
- enabledboolean
- rateLimitedUntilstring (date-time)
  Can be null.
- metadataobject
hasAnalyticsAccessbooleanrequired
paginationobject
One of:
Pagination (4 fields)
- pageinteger
- limitinteger
- totalinteger
- pagesinteger
Account Cursor Pagination (2 fields)
- limitintegerrequired
- nextCursorstringrequired
  Can be null.
profileTotalsmap of integer
statusCountsobject
- allintegerrequired
- disconnectedintegerrequired

200 response

{
  "accounts": [
    {
      "_id": "635d87e261ae344ef27fd1df",
      "platform": "tiktok",
      "profileId": "6a0b6573846efc28aaa9a3ff",
      "username": "acme",
      "displayName": "Acme",
      "platformUserId": "60c5beb6ca4037bb9ff5117a",
      "scopeAreas": [
        "string"
      ],
      "oauthAppId": "629a39de8c0a63af5a05067c",
      "tiktokAccountType": "business",
      "profilePicture": "string",
      "profileUrl": "https://pozy.ai/media/example-1.jpg",
      "isActive": true,
      "needsReconnection": true,
      "followersCount": 12.5,
      "followersLastUpdated": "2026-10-02T09:00:00.000Z",
      "parentAccountId": "6ce971ffa48fe63468db336b",
      "enabled": true,
      "rateLimitedUntil": "2026-10-02T09:00:00.000Z",
      "metadata": {}
    }
  ],
  "hasAnalyticsAccess": true,
  "pagination": {
    "page": 1,
    "limit": 1,
    "total": 42,
    "pages": 1
  },
  "profileTotals": {
    "key": 1
  },
  "statusCounts": {
    "all": 1,
    "disconnected": 1
  }
}

Errors

Errors use one shape: { error, type, code, param?, details? }. The ones you are most likely to see here:

400	invalid_request_error	A parameter or body field is missing or invalid. `param` names it.
401	authentication_error	The API key is missing, revoked or expired.
403	permission_error	The key is scoped to other profiles or has this resource group disabled.
429	rate_limit_error	Too many requests this minute. Wait for `Retry-After` seconds.

Every code is listed in Errors.

Request

Query parameters

Example

Response

Errors

More in Accounts