# Best Times to Post

The Best Times to Post endpoint returns a heatmap of optimal posting times for a specific account, based on historical performance. Use it to power schedule suggestions, calendar overlays, and autofill routines.

### Requirements

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

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

### Endpoint <a href="#endpoint" id="endpoint"></a>

#### Get Best Times to Post

```http
GET /api/v1/analytics/:account_id/best_times
```

#### Description

Retrieves a day/hour heatmap of posting performance tailored to the audience of the specified account. Optionally include competitor data and restrict to a custom date range.

#### URL Parameter

<table><thead><tr><th width="119.40118408203125">Parameter</th><th width="82.78936767578125">Type</th><th width="106.99005126953125">Required</th><th>Description</th></tr></thead><tbody><tr><td><code>account_id</code></td><td>string</td><td>No</td><td>Social account to analyze. Omit for all workspace accounts.</td></tr></tbody></table>

#### Query Parameters

<table><thead><tr><th width="141.52471923828125">Parameter</th><th width="179.1859130859375">Type</th><th width="107.7215576171875">Required</th><th>Description</th></tr></thead><tbody><tr><td><code>competitors</code></td><td>string</td><td>No</td><td>For competitor data. <code>true</code> or <code>false</code> (default <code>false</code>).</td></tr><tr><td><code>competitor_id</code></td><td>string</td><td>No</td><td>Analyze a specific competitor (requires <code>competitors=true</code>).</td></tr><tr><td><code>from</code></td><td>date (YYYY-MM-DD)</td><td>Yes</td><td>Start date (inclusive).</td></tr><tr><td><code>to</code></td><td>date (YYYY-MM-DD)</td><td>Yes</td><td>End date (inclusive).</td></tr></tbody></table>

## Get Best Times to Post for Account

> Retrieves the optimal posting times for a specific social media account based on historical analytics data. Returns a heatmap of posting performance across days of the week and hours of the day, tailored to the specified account's audience engagement patterns.

```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/{account_id}/best_times":{"get":{"summary":"Get Best Times to Post for Account","description":"Retrieves the optimal posting times for a specific social media account based on historical analytics data. Returns a heatmap of posting performance across days of the week and hours of the day, tailored to the specified account's audience engagement patterns.","tags":["Analytics"],"parameters":[{"schema":{"type":"string"},"name":"Publer-Workspace-Id","in":"header","description":"ID of the workspace to retrieve best times from","required":true},{"schema":{"type":"string"},"name":"account_id","in":"path","description":"Social media account ID to analyze posting times for. When provided, analysis is specific to this account's performance data","required":false},{"schema":{"type":"string","enum":["true","false"]},"name":"competitors","in":"query","description":"Include competitor data in best times analysis. Set to 'true' to analyze competitor posting patterns","required":false},{"schema":{"type":"string"},"name":"competitor_id","in":"query","description":"Specific competitor ID to analyze. Used in conjunction with competitors=true parameter","required":false},{"schema":{"type":"string","format":"date"},"name":"from","in":"query","description":"Start date for analytics data range (YYYY-MM-DD format). Filters data from this date onwards","required":true},{"schema":{"type":"string","format":"date"},"name":"to","in":"query","description":"End date for analytics data range (YYYY-MM-DD format). Filters data up to this date","required":true}],"responses":{"200":{"description":"Best times to post data organized by day of the week and hour for the specific account","content":{"application/json":{"schema":{"type":"object","description":"Heatmap data showing optimal posting times with scores for each hour of each day, specific to the account's audience","additionalProperties":{"type":"array","description":"Array of 24 hourly scores (0-23) for each day of the week","items":{"type":"number","description":"Engagement score for this hour (higher = better posting time)"}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/401ErrorResponse"}}}},"403":{"description":"Permission denied - requires analytics access or paying subscription","content":{"application/json":{"schema":{"$ref":"#/components/schemas/403ErrorResponse"}}}}}}}}}
```

#### Structure

* Object keyed by day of week (`Monday`..`Sunday`).
* Each day maps to an array of 24 numbers (hour indexes `0..23`).
* Each number is a relative engagement/performance score (higher = better posting time). Use for ranking and heatmap intensity; not a percentage.

### Notes

* Default window: If no dates are provided, best times are computed from recent history (commonly last 7 days).
* Workspace/account settings (e.g., “day starts at” and “week starts on”) influence the visualization in the app; the API always returns 24 hourly slots per day.
* Heatmap scores are relative within the dataset; normalize in your UI if combining multiple accounts.
* Competitor view requires `competitors=true`; use `competitor_id` to focus on a single competitor.
* Data refreshes automatically (about every 24 hours). Use Sync Insights in the UI for on‑demand refresh.

### Related Resources

* [Charts](https://publer.com/docs/analytics/charts) — Discover chart IDs and fetch chart data
* [Post Insights](https://publer.com/docs/analytics/post-insights) — Per‑post performance analytics
* [Hashtag Analysis](https://publer.com/docs/analytics/hashtag-analysis) — Hashtag performance
* [Members](https://publer.com/docs/analytics/members) — Workspace member analytics