---
title: "List connected social accounts"
method: GET
path: "/v1/social-accounts"
tags: ["Social Accounts"]
---

# List connected social accounts

`GET /v1/social-accounts`

## Request

- Base URL: `https://api.outstand.so`
- URL: `https://api.outstand.so/v1/social-accounts`
- Auth: none declared

Retrieve all social accounts connected to your organization. This endpoint returns all social media profiles that have been connected and authorized through OAuth flows.

**Use Cases:**
- View all connected social media accounts for your organization
- Check which platforms have accounts connected
- Verify account status and metadata
- Get account information for use in post creation endpoints
- Filter accounts by tenant ID, network, username, or unique platform ID

**Filtering:**
- `id` - Filter by encoded social account ID (exact match)
- `tenantId` - Filter by tenant ID for multi-tenant applications (exact match)
- `network` - Filter by social network platform, e.g. `x`, `linkedin`, `instagram` (exact match)
- `networkUniqueId` - Filter by the account's unique ID on the platform (exact match)
- `username` - Filter by username or handle (case-insensitive partial match)
- All filters can be combined for precise queries

**Pagination:**
- Use `limit` and `offset` query parameters to paginate results
- Default limit is 50, maximum is 100
- `total` is the number of accounts matching your filters across all pages; `count` is the number returned in this page
- Results are always ordered by connection order (oldest connected first), so paging through every offset returns each account exactly once. Accounts connected while you are paginating are appended after the last page rather than shifting the pages you already fetched

**Tokens:** By default, OAuth tokens are never exposed. Pass `includeTokens=true` to include the account's `access_token` nested under a `tokens` object in each result. Only `access_token` is returned - refresh tokens and other sensitive fields remain hidden.

## Query parameters

- `id` string
- `tenantId` string
- `network` string
- `networkUniqueId` string
- `username` string
- `limit` number
- `offset` number
- `includeTokens` 'true' | 'false'

## Response `200`

List of social accounts retrieved successfully

- object: Successful list operation response
  - `success` boolean, required
  - `data` object[], required
    - `id` string, required: Unique identifier for the social account
    - `orgId` string, required: Organization ID that owns this social account
    - `tenant_id` string, nullable, required: Your own tenant identifier for this account, as supplied when it was connected. Null when the account was connected without one - such an account is not matched by the `tenantId` filter.
    - `nickname` string, required: User-friendly nickname for the social account
    - `network` string, required: Social network platform (e.g., 'x', 'linkedin', 'instagram')
    - `username` string, required: Username or handle for the social account
    - `profile_picture_url` string, nullable, required: URL to the profile picture for the social account
    - `network_unique_id` string, required: Unique identifier for the account on the social network platform
    - `network_webhook_reference_id` string, nullable: The id this network uses to identify the account in webhook payloads, when it differs from network_unique_id. Null when the platform uses the same id for both. Used by: Instagram.
    - `customer_social_network_id` number, required: ID of the customer social network configuration used to connect this account
    - `accountType` string, required: Type of account: 'personal', 'organization', or 'page'
    - `isActive` number, nullable, required: Whether the account is active (1) or inactive (0)
    - `createdAt` string, nullable, required: ISO 8601 timestamp when the account was connected
    - `tokens` object: Sensitive OAuth tokens. Only included when includeTokens=true is passed.
      - `access_token` string, nullable, required: OAuth access token for the account. Only present when the request included includeTokens=true.
  - `count` number, required: Number of social accounts returned in this page
  - `total` number, required: Total number of social accounts matching the filters, across all pages
  - `limit` number, required: Maximum number of results per page
  - `offset` number, required: Number of results to skip

## Other responses

- `400`: Invalid query parameters
- `500`: Internal server error

---

[API](https://skmtc.dev/outstand/apis/outstand-social-accounts-api-v1.md) · [All operations](https://skmtc.dev/outstand/apis/outstand-social-accounts-api-v1/llms.txt) · [OpenAPI document](https://skmtc.dev/outstand/apis/outstand-social-accounts-api-v1/revisions/181fad55d031?raw)