curl --request GET \
--url 'https://www.genviral.io/api/partner/v1/analytics/best-times?timezone=Europe/Amsterdam&platform=tiktok&range=90d&count=3' \
--header 'Authorization: Bearer <token>'
{
"ok": true,
"code": 200,
"message": "Best posting times retrieved",
"data": {
"status": "ok",
"range": "90d",
"platform": "tiktok",
"timezone": "Europe/Amsterdam",
"analyzed_post_count": 42,
"times": [
{
"rank": 1,
"day_of_week": "tuesday",
"hour": 18,
"post_count": 6,
"average_views": 15200,
"average_engagement_rate": 0.081,
"views_vs_average": 1.67,
"explanation": "This slot averaged 8.1% engagement across 6 observed post(s)."
},
{
"rank": 2,
"day_of_week": "saturday",
"hour": 11,
"post_count": 4,
"average_views": 9800,
"average_engagement_rate": 0.064,
"views_vs_average": 1.08,
"explanation": "This slot averaged 6.4% engagement across 4 observed post(s)."
}
]
}
}
{
"ok": true,
"code": 200,
"message": "Best posting times retrieved",
"data": {
"status": "insufficient_data",
"range": "30d",
"platform": null,
"timezone": "Europe/Amsterdam",
"analyzed_post_count": 0,
"times": []
}
}
Analytics
Get Best Posting Times
Rank the weekdays and hours when your own published posts performed best, from your Genviral analytics.
GET
/
api
/
partner
/
v1
/
analytics
/
best-times
curl --request GET \
--url 'https://www.genviral.io/api/partner/v1/analytics/best-times?timezone=Europe/Amsterdam&platform=tiktok&range=90d&count=3' \
--header 'Authorization: Bearer <token>'
{
"ok": true,
"code": 200,
"message": "Best posting times retrieved",
"data": {
"status": "ok",
"range": "90d",
"platform": "tiktok",
"timezone": "Europe/Amsterdam",
"analyzed_post_count": 42,
"times": [
{
"rank": 1,
"day_of_week": "tuesday",
"hour": 18,
"post_count": 6,
"average_views": 15200,
"average_engagement_rate": 0.081,
"views_vs_average": 1.67,
"explanation": "This slot averaged 8.1% engagement across 6 observed post(s)."
},
{
"rank": 2,
"day_of_week": "saturday",
"hour": 11,
"post_count": 4,
"average_views": 9800,
"average_engagement_rate": 0.064,
"views_vs_average": 1.08,
"explanation": "This slot averaged 6.4% engagement across 4 observed post(s)."
}
]
}
}
{
"ok": true,
"code": 200,
"message": "Best posting times retrieved",
"data": {
"status": "insufficient_data",
"range": "30d",
"platform": null,
"timezone": "Europe/Amsterdam",
"analyzed_post_count": 0,
"times": []
}
}
Ranks the weekday and hour slots where your own published posts did best. It reads the analytics of
the workspace (for a workspace key) or your personal space (for a personal key) and counts only
your own posts: posts from your connected accounts and posts published through Genviral. Accounts
you only track for research are left out. It never falls back to generic platform advice.
Behavior
- Each published post is placed in a slot by the weekday and hour it went out, in the
timezoneyou send. - Slots are ranked mainly by average engagement rate, then by average views and by how many posts back them.
- When none of your own posts in the range has analytics,
statusisinsufficient_dataandtimesis empty. Try a longerrange, or drop theplatformfilter. - Read-only: nothing is scheduled and no credits are used.
Query Parameters
string
required
IANA time zone the slots are computed in, for example
Europe/Amsterdam.string
Only rank posts from one platform:
tiktok, instagram, youtube, facebook, linkedin, x,
threads, pinterest, or bluesky. Omit it to rank all platforms together.string
default:"90d"
How far back to look:
30d, 90d, or 180d.number
default:"3"
How many slots to return. Range:
1-5.Response
string
ok when at least one slot was ranked, otherwise insufficient_data.string
The range that was analyzed.
string | null
The platform filter, or
null when all platforms were ranked together.string
The time zone the slots are expressed in.
number
Number of published posts the ranking was built from.
array
Best slots, best first. At most
count items.Show Time Object
Show Time Object
number
Position in the ranking, starting at
1.string
monday through sunday.number
Hour of the day in
timezone, from 0 to 23.number
Number of posts published in this slot.
number
Average views of those posts.
number
Average engagement rate of those posts, as a fraction (
0.081 is 8.1%).number | null
This slot’s average views divided by the average views of all analyzed posts, rounded to
two decimals.
1.67 means 67% more views than usual. null when the posts have no views
to compare against.string
One plain sentence explaining the slot.
curl --request GET \
--url 'https://www.genviral.io/api/partner/v1/analytics/best-times?timezone=Europe/Amsterdam&platform=tiktok&range=90d&count=3' \
--header 'Authorization: Bearer <token>'
{
"ok": true,
"code": 200,
"message": "Best posting times retrieved",
"data": {
"status": "ok",
"range": "90d",
"platform": "tiktok",
"timezone": "Europe/Amsterdam",
"analyzed_post_count": 42,
"times": [
{
"rank": 1,
"day_of_week": "tuesday",
"hour": 18,
"post_count": 6,
"average_views": 15200,
"average_engagement_rate": 0.081,
"views_vs_average": 1.67,
"explanation": "This slot averaged 8.1% engagement across 6 observed post(s)."
},
{
"rank": 2,
"day_of_week": "saturday",
"hour": 11,
"post_count": 4,
"average_views": 9800,
"average_engagement_rate": 0.064,
"views_vs_average": 1.08,
"explanation": "This slot averaged 6.4% engagement across 4 observed post(s)."
}
]
}
}
{
"ok": true,
"code": 200,
"message": "Best posting times retrieved",
"data": {
"status": "insufficient_data",
"range": "30d",
"platform": null,
"timezone": "Europe/Amsterdam",
"analyzed_post_count": 0,
"times": []
}
}
Error Responses
401- authentication failed (missing, invalid, or revoked token)422 invalid_payload- a query parameter is missing or invalid;fieldsnames each one500 best_times_failed- unexpected error while reading analytics
error_code field.