# Charts

The Analytics section provide 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.

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

#### Description

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

#### Query Parameters

<table data-full-width="true"><thead><tr><th width="139.78363037109375">Parameter</th><th width="83.0086669921875">Type</th><th width="115.09356689453125">Required</th><th>Description</th></tr></thead><tbody><tr><td><code>account_type</code></td><td>string</td><td>No</td><td>Filter charts for a specific account type.</td></tr></tbody></table>

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

> 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).

```json
{"openapi":"3.1.1","info":{"title":"Publer API","version":"1.0.0"},"tags":[{"name":"Analytics","description":"Endpoints for retrieving analytics data and charts"}],"servers":[{"url":"https://app.publer.com/api/v1"}],"security":[{"Bearer":[]}],"components":{"securitySchemes":{},"schemas":{"401ErrorResponse":{"type":"object","properties":{"errors":{"type":"array","description":"List of error messages","items":{"type":"string"}}}},"403ErrorResponse":{"type":"object","properties":{"errors":{"type":"array","description":"List of error messages","items":{"type":"string"}}}}}},"paths":{"/analytics/charts":{"get":{"summary":"Get Available Analytics Charts","description":"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).","tags":["Analytics"],"parameters":[{"schema":{"type":"string"},"name":"Publer-Workspace-Id","in":"header","description":"ID of the workspace to retrieve charts from","required":true},{"schema":{"type":"string","enum":["ig_business","fb_page","twitter","linkedin","youtube","tiktok","google","pin_business","pin_personal","threads","wordpress_oauth","in_profile","in_page","mastodon","bluesky"]},"name":"account_type","in":"query","description":"Social media platform type to filter charts for (e.g., 'ig_business', 'fb_page', 'twitter', 'linkedin', 'youtube', 'tiktok', 'google', 'pin_business')","required":false}],"responses":{"200":{"description":"List of available charts with metadata","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the chart"},"title":{"type":"string","description":"Display title of the chart"},"group_id":{"type":"string","description":"Group category (growth, insights, demographics)"},"tooltip":{"type":"string","description":"Tooltip text explaining the chart"},"type":{"type":"string","description":"Chart visualization type","enum":["vertical","horizontal","side_by_side"]},"last_value":{"type":"boolean","description":"Whether to show the most recent value"},"show_percentage":{"type":"boolean","description":"Whether values should be displayed as percentages"}}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/401ErrorResponse"}}}},"403":{"description":"Permission denied or missing required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/403ErrorResponse"}}}}}}}}}
```

#### Field Descriptions

<table data-full-width="true"><thead><tr><th width="214.21484375">Field</th><th>Description</th></tr></thead><tbody><tr><td><code>id</code></td><td>Unique chart identifier (use in <code>chart_ids[]</code>).</td></tr><tr><td><code>title</code></td><td>Display title.</td></tr><tr><td><code>group_id</code></td><td>Chart group: <code>growth</code>, <code>insights</code>, <code>demographics</code>.</td></tr><tr><td><code>tooltip</code></td><td>Short explanatory text.</td></tr><tr><td><code>type</code></td><td>Suggested visualization: <code>vertical</code>, <code>horizontal</code>, <code>side_by_side</code>.</td></tr><tr><td><code>last_value</code></td><td>Show latest value highlight.</td></tr><tr><td><code>show_percentage</code></td><td>Indicates client should render as percentage.</td></tr></tbody></table>

### 2. Get Chart Data

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

```http
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.

For better performance and lower latency, request chart data in small logical batches of related `chart_ids` (e.g., growth first, then insights, then demographics) instead of sending every available chart ID in one call.

#### URL Parameters

<table data-full-width="true"><thead><tr><th width="124.3582763671875">Parameter</th><th width="83.41064453125">Type</th><th width="108.86383056640625">Required</th><th>Description</th></tr></thead><tbody><tr><td><code>account_id</code></td><td>string</td><td>No</td><td>When provided, returns data for that account only; when omitted, returns aggregate across the workspace (where supported).</td></tr></tbody></table>

#### Query Parameters

<table data-full-width="true"><thead><tr><th width="129.170654296875">Parameter</th><th width="184.84124755859375">Type</th><th width="146.0906982421875">Required</th><th>Description</th></tr></thead><tbody><tr><td><code>chart_ids[]</code></td><td>string[]</td><td>Yes</td><td>One or more chart IDs from <code>/api/v1/analytics/charts</code>. Example: <code>chart_ids[]=followers&#x26;chart_ids[]=post_engagement</code></td></tr><tr><td><code>from</code></td><td>string (YYYY-MM-DD)</td><td>Yes if <code>to</code> used</td><td>Start date (inclusive). Defaults to workspace range if omitted with <code>to</code>.</td></tr><tr><td><code>to</code></td><td>string (YYYY-MM-DD)</td><td>Yes if <code>from</code> used</td><td>End date (inclusive). Defaults to workspace range if omitted with <code>from</code>.</td></tr></tbody></table>

## Get 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.

```json
{"openapi":"3.1.1","info":{"title":"Publer API","version":"1.0.0"},"tags":[{"name":"Analytics","description":"Endpoints for retrieving analytics data and charts"}],"servers":[{"url":"https://app.publer.com/api/v1"}],"security":[{"Bearer":[]}],"components":{"securitySchemes":{},"schemas":{"401ErrorResponse":{"type":"object","properties":{"errors":{"type":"array","description":"List of error messages","items":{"type":"string"}}}},"403ErrorResponse":{"type":"object","properties":{"errors":{"type":"array","description":"List of error messages","items":{"type":"string"}}}}}},"paths":{"/analytics/chart_data":{"get":{"summary":"Get Analytics Chart Data","description":"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.","tags":["Analytics"],"parameters":[{"schema":{"type":"string"},"name":"Publer-Workspace-Id","in":"header","description":"ID of the workspace to retrieve data from","required":true},{"schema":{"type":"array","items":{"type":"string"}},"style":"form","explode":true,"name":"chart_ids","in":"query","description":"Array of chart IDs to retrieve data for. Use chart IDs from the /analytics/charts endpoint","required":true},{"schema":{"type":"string"},"name":"account_id","in":"path","description":"Optional account ID to filter analytics data for a specific social media account","required":false},{"schema":{"type":"string","format":"date"},"name":"from","in":"query","description":"Start date for analytics data (YYYY-MM-DD format)","required":false},{"schema":{"type":"string","format":"date"},"name":"to","in":"query","description":"End date for analytics data (YYYY-MM-DD format)","required":false}],"responses":{"200":{"description":"Analytics chart data with current and previous period values","content":{"application/json":{"schema":{"type":"object","properties":{"current":{"type":"object","description":"Current period data for requested charts","additionalProperties":{"type":"object","description":"Chart-specific data structure with metrics and values"}},"previous":{"type":"object","description":"Previous period data for comparison","additionalProperties":{"type":"object","description":"Previous period chart data for trend analysis"}}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/401ErrorResponse"}}}},"403":{"description":"Permission denied or missing required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/403ErrorResponse"}}}}}}}}}
```

#### Structure

<table data-full-width="true"><thead><tr><th width="153.740966796875">Key</th><th>Description</th></tr></thead><tbody><tr><td><code>current</code></td><td>Object keyed by chart ID with current period series.</td></tr><tr><td><code>previous</code></td><td>Matching structure for the previous (comparison) period.</td></tr><tr><td><code>data[]</code></td><td>Array of <code>{ date, value }</code> points.</td></tr><tr><td><code>last_value</code></td><td>Latest cumulative snapshot (growth charts).</td></tr><tr><td><code>total</code></td><td>Period aggregate sum (engagement / sum charts).</td></tr></tbody></table>

### 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).
* The comparison (previous) window automatically matches the current window length.
* Ensure `from` ≤ `to` when providing dates.
* Not all charts are available for every `account_type`.
* Apply client‑side caching for chart definitions to reduce requests.

### Related Resources

* [Accounts API](/docs/api-reference/accounts.md) - Manage social media accounts
* [Hashtag Analysis](/docs/analytics/hashtag-analysis.md) — Track hashtag performance
* [Best Times](/docs/analytics/best-times-to-post.md) — Suggested posting time slots
* [Members](/docs/analytics/members.md) — Member (team) analytics


---

# 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://publer.com/docs/analytics/charts.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.