Skip to content

YouTube Scheduling API

The YouTube Scheduling API helps a product, agency workflow, automation, or AI system place a video or YouTube Shorts upload into a future publishing queue, rather than building queue infrastructure from scratch.

Scheduled YouTube video request
POST {{API_BASE_URL}}/v1/posts
x-access-key: YOUR_API_KEY
Content-Type: application/json

{
    "content": "A short example update.",
    "platforms": [
      {
        "platform": "youtube",
        "accountId": "yt_789",
        "platformSpecificData": {
          "title": "How to Build a Social Media Scheduler",
          "visibility": "public",
          "tags": [
            "tutorial",
            "api",
            "social media"
          ],
          "categoryId": "28"
        }
      }
    ],
    "mediaItems": [
      {
        "type": "video",
        "url": "https://cdn.example.com/tutorial.mp4"
      }
    ],
    "scheduledFor": "2026-09-15T09:00:00",
    "timezone": "America/New_York"
}
Illustrative request
Example line 1

POST {{API_BASE_URL}}/v1/posts

Illustrative request
Example line 2

x-access-key: YOUR_API_KEY

Illustrative request
Example line 3

Content-Type: application/json

A request carries a scheduledFor timestamp and, when local time matters, an IANA timezone; the item then waits in a scheduled state until that moment.

What the YouTube Scheduling API does and who it is for

This API is aimed at teams that need future-dated YouTube publishing inside their own product, agency workflow, automation, or AI system, without operating a publishing queue themselves. A video or YouTube Shorts upload can be queued for a chosen future date and time, with an IANA timezone used to interpret that time locally and return the matching UTC moment. Once connected, the same account can also support publishing, analytics, comment management, and messaging through a single API, keeping scheduling part of a broader social workflow.

Add social media to your product in three steps

Getting started follows three stages. Obtain an API key first. Then connect an account once so publishing, scheduling, analytics, comments, and messaging can all run through that connection. Finally, expose multiple social platforms through the shared API instead of maintaining a separate integration for each one. For scheduling specifically, send the video to POST {{API_BASE_URL}}/v1/posts with a YouTube accountId, mediaItems, and an ISO 8601 scheduledFor value, adding an IANA timezone when the timestamp represents local time. After the call, inspect the returned status and scheduledFor, since the response gives the resolved UTC time rather than simply repeating the local input.

Input contract and worked Video example

One endpoint covers the different publishing formats, with only the format-specific fields changing. The Video example in the code examples below reproduces the captured request and its 202 response exactly: content, a platforms array with platform youtube, accountId yt_789 and platformSpecificData, mediaItems holding a video URL, plus scheduledFor and timezone. There, 2026-09-15T09:00:00 in America/New_York comes back as 2026-09-15T13:00:00.000Z, alongside status scheduled and a postId. Treat the fields shown there as the evidenced contract and do not assume support for fields absent from that example. Before queueing, confirm accountId points to the right connected YouTube account, the mediaItems URL can be reached, and visibility matches the intended setting, such as public or unlisted.

Timezone handling: IANA timezone, UTC resolution, and omitted timezone

Timezone interpretation is where scheduled publishing most often goes wrong. When an IANA timezone such as America/New_York accompanies scheduledFor, the local time is converted and the response carries the UTC equivalent. Omitting timezone changes the meaning entirely: the timestamp is then read as UTC. A reliable routine is to compare input and returned values for every queued item, paying particular attention near daylight-saving changes, and to keep the returned UTC value as the canonical time for calendar display. If that comparison shows a mismatch, correct the timezone or scheduledFor and move the item before it publishes.

Shorts and long-form, metadata settings, and video limits

Standard videos and YouTube Shorts follow the identical scheduling flow. Metadata should be decided before queueing, covering title, tags, visibility, categoryId, audience setting, synthetic media disclosure, and first comment where relevant. YouTube classifies square or vertical clips of up to three minutes as Shorts. The stated limits are 256 GB per file, 15 minutes by default, up to 12 hours for verified accounts, and three minutes for Shorts. Checking duration, file size, orientation, and metadata completeness in advance prevents a queued item from failing to publish as intended.

Reschedule, edit, cancel, and content calendar via API

While an upload is still queued, its details can be revised, its publish time can be moved, or it can be withdrawn before going live; moving the time uses the scheduled-post reschedule endpoint. For calendar planning, create each upload with its own scheduledFor value so weeks or months of content can be queued ahead, then retrieve the scheduled list to render a calendar view. A practical checklist is to fetch queued posts, group them by returned UTC scheduledFor, convert each one into the viewer's timezone for display, and flag anything whose status is no longer scheduled.

Cross-platform queuing and related capabilities

Compatible video content can target YouTube together with other supported platforms in a single request, but every target then shares one scheduledFor and timezone, so this suits only cases where all destinations should go live together. Related YouTube capabilities include posting standard uploads, analytics for performance reporting, and comments for listing, replying to, and deleting. Whether the caller is a developer stack, a no-code workflow, or an AI agent, the API request remains the authoritative record of what is queued and when it will publish.

Timezone decision table
InputExampleResolution / check
scheduledFor + timezone2026-09-15T09:00:00 + America/New_YorkReturns 2026-09-15T13:00:00.000Z
scheduledFor, timezone omitted2026-09-15T09:00:00Treated as UTC
scheduledFor + IANA timezoneLocal time in the named zoneCompare returned UTC value before queueing

Source-stated behavior; runtime parity not tested.

Request field map for POST /v1/posts
FieldShown type / valuePurpose
contentstringPost content / description text
platforms[].platformstring: youtubeTarget platform
platforms[].accountIdstring: yt_789Connected YouTube account
platforms[].platformSpecificData.titlestringYouTube title
platforms[].platformSpecificData.visibilitystring: publicRequested visibility
platforms[].platformSpecificData.tagsstring[]YouTube tags
platforms[].platformSpecificData.categoryIdstring: 28YouTube category
mediaItems[].typestring: videoMedia type
mediaItems[].urlstring URLVideo file URL
scheduledForISO 8601 stringFuture publishing time
timezoneIANA timezone stringLocal timezone for scheduledFor

Fields as shown in captured example; requiredness beyond the example is not independently evidenced.

Lifecycle and edge matrix
State / actionExpected behaviorFailure check
QueuedRemains scheduled until publish timeConfirm status scheduled and postId in response
RescheduleMove queued upload to a new timeConfirm new resolved UTC time
CancelStop publication before it goes liveConfirm item no longer queued
EditChange scheduled upload before publicationRe-check metadata and visibility
Shorts vs long-formSame scheduling flowCheck duration and orientation limits
Video limitsUp to 256 GB; 15 min default; 12 hours verified; Shorts up to 3 minValidate before scheduling

Reschedule/cancel endpoint details not evidenced in captured blocks.

Frequently asked questions

How do I schedule a YouTube video?

Send a request to POST {{API_BASE_URL}}/v1/posts. Include the connected YouTube accountId, the video in mediaItems, and a future ISO 8601 scheduledFor timestamp. Include an IANA timezone if that timestamp should be read as local time.

What happens to a scheduled YouTube video before publish time?

The item stays in a queued, scheduled state until its publish moment arrives. At that point the upload proceeds with the visibility chosen in the request, for example public or unlisted.

How does timezone handling work?

Supply an IANA timezone such as America/New_York together with scheduledFor, and the returned scheduledFor shows the resolved UTC moment. Leaving timezone out means the input is read as UTC.

Can I schedule YouTube Shorts?

Yes, the same request pattern applies. YouTube treats square or vertical clips lasting no more than three minutes as Shorts, so check orientation and duration before queueing.

What are the YouTube video limits?

Stated limits are 256 GB per file, 15 minutes by default, and up to 12 hours for verified accounts. Shorts are capped at three minutes. Validate size and duration before scheduling.

What YouTube settings can I include?

Available settings include title, tags, visibility, audience setting, synthetic media disclosure, category, and a first comment. Confirm each value before the item is queued.

Can I edit, reschedule, or cancel a scheduled YouTube upload?

Yes, while an item is still queued you can revise its details, shift it to a different publish time, or withdraw it entirely before it becomes public.

Who is the YouTube Scheduling API for?

It suits developers, SaaS teams, agencies, automation builders, and AI products that need programmatic scheduling for social publishing.

202 scheduled response
{
    "success": true,
    "status": "scheduled",
    "postId": "post_xyz789",
    "scheduledFor": "2026-09-15T13:00:00.000Z",
    "platforms": [
      {
        "platform": "youtube",
        "success": true
      }
    ]
}