# Account

## List Connected Accounts

### Endpoint

**Base URL:** `https://backend.blotato.com/v2`

**URL:** `/users/me/accounts`

**Method:** `GET`

### Description

Returns all social media accounts connected to your Blotato account. Use this to get the `accountId` required for [publishing posts](/api/publish-post.md).

### Query Parameters

| Field      | Type     | Required | Description                                                                                                                        |
| ---------- | -------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| `platform` | `string` | No       | Filter by platform. Values: `twitter`, `instagram`, `linkedin`, `facebook`, `tiktok`, `pinterest`, `threads`, `bluesky`, `youtube` |

The `platform` values here are the same values used in `content.platform` and `target.targetType` when publishing.

### Response

**Status Code:** `200 OK`

```json
{
  "items": [
    {
      "id": "98432",
      "platform": "twitter",
      "fullname": "Jane Smith",
      "username": "janesmith"
    },
    {
      "id": "98433",
      "platform": "facebook",
      "fullname": "Jane Smith",
      "username": "janesmith"
    }
  ]
}
```

| Field              | Type     | Description                                              |
| ------------------ | -------- | -------------------------------------------------------- |
| `items`            | `array`  | List of connected accounts                               |
| `items[].id`       | `string` | Account ID. Use this as `accountId` when publishing.     |
| `items[].platform` | `string` | Platform type (e.g., `twitter`, `facebook`, `instagram`) |
| `items[].fullname` | `string` | Display name of the account                              |
| `items[].username` | `string` | Username or handle                                       |

If no accounts are returned, the user needs to connect social accounts in [Blotato Settings](https://my.blotato.com/settings).

### Examples

#### List all accounts

```http
GET https://backend.blotato.com/v2/users/me/accounts HTTP/1.1
blotato-api-key: YOUR_API_KEY
```

#### Filter by platform

```http
GET https://backend.blotato.com/v2/users/me/accounts?platform=instagram HTTP/1.1
blotato-api-key: YOUR_API_KEY
```

***

## List Subaccounts (Pages)

### Endpoint

**Base URL:** `https://backend.blotato.com/v2`

**URL:** `/users/me/accounts/:accountId/subaccounts`

**Method:** `GET`

### Description

Returns subaccounts for a connected account. Subaccounts include Facebook Pages, LinkedIn Company Pages, and YouTube Playlists. Use this to get the `pageId` required for publishing to Facebook/LinkedIn, or `playlistIds` for adding YouTube videos to playlists.

### Path Parameters

| Field       | Type     | Required | Description                                    |
| ----------- | -------- | -------- | ---------------------------------------------- |
| `accountId` | `string` | Yes      | The account ID from the List Accounts endpoint |

### Response

**Status Code:** `200 OK`

```json
{
  "items": [
    {
      "id": "123456789",
      "accountId": "98433",
      "name": "My Business Page"
    }
  ]
}
```

| Field               | Type     | Description                                                                         |
| ------------------- | -------- | ----------------------------------------------------------------------------------- |
| `items`             | `array`  | List of subaccounts                                                                 |
| `items[].id`        | `string` | Subaccount ID. Use this as `target.pageId` when publishing to Facebook or LinkedIn. |
| `items[].accountId` | `string` | Parent account ID                                                                   |
| `items[].name`      | `string` | Name of the page                                                                    |

If subaccounts is empty, the user needs to connect a Facebook Page, LinkedIn Company Page, or YouTube account in [Blotato Settings](https://my.blotato.com/settings).

### Example

```http
GET https://backend.blotato.com/v2/users/me/accounts/98433/subaccounts HTTP/1.1
blotato-api-key: YOUR_API_KEY
```

***

## How to Get the Right IDs for Publishing

Different platforms need different IDs. Here is how to get them for each platform.

### Twitter, Instagram, TikTok, Threads, Bluesky

These platforms need only an `accountId`:

1. Call `GET /v2/users/me/accounts?platform=twitter` (replace with your platform)
2. Use `items[].id` as `accountId` in your publish request
3. If multiple accounts are returned, use `fullname` or `username` to identify the correct one, or ask the user which account to use

### YouTube

YouTube needs an `accountId`. To add videos to playlists, also fetch subaccounts to get playlist IDs:

1. Call `GET /v2/users/me/accounts?platform=youtube`
2. Use `items[].id` as `accountId`
3. Call `GET /v2/users/me/accounts/{accountId}/subaccounts`
4. Use `items[].id` values as `target.playlistIds` in your publish request
5. `playlistIds` is optional -- omit it to publish without adding to a playlist

### Facebook

Facebook requires both `accountId` and `pageId`:

1. Call `GET /v2/users/me/accounts?platform=facebook`
2. Use `items[].id` as `accountId`
3. Call `GET /v2/users/me/accounts/{accountId}/subaccounts`
4. Use `items[].id` as `target.pageId` in your publish request
5. If multiple pages are returned, use `name` to identify the correct one, or ask the user which page to use

**Full example:**

```
1. GET /v2/users/me/accounts?platform=facebook
   Response: { "items": [{ "id": "98433", "platform": "facebook", ... }] }

2. GET /v2/users/me/accounts/98433/subaccounts
   Response: { "items": [{ "id": "123456789", "name": "My Business Page" }] }

3. POST /v2/posts with:
   {
     "post": {
       "accountId": "98433",
       "content": { "text": "Hello!", "mediaUrls": [], "platform": "facebook" },
       "target": { "targetType": "facebook", "pageId": "123456789" }
     }
   }
```

### LinkedIn Company Page

To post to a LinkedIn Company Page instead of your personal profile:

1. Call `GET /v2/users/me/accounts?platform=linkedin`
2. Use `items[].id` as `accountId`
3. Call `GET /v2/users/me/accounts/{accountId}/subaccounts`
4. Use `items[].id` as `target.pageId`
5. If you skip `pageId`, the post goes to your personal LinkedIn profile

### Pinterest

Pinterest requires a `boardId`. Fetch boards with the List Pinterest Boards endpoint:

1. Call `GET /v2/users/me/accounts?platform=pinterest`
2. Use `items[].id` as `accountId`
3. Call `GET /v2/social/pinterest/boards?accountId={accountId}`
4. Use `items[].id` as `target.boardId` in your publish request
5. If multiple boards are returned, use `name` to identify the correct one, or ask the user which board to use

**Full example:**

```
1. GET /v2/users/me/accounts?platform=pinterest
   Response: { "items": [{ "id": "98436", "platform": "pinterest", ... }] }

2. GET /v2/social/pinterest/boards?accountId=98436
   Response: { "items": [{ "id": "1234567890123456789", "name": "Summer Outfits" }] }

3. POST /v2/posts with:
   {
     "post": {
       "accountId": "98436",
       "content": { "text": "Check out this pin!", "mediaUrls": ["https://example.com/image.jpg"], "platform": "pinterest" },
       "target": { "targetType": "pinterest", "boardId": "1234567890123456789" }
     }
   }
```

***

## List Pinterest Boards

### Endpoint

**Base URL:** `https://backend.blotato.com/v2`

**URL:** `/social/pinterest/boards`

**Method:** `GET`

### Description

Returns boards owned by a connected Pinterest account. Use this to get the `boardId` required when publishing a pin.

### Query Parameters

| Field       | Type     | Required | Description                                                 |
| ----------- | -------- | -------- | ----------------------------------------------------------- |
| `accountId` | `string` | Yes      | Blotato Pinterest account ID from `GET /users/me/accounts`. |

### Response

**Status Code:** `200 OK`

```json
{
  "items": [
    {
      "id": "1234567890123456789",
      "name": "Summer Outfits"
    }
  ]
}
```

| Field          | Type     | Description                                                   |
| -------------- | -------- | ------------------------------------------------------------- |
| `items`        | `array`  | List of Pinterest boards (max 250)                            |
| `items[].id`   | `string` | Board ID. Use this as `target.boardId` when publishing a pin. |
| `items[].name` | `string` | Display name of the board on Pinterest                        |

### Example

```http
GET https://backend.blotato.com/v2/social/pinterest/boards?accountId=98436 HTTP/1.1
blotato-api-key: YOUR_API_KEY
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://help.blotato.com/api/accounts.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.