GETInsights4–6 credits

Best time to post

GET https://api.instagramapi.dev/v1/insights/profile/best-time

Analyzes when an account's recent posts earned the most engagement and returns the best hours and weekdays to post. Pass `posts` (1–50, default 30) to set the analysis window and `timezone` (UTC offset hours, e.g. `-5` for US East) to localize results. Cost: 4–6 credits depending on the analysis window.

Build this with an AI agent

Paste this prompt into Claude, Codex, or any coding agent.

Parameters

Name	Type	Required	Description
handle	string	yes	An Instagram account. Accepts a username (`nike`), a numeric user id (`13460080`), or a full profile URL (`https://instagram.com/nike`). We resolve it automatically.
posts	number	no	Recent posts to analyze (1–50). Defaults to 30.
timezone	number	no	UTC offset in hours to localize the hour/day buckets (e.g. -5). Defaults to 0 (UTC).

Example request

curl "https://api.instagramapi.dev/v1/insights/profile/best-time?handle=nike&posts=30&timezone=-5" \
  -H "Authorization: Bearer $INSTAGRAMAPI_KEY"

const res = await fetch("https://api.instagramapi.dev/v1/insights/profile/best-time?handle=nike&posts=30&timezone=-5", {
  headers: { Authorization: `Bearer ${process.env.INSTAGRAMAPI_KEY}` },
});

res = requests.get("https://api.instagramapi.dev/v1/insights/profile/best-time?handle=nike&posts=30&timezone=-5",
    headers={"Authorization": f"Bearer {INSTAGRAMAPI_KEY}"})

Try it

Live request · uses 4 credits

API key

handle *string

postsnumber

timezonenumber

Example responses

Switch tabs to see the body shape for success and each error status.

{
  "data": {
    "username": "nike",
    "posts_analyzed": 30,
    "timezone_offset": -5,
    "best_hours": [
      {
        "hour": 18,
        "posts": 6,
        "avg_engagement": 521340
      }
    ],
    "best_days": [
      {
        "day": "Thursday",
        "posts": 5,
        "avg_engagement": 498120
      }
    ],
    "recommendation": "Thursday around 18:00 (UTC-5)",
    "by_hour": [
      {
        "hour": 18,
        "posts": 6,
        "avg_engagement": 521340
      }
    ],
    "by_day": [
      {
        "day": "Thursday",
        "posts": 5,
        "avg_engagement": 498120
      }
    ]
  },
  "meta": {
    "endpoint": "insights/profile/best-time",
    "request_id": "req_3f8a1c9e",
    "credits_charged": 4,
    "credits_remaining": 4987,
    "ms": 412
  }
}

{
  "error": {
    "code": "missing_parameter",
    "message": "Missing required parameter \"handle\".",
    "docs": "/docs/insights/profile/best-time"
  },
  "meta": {
    "request_id": "req_3f8a1c9e"
  }
}

{
  "error": {
    "code": "invalid_api_key",
    "message": "This API key is invalid or has been revoked.",
    "docs": "/docs#authentication"
  },
  "meta": {
    "request_id": "req_3f8a1c9e"
  }
}

{
  "error": {
    "code": "insufficient_credits",
    "message": "You're out of credits. Top up to continue.",
    "docs": "/dashboard/billing"
  },
  "meta": {
    "request_id": "req_3f8a1c9e"
  }
}

{
  "error": {
    "code": "not_found",
    "message": "No public data for that request (private, deleted, or nonexistent). This is a billed request. We queried Instagram on your behalf.",
    "docs": "/docs/insights/profile/best-time"
  },
  "meta": {
    "request_id": "req_3f8a1c9e",
    "endpoint": "insights/profile/best-time",
    "credits_charged": 4,
    "credits_remaining": 4985
  }
}

{
  "error": {
    "code": "upstream_error",
    "message": "Upstream data provider error. You were not charged. Please retry.",
    "docs": "/docs/insights/profile/best-time"
  },
  "meta": {
    "request_id": "req_3f8a1c9e"
  }
}

Response fields

Fields returned under data on a 200 response. Every response also includes a meta object with billing info.

Field	Type	Description
username	string	The account's @handle.
posts_analyzed	number	How many recent posts were analyzed.
timezone_offset	number	UTC offset (hours) used to localize the hour/day buckets.
best_hours	array<object>	Top hours to post, ranked by average engagement.
best_hours[].hour	number	Hour of day (0–23) in the requested timezone.
best_hours[].posts	number	Number of analyzed posts that fell in this bucket.
best_hours[].avg_engagement	number	Average interactions (likes + comments) for posts in this bucket.
best_days	array<object>	Top weekdays to post, ranked by average engagement.
best_days[].day	string	Weekday name.
best_days[].posts	number	Number of analyzed posts that fell in this bucket.
best_days[].avg_engagement	number	Average interactions (likes + comments) for posts in this bucket.
recommendation	string	Plain-English summary of the single best time to post.
by_hour	array<object>	Engagement broken down by hour of day.
by_hour[].hour	number	Hour of day (0–23) in the requested timezone.
by_hour[].posts	number	Number of analyzed posts that fell in this bucket.
by_hour[].avg_engagement	number	Average interactions (likes + comments) for posts in this bucket.
by_day	array<object>	Engagement broken down by weekday.
by_day[].day	string	Weekday name.
by_day[].posts	number	Number of analyzed posts that fell in this bucket.
by_day[].avg_engagement	number	Average interactions (likes + comments) for posts in this bucket.