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

# Connected Accounts

> List connected social media accounts for your organization

List all social media accounts connected to your organization. Use this to discover available accounts for [publishing](/api-reference/publish) or to display account information in your integration.

## Authentication

<ParamField header="Authorization" type="string" required>
  Your Nouvel API key with `analytics:read` permission. Format: `Bearer nvl_xxxx`
</ParamField>

## Query Parameters

<ParamField query="platform" type="string">
  Filter accounts by platform. Supported values: `instagram`, `tiktok`, `youtube`, `facebook`, `linkedin`, `pinterest`, `threads`, `twitter`, `reddit`
</ParamField>

## Response

<ResponseField name="accounts" type="array" required>
  List of connected social media accounts.

  <Expandable title="Account object">
    <ResponseField name="id" type="string" required>
      Unique account identifier. Use this as `accountId` when publishing.
    </ResponseField>

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

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

    <ResponseField name="displayName" type="string" required>
      Account display name.
    </ResponseField>

    <ResponseField name="avatarUrl" type="string">
      URL of the account's profile picture.
    </ResponseField>

    <ResponseField name="followersCount" type="integer">
      Current number of followers.
    </ResponseField>
  </Expandable>
</ResponseField>

## Example Requests

<CodeGroup>
  ```bash cURL - All Accounts theme={null}
  curl https://app.nouvel.ai/api/v1/accounts \
    -H "Authorization: Bearer nvl_xxxx"
  ```

  ```bash cURL - Filter by Platform theme={null}
  curl "https://app.nouvel.ai/api/v1/accounts?platform=instagram" \
    -H "Authorization: Bearer nvl_xxxx"
  ```

  ```typescript TypeScript theme={null}
  const response = await fetch('https://app.nouvel.ai/api/v1/accounts?platform=instagram', {
    headers: {
      'Authorization': `Bearer ${process.env.NOUVEL_API_KEY}`,
    },
  });

  const { accounts } = await response.json();
  accounts.forEach(acct => {
    console.log(`${acct.platform}: @${acct.username} (${acct.followersCount} followers)`);
  });
  ```

  ```python Python theme={null}
  import requests

  response = requests.get(
      'https://app.nouvel.ai/api/v1/accounts',
      headers={'Authorization': f'Bearer {api_key}'},
      params={'platform': 'instagram'}
  )

  for acct in response.json()['accounts']:
      print(f"{acct['platform']}: @{acct['username']}")
  ```
</CodeGroup>

## Response Examples

<CodeGroup>
  ```json 200 - Success theme={null}
  {
    "accounts": [
      {
        "id": "6612f1a2b3c4d5e6f7890123",
        "platform": "instagram",
        "username": "mybrand",
        "displayName": "My Brand",
        "avatarUrl": "https://scontent.cdninstagram.com/...",
        "followersCount": 15000
      },
      {
        "id": "6612f1a2b3c4d5e6f7890456",
        "platform": "tiktok",
        "username": "mybrand_official",
        "displayName": "My Brand Official",
        "avatarUrl": "https://p16-sign.tiktokcdn.com/...",
        "followersCount": 42000
      }
    ]
  }
  ```

  ```json 401 - Unauthorized theme={null}
  {
    "error": "Invalid API key"
  }
  ```

  ```json 403 - Forbidden theme={null}
  {
    "error": "This API key does not have the 'analytics:read' permission"
  }
  ```

  ```json 404 - No Organization theme={null}
  {
    "error": "No organization found for this user"
  }
  ```
</CodeGroup>

## Error Codes

| Code | Description                                 |
| ---- | ------------------------------------------- |
| 401  | Invalid or missing API key                  |
| 402  | Plan doesn't include API access             |
| 403  | API key missing `analytics:read` permission |
| 404  | No organization found for the user          |

## Notes

* Accounts are connected via the Nouvel dashboard (Settings > Connected Accounts)
* Account data is synced from the social platform — follower counts may lag by up to 1 hour
* The `id` field is the identifier you'll use as `accountId` when calling the [Publish endpoint](/api-reference/publish)