# 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](/docs/analytics/charts.md) — Discover chart IDs and fetch chart data
* [Post Insights](/docs/analytics/post-insights.md) — Per‑post performance analytics
* [Hashtag Analysis](/docs/analytics/hashtag-analysis.md) — Hashtag performance
* [Members](/docs/analytics/members.md) — Workspace member 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/best-times-to-post.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.