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

Get Best Times to Post

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

Parameter	Type	Required	Description
account_id	string	No	Social account to analyze. Omit for all workspace accounts.

Query Parameters

Parameter	Type	Required	Description
competitors	string	No	For competitor data. true or false (default false).
competitor_id	string	No	Analyze a specific competitor (requires competitors=true).
from	date (YYYY-MM-DD)	Yes	Start date (inclusive).
to	date (YYYY-MM-DD)	Yes	End date (inclusive).

Get Best Times to Post for Account

get

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.

Path parameters

account_idstringOptional

Social media account ID to analyze posting times for. When provided, analysis is specific to this account's performance data

Query parameters

competitorsstring · enumOptional

Include competitor data in best times analysis. Set to 'true' to analyze competitor posting patterns

Possible values:

competitor_idstringOptional

Specific competitor ID to analyze. Used in conjunction with competitors=true parameter

fromstring · dateRequired

Start date for analytics data range (YYYY-MM-DD format). Filters data from this date onwards

Example: {"value":"2024-01-01"}

tostring · dateRequired

End date for analytics data range (YYYY-MM-DD format). Filters data up to this date

Example: {"value":"2024-12-31"}

Header parameters

Publer-Workspace-IdstringRequired

ID of the workspace to retrieve best times from

Responses

200

Best times to post data organized by day of the week and hour for the specific account

application/json

401

Unauthorized

application/json

403

Permission denied - requires analytics access or paying subscription

application/json

get

HTTPcURLJavaScriptPython

GET /api/v1/analytics/{account_id}/best_times HTTP/1.1
Host: app.publer.com
Publer-Workspace-Id: text
Accept: */*

{
  "Monday": [
    0,
    0,
    0,
    0,
    0,
    0,
    5,
    12,
    18,
    25,
    22,
    15,
    8,
    10,
    16,
    20,
    18,
    14,
    12,
    8,
    5,
    3,
    1,
    0
  ],
  "Tuesday": [
    0,
    0,
    0,
    0,
    0,
    0,
    6,
    15,
    20,
    28,
    25,
    18,
    10,
    12,
    18,
    22,
    20,
    16,
    14,
    10,
    6,
    4,
    2,
    0
  ],
  "Wednesday": [
    0,
    0,
    0,
    0,
    0,
    0,
    7,
    16,
    22,
    30,
    27,
    20,
    12,
    14,
    20,
    24,
    22,
    18,
    16,
    12,
    8,
    5,
    3,
    0
  ]
}

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 — Discover chart IDs and fetch chart data

• Post Insights — Per‑post performance analytics

• Hashtag Analysis — Hashtag performance

• Members — Workspace member analytics