Meta Documents Four Different Limits for Facebook scheduled_publish_time

What is Facebook scheduled_publish_time?

The Facebook scheduled_publish_time field is the Graph API parameter that tells Meta when an unpublished Page post should go live, and you send it in the same POST that creates the post. It exists on /{page-id}/feed for text and link posts, on /{page-id}/videos for video, and on /{page-id}/photos for photos.

Meta's Pages API posts guide lists it as a sub-item of published, which is the first thing to understand about it: "published set to true to publish the post immediately (default) or false to publish later". Directly under that line: "Include scheduled_publish_time if set to false".

The guide's own example request looks like this:

curl -X POST "https://graph.facebook.com/v25.0/page_id/feed" \
  -H "Content-Type: application/json" \
  -d '{
    "message":"your_message_text",
    "link":"your_url",
    "published":"false",
    "scheduled_publish_time":"unix_time_stamp_of_a_future_date",
  }'

On success the response is the ID of a post that exists but has not appeared on the Page yet: {"id": "page_post_id"}. The rest of this page covers the three things that decide whether that request works: the published flag, the time format, and the lead time.

Does scheduled_publish_time require published=false?

Yes. A scheduled Page post is an unpublished post with a date attached, so the two parameters travel together. Leave published at its default of true and the post goes out immediately.

Photos add a step. The Page Photos reference says that a photo used in a scheduled post must be uploaded with temporary=true, and it describes that parameter in one line: "published must be false, and you can't set scheduled_publish_time". The schedule goes on the feed post that attaches the photos, not on the photos themselves. For a multi-photo post, Meta writes: "When the photos are part of a scheduled post, the published, scheduled_publish_time, and unpublished_content_type parameters must be included." Its example sends published=false, scheduled_publish_time=1512068400 and unpublished_content_type=SCHEDULED to /feed.

Upload those photos shortly before you create the post. Meta states that an unpublished upload "will remain on Facebook servers for about 24 hours. If you do not publish these photos within 24 hours, we delete them."

One slip in the Page Feed reference is worth knowing about before you copy code from it. Its parameter table names the flag published, while its "Posting a Link to a Page" section tells you to "Set the publish parameter to 1 to publish the post immediately or to 0 to create an unpublished post to be published later". The sample request underneath that sentence sends published=1. Go with published.

Which time formats does scheduled_publish_time accept?

The Pages API posts guide lists three formats:

The guide's link text spells the standard "ISO 8061". The link itself points at ISO 8601, and the example is a valid ISO 8601 string, so read it as a typo.

The reference pages are narrower than the guide. The Page Feed reference types the parameter as timestamp and calls it a "UNIX timestamp indicating when post should go live." The Page Photos and Page Videos references both type it as int64. Only the guide mentions strings. A UNIX integer in seconds is the one format every page accepts, so send that. JavaScript's Date.now() returns milliseconds, which gives a number 1,000 times too large, so divide before you send it.

If you do use a relative string, Meta tells you how to check the result: "If you are relying on strtotime()'s relative date strings you can read-after-write the scheduled_publish_time of the created post to make sure it is what is expected." tomorrow depends on which server clock and time zone parses it, and Meta says nothing about either.

Reading the value back has its own quirk. In the Page Feed reference's field list, the read-side field is spelled sheduled_publish_time, missing a "c", and typed as float. The Page Post reference spells it correctly as scheduled_publish_time. Request the correct spelling.

How far ahead can you schedule with scheduled_publish_time?

At least 10 minutes. The maximum depends on which Meta page you read, and the pages disagree.

The 10 minute floor is the only number all of them agree on. Mastodon's floor is half that, and its docs say it in one line, "Must be at least 5 minutes in the future", which is why the Mastodon API scheduled_at needs 5 minutes of lead time.

The disagreement on /feed matters most, because text posts, link posts and scheduled multi-photo posts all go through it. Two Meta pages give two ceilings for the same parameter on the same endpoint: the guide says 30 days, the reference says 75. Nothing on either page says which one is current, and neither page mentions the other number. A tool that allows 75 days will work if the reference is right and fail somewhere between day 31 and day 75 if the guide is right. A tool that caps at 30 days works either way. Cap at 30.

The video number needs a second look too. The feed pages measure from "the time of the API request". The video reference measures from "the time of publishing the video", which is ambiguous for a video whose upload finishes minutes after the request that started it. Leave a margin at both ends.

Meta's photo and video references also list more unpublished states than they explain. Both pages list unpublished_content_type values including SCHEDULED, SCHEDULED_RECURRING, DRAFT and PUBLISH_PENDING, and neither one says what SCHEDULED_RECURRING does. Stick to SCHEDULED.

What error does Meta return when the time is out of range?

Meta does not publish one. None of the pages above quotes an error message for a scheduled_publish_time that is too early or too late. The Page Videos and Page Post references both list error 100, "Invalid parameter", as their general validation failure, and that is as specific as Meta's documentation gets.

Build your handling around the code. Meta's own Marketing API error reference gives the reason in one line: "Error handling should be done using only the Error Codes. The Description string is subject to change without prior notice." Log the message and fbtrace_id fields for debugging, but key retry logic on code. Meta's error handling guide describes fbtrace_id as an "Internal support identifier", which is the value to give Meta support.

A time-window rejection is also not a retryable error. Retrying the same request sends the same bad timestamp and gets the same 100. Validate the window before the call: at least 10 minutes and at most 30 days ahead for /feed, measured against your server's clock in UTC seconds. YouTube schedules uploads through different fields with different failure modes, and every field in YouTube's scheduling flow, and how each one fails, is covered separately.

How do you change or cancel a scheduled Facebook post?

Update it with a POST to /{page_post_id}, or delete it with a DELETE to the same path. The Page Post reference's update parameters include both scheduled_publish_time and is_published, but the table gives neither one a description beyond its own name. The Pages API guide adds one constraint: "An app can only update a Page post if the post was made using that app." By that rule, a post scheduled in Meta Business Suite is not one your app can edit.

To find scheduled posts, read /{page-id}/feed with the is_published field. The Page Feed reference says so directly: "Published and unpublished posts will be returned when querying the /{page-id}/feed endpoint. Use the 'is_publishedfield to return only published posts." Meta defines the field as one that "Indicates whether a scheduled post was published (applies to scheduled Page Post only, for users post and instantly published posts this value is alwaystrue`)."

That feed behaviour catches people who sync a Page's posts into a database. A job that reads /feed without asking for is_published collects scheduled posts as though they were live. Always request the field, and filter on it. For a view of how different schedulers expose this across networks, see how nine social media scheduling APIs compare.

Frequently asked questions

What is the minimum lead time for Facebook scheduled_publish_time?

Ten minutes. The Pages API posts guide and the Page Feed reference measure the 10 minute floor from the time of the API request, the Page Videos reference measures it from the time of publishing the video, and the Reels publishing guide requires a time more than 10 minutes out. The Page Photos reference states no range at all.

What is the maximum scheduling window for a Facebook Page post through the API?

Meta publishes two numbers for /feed. The Pages API posts guide says 30 days, and the Page Feed reference says 75 days. For videos on /{page-id}/videos, the Page Videos reference says 6 months, and for Reels on /{page-id}/video_reels the Reels publishing guide says 29 days. Capping feed posts at 30 days works whichever page is correct.

Do I have to set published=false to use scheduled_publish_time?

Yes. Meta's guide makes scheduled_publish_time conditional on published being false. With the default of true, the post goes live immediately.

Can scheduled_publish_time be an ISO 8601 date string?

The Pages API posts guide accepts ISO 8601, with the example 2018-09-01T10:15:30+01:00, as well as strtotime() strings like +2 weeks. The reference pages type the field as a UNIX timestamp or int64, so an integer in seconds is the safest choice.

What error does the Graph API return for a scheduled_publish_time outside the window?

Meta does not document a specific message. The Page Videos and Page Post references list code 100, "Invalid parameter", as their general validation error. Handle the code and log the message, since Meta warns that description strings can change without notice.

How do I list scheduled posts on a Facebook Page through the API?

Query /{page-id}/feed and request the is_published field. Meta returns published and unpublished posts together on that endpoint, and is_published is false for a post that is still scheduled.

Should scheduled_publish_time be in seconds or milliseconds?

Seconds. Meta's Pages API guide asks for an integer UNIX timestamp in seconds. JavaScript's Date.now() returns milliseconds, a number 1,000 times too large, so divide it by 1,000 before you send it.

Does scheduled_publish_time use UTC or my local time zone?

A UNIX timestamp in seconds marks one absolute moment, so it carries no time zone. Meta does not say which clock or time zone parses a string like tomorrow, so send an integer instead. Check the 10 minute minimum and your ceiling against your server's clock in UTC seconds.

Can I edit a post scheduled in Meta Business Suite through the API?

Not with your own app. The Pages API guide says "An app can only update a Page post if the post was made using that app", so a post scheduled in Meta Business Suite is not one your app can edit. Posts your app created can be updated with a POST to /{page_post_id}.

Does scheduled_publish_time work for Facebook Reels?

It does, with two differences. Reels go through /{page-id}/video_reels, and the field takes a Unix timestamp only. It pairs with video_state=SCHEDULED instead of published=false, and the Reels publishing guide requires a time more than 10 minutes out and within 29 days.