The Analytics section provides access to social media analytics data for connected accounts in your workspace. These endpoints allow you to retrieve available charts and their corresponding data for various social media platforms.

The Charts endpoints let you:

- Discover which analytics charts are available (and their IDs).
- Fetch time‑series and comparative data for selected charts.

Use the returned `id` values from “List Charts” with “Get Chart Data” to build dashboards and reports.

### Requirements

**Authentication:** Bearer API token  
**Scope:** `analytics`

**Headers:**  
- `Authorization: Bearer-API YOUR_API_KEY`  
- `Publer-Workspace-Id: YOUR_WORKSPACE_ID`

### Endpoints

### 1. List Charts

Retrieve chart definitions.

```
GET /api/v1/analytics/charts
```

#### Description

Returns a list of charts grouped by category (growth, insights, demographics). Different platforms expose different charts.

#### Query Parameters

| Parameter     | Type   | Required | Description                                               |
|---------------|--------|----------|-----------------------------------------------------------|
| `account_type`| string | No       | Filter charts for a specific account type.               |

Account type values:  
`ig_business`, `fb_page`, `twitter`, `linkedin`, `youtube`, `tiktok`, `google`, `pin_business`, `pin_personal`, `threads`, `wordpress_oauth`, `in_profile`, `in_page`, `mastodon`, `bluesky`

### Get Available Analytics Charts

GET  
https://app.publer.com/api/v1/analytics/charts

Retrieves a list of available analytics charts filtered by account type and chart type. Charts include growth metrics (followers, connections), insights (engagement, reach), and demographics (countries, ages).

**Authorizations**  
Bearer

**Query Parameters**

| Parameter        | Type     | Required   | Description                                              |
|------------------|----------|------------|----------------------------------------------------------|
| `account_type`   | string   | Optional   | Social media platform type to filter charts for (e.g., 'ig_business', 'fb_page', ...)

**Responses**

- 200: List of available charts with metadata

```json
    [
      {
        "id": "followers",
        "title": "Followers",
        "group_id": "growth",
        "tooltip": "text",
        "type": "vertical",
        "last_value": true,
        "show_percentage": true
      }
    ]
    ```

#### Field Descriptions

| Field       | Description                                                              |
|-------------|--------------------------------------------------------------------------|
| `id`       | Unique chart identifier (use in `chart_ids[]`).                        |
| `title`    | Display title.                                                          |
| `group_id` | Chart group: `growth`, `insights`, `demographics`.                     |
| `tooltip`  | Short explanatory text.                                                 |
| `type`     | Suggested visualization: `vertical`, `horizontal`, `side_by_side`.      |
| `last_value` | Show latest value highlight.                                          |
| `show_percentage` | Indicates client should render as percentage.                     |

### 2. Get Chart Data

Fetch data for one or more charts by ID. Returns current and previous period blocks for comparison.

```
GET /api/v1/analytics/:account_id/chart_data
```

#### Description

Supports growth metrics, post insights, and demographics. Chart IDs must come from the “List Charts” endpoint.

#### URL Parameters

| Parameter     | Type   | Required | Description                                           |
|---------------|--------|----------|-----------------------------------------------------|
| `account_id`  | string | No       | When provided, returns data for that account only; when omitted, returns aggregate across the workspace (where supported).

#### Query Parameters

| Parameter     | Type      | Required | Description                                           |
|---------------|-----------|----------|-----------------------------------------------------|
| `chart_ids[]`| string[]  | Yes      | One or more chart IDs from `/api/v1/analytics/charts`.

### Get Analytics Chart Data

GET  
https://app.publer.com/api/v1/analytics/chart_data

Retrieves analytics data for specific charts by their IDs. Returns current and previous period data for comparison. Supports growth metrics, post insights, and demographic data.

**Responses**

- 200: Analytics chart data with current and previous period values

```json
    {
      "current": {
        "ANY_ADDITIONAL_PROPERTY": {}
      },
      "previous": {
        "ANY_ADDITIONAL_PROPERTY": {}
      }
    }
    ```

#### Structure

| Key       | Description                                                             |
|-----------|-------------------------------------------------------------------------|
| `current` | Object keyed by chart ID with current period series.                    |
| `previous`| Matching structure for the previous (comparison) period.                |

### Usage Notes

- Always fetch chart IDs from `/api/v1/analytics/charts`; charts can change over time.
- If `account_id` is omitted, results are aggregated across accessible accounts (where the metric supports aggregation).
- Ensure `from` ≤ `to` when providing dates.
- Apply client‑side caching for chart definitions to reduce requests.