> ## Documentation Index
> Fetch the complete documentation index at: https://docs.genviral.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Get Accounts

> List connected social accounts and discover per-account posting capabilities, media limits, caption limits, and settings schemas for the Genviral social media API.

List the social accounts available in the authenticated key scope - including both your own connected accounts (BYO) and hosted creator accounts. Use this endpoint to discover the `account_id` you need when calling [Create Post](/api-reference/create-post), and to inspect what each account can publish before you build a payload.

## Behavior

* The API merges active BYO social accounts with active hosted accounts in scope.
* Workspace keys return workspace accounts. Personal keys return personal accounts (`user_id = owner_user_id`, `workspace_id IS NULL`).
* IDs are stable UUIDs constrained to key scope. If no active accounts exist, the endpoint returns an empty array.
* Each account is normalized to expose the platform (`tiktok`, `instagram`, etc.)
  and a simplified `type` of `byo` or `hosted`.
* Each account includes a `capabilities` object with supported content kinds,
  caption limits, media limits, unsupported reasons, and a machine-readable
  provider settings schema.
* Text-only posting is available only for accounts whose
  `capabilities.supported_content_kinds` includes `text_only`.

## Response

<ResponseField name="scope" type="string">
  Authenticated key scope: `workspace` or `personal`.
</ResponseField>

<ResponseField name="owner_user_id" type="string">
  Resolved owner user ID for the authenticated key.
</ResponseField>

<ResponseField name="workspace_id" type="string | null">
  Workspace ID for workspace keys, otherwise `null`.
</ResponseField>

<ResponseField name="accounts" type="array">
  List of social accounts available for posting.

  <Expandable title="Account Object">
    <ResponseField name="id" type="string">
      UUID account ID returned by `/accounts`. Use this in the `accounts` array
      when creating a post.
    </ResponseField>

    <ResponseField name="platform" type="string">
      The platform name (e.g., `instagram`, `tiktok`).
    </ResponseField>

    <ResponseField name="type" type="string">
      Type of account: `byo` (connected by user) or `hosted` (managed virtual
      account).
    </ResponseField>

    <ResponseField name="username" type="string">
      The handle or username.
    </ResponseField>

    <ResponseField name="display_name" type="string">
      The display name of the account.
    </ResponseField>

    <ResponseField name="status" type="string">
      Current status of the account connection.
    </ResponseField>

    <ResponseField name="workspace_id" type="string | null">
      Workspace that owns the account, or `null` in personal scope.
    </ResponseField>

    <ResponseField name="capabilities" type="object">
      Posting capabilities for this account.

      <Expandable title="Capabilities Object">
        <ResponseField name="supported_content_kinds" type="string[]">
          Content kinds this account can publish through Genviral. Values
          include `text_only`, `single_image`, `multi_image`, and
          `single_video`.
        </ResponseField>

        <ResponseField name="caption_limit" type="number">
          Maximum caption length for this account after platform/account policy
          is applied.
        </ResponseField>

        <ResponseField name="media_limits" type="object">
          Media limits such as `max_images`, `max_videos`, and optionally
          `max_video_seconds`.
        </ResponseField>

        <ResponseField name="unsupported_content_kind_reasons" type="object">
          Reason strings keyed by unsupported content kind.
        </ResponseField>

        <ResponseField name="settings_schema" type="object">
          JSON Schema for the dashboard composer. Field names may differ from the Partner API.
          For create payloads, use the field tables in
          [`Create Post`](/api-reference/create-post) for YouTube, TikTok, Pinterest, and Instagram
          — not `settings_schema`.
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl --request GET \
    --url https://www.genviral.io/api/partner/v1/accounts \
    --header 'Authorization: Bearer <token>'
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={null}
  {
    "ok": true,
    "code": 200,
    "message": "Accounts retrieved",
    "data": {
      "scope": "workspace",
      "owner_user_id": "7be83ba4-14e5-47ba-a662-0ad42d852111",
      "workspace_id": "4cb5d3fd-8c8f-4ed7-a17c-4ffb52c7e6ac",
      "accounts": [
        {
          "id": "54c22677-43f4-415f-a820-7dfd1fcd4bd5",
          "platform": "twitter",
          "type": "byo",
          "username": "jamesgrowth_",
          "display_name": "james",
          "status": "active",
          "workspace_id": null,
          "capabilities": {
            "supported_content_kinds": ["text_only", "single_image", "multi_image", "single_video"],
            "caption_limit": 4000,
            "media_limits": {
              "max_images": 4,
              "max_videos": 1
            },
            "unsupported_content_kind_reasons": {},
            "settings_schema": {
              "type": "object",
              "additionalProperties": false,
              "properties": {
                "who_can_reply_post": {
                  "type": "string",
                  "enum": ["everyone", "following", "mentionedUsers", "subscribers", "verified"]
                },
                "made_with_ai": { "type": "boolean" },
                "paid_partnership": { "type": "boolean" }
              },
              "required": ["who_can_reply_post"]
            }
          }
        },
        {
          "id": "0f4f54d4-8cce-4fb7-8c7b-befbcb8af812",
          "platform": "tiktok",
          "type": "hosted",
          "username": "ugc_trends_42",
          "display_name": "Hosted Trends 42",
          "status": "active",
          "workspace_id": "4cb5d3fd-8c8f-4ed7-a17c-4ffb52c7e6ac",
          "capabilities": {
            "supported_content_kinds": ["single_image", "multi_image", "single_video"],
            "caption_limit": 500,
            "media_limits": {
              "max_images": 35,
              "max_videos": 1
            },
            "unsupported_content_kind_reasons": {
              "text_only": "Text-only posts are only available for connected BYO accounts; hosted accounts require media."
            },
            "settings_schema": {
              "type": "object",
              "additionalProperties": false,
              "properties": {}
            }
          }
        }
      ]
    }
  }
  ```
</ResponseExample>

## Error Responses

* `401` - authentication failed (missing/invalid/revoked token)
* `402 subscription_required` - active Creator/Professional/Business plan required
* `403 tier_not_allowed` - Scheduler tier cannot use Partner API
* `500 accounts_failed` - Database query failed unexpectedly