Uploading to YouTube by API: the audit that locks your videos private

There are two facts about the YouTube Data API that decide whether an upload pipeline is worth building, and neither appears in most guides until after you have built it.

Videos uploaded by an unverified API project are locked to private, and that cannot be appealed. And the default daily quota allows roughly six uploads a day, not because of a rate limit but because of how the quota is priced. Both are solved by the same audit, and the audit takes time you have to plan for rather than discover.

What we'll cover

• The private lock, and why it cannot be appealed
• The quota arithmetic
• What the audit involves
• Credentials: OAuth, not an API key
• Building it with CodeWords
• Uploading a large file properly
• Metadata, and where the limits are
• What the API will not do
• Failure modes worth handling
• Making it survive
• Limits worth knowing about
• What to check first
• Frequently asked questions

The private lock, and why it cannot be appealed

Videos uploaded through videos.insert by an API project that has not passed a compliance audit are restricted to private, and for projects created since 28 July 2020 this is the default state of affairs.

The part that hurts: you cannot appeal a video locked this way. The remedy is to re-upload it through a verified project or through the YouTube app or website (YouTube's quota and compliance audits guide, videos locked as private).

So the order of work matters enormously. Build the pipeline, upload a month of content, then discover the lock, and that month has to be re-uploaded by hand. Check your project's status before the first real upload and the problem does not exist.

Test with content you do not mind re-doing until you have confirmed a video goes out at the privacy status you asked for.

The quota arithmetic

The second constraint is quantitative and catches people who reason about it as a rate limit.

A project enabling the YouTube Data API gets a default allocation of 10,000 units per day, and operations cost different amounts. An upload is expensive relative to reads, which is why the practical ceiling on default quota is around six uploads a day rather than anything resembling a bulk pipeline.

Three consequences.

Count your units before designing the schedule, rather than assuming you can upload as often as you like.

Reads are cheap and searches are not. A pipeline that searches before every upload will spend its quota on the search.

Quota resets daily, on Pacific time, which is worth knowing when a run fails at what looks like an arbitrary hour.

Raising the allocation requires the same audit as lifting the private lock, which is the argument for doing it once, early.

What the audit involves

It is a review of whether your use complies with the API Services Terms, submitted through YouTube's audit and quota extension form.

Expect to describe what your project does, who uses it, and how. A project that uploads a creator's own content to their own channel is a straightforward case. A project uploading on behalf of many unrelated users, or republishing content that is not yours, is a harder one and should expect questions.

Two practical points. Submit early, because the review takes time and it gates both the private lock and any quota increase. And describe the actual use rather than an aspirational one, since a mismatch between what you said and what the project does is the thing that causes trouble later.

Credentials: OAuth, not an API key

A common first wrong turn. An API key identifies a project and authorises nothing on a user's behalf, so it can read public data and cannot upload.

Uploading requires OAuth 2.0 with the appropriate upload scope, and the account that authorises must own or manage the channel being uploaded to. If the channel is a brand account, the authorising Google account needs the right permissions on it, which is a separate thing from owning the login.

One trap carries over from Google OAuth generally. While the consent screen is in Testing status, refresh tokens expire after seven days, so an upload pipeline that works all week will fail the next one. Move the project to production before relying on it. The general picture is in which Google credential you need.

Building it with CodeWords

CodeWords connects to more than 3,000 integrations, and the connection is made once and reused.

1. Open CodeWords and start a new automation.
2. Describe what should happen in plain language to Cody, the automation builder: where the video comes from, what metadata it should carry, and whether it publishes or stays private for review.
3. Authorize the connections to your storage, your YouTube account and anywhere you want to be notified.
4. Describe the exceptions: an upload that fails partway, a quota exhaustion, a file that is not what was expected.
5. Default new uploads to private and publish deliberately, so a pipeline problem produces an unlisted video rather than a public mistake.

You describe the outcome; Cody builds it, connects it, and deploys it. The free plan covers light use, with Pro at $39 per month and Business at $100 per month as usage grows; details are on the pricing page.

Uploading a large file properly

Video files are large enough that the naive approach fails on real connections.

Use a resumable upload rather than a single request. It survives an interruption, it can be continued rather than restarted, and it gives you progress. A two-gigabyte upload that fails at ninety per cent and starts again is how an afternoon disappears.

Related details worth getting right: set the content type correctly, do not hold the whole file in memory, and treat the upload as a long operation rather than something to run inside a short-lived request.

Check what came back. A successful call returns a video id, and that id is what you need for the thumbnail, the playlist and any later update. Losing it means finding the video by title, which is unreliable.

Metadata, and where the limits are

The upload takes the metadata with it, and the limits are firm.

Title up to 100 characters. Description up to 5,000. Tags exist but count against a combined character budget rather than a simple count. Category is an id rather than a name. Privacy status is one of private, unlisted or public, and a scheduled publish time only applies to videos that are private.

Thumbnails are a separate call after the upload, and custom thumbnails require the channel to be verified. That is a channel-level requirement rather than an API one, and it is the most common reason a thumbnail call fails on an otherwise working pipeline.

Truncate deliberately rather than letting the API reject the request. A description generated without a length check will eventually exceed 5,000 characters and fail the whole upload.

What the API will not do

Worth knowing before you plan around it.

It will not set some monetisation properties, which remain in Studio. It will not perform many Shorts-specific operations. It will not give you all the analytics available in the interface, which is a different API. And it will not let you bulk-edit as freely as the web interface does.

Anything you cannot do through the API is a manual step, and a pipeline that is ninety per cent automated with a manual step in the middle needs that step to be visible rather than assumed.

Failure modes worth handling

Quota exhausted. Stop cleanly, say so, and resume after the reset rather than retrying into a wall.

Token expired or revoked. Detect and alert. Silent failure means discovering a gap in the schedule weeks later.

Upload interrupted. Resume rather than restart.

Video locked private. Check the project status; this is the audit.

Thumbnail rejected. Usually channel verification, occasionally the file size limit.

Duplicate upload. A retry that succeeded the first time. Record the video id at the moment the upload completes, before any later step can fail.

Making it survive

Confirm audit status before the first real upload.

Budget the quota and alert before it is exhausted rather than after.

Keep the project in production status, not Testing.

Record the video id immediately on success.

Default to private and publish deliberately.

Limits worth knowing about

Unverified projects upload to private, with no appeal, and re-uploading is the only remedy.

Default quota allows roughly six uploads a day, not a bulk pipeline.

An API key cannot upload. OAuth with the upload scope is required.

Custom thumbnails need a verified channel, independent of the API.

Some operations are not available through the API at all, and remain manual.

What to check first

Whether your API project has passed the compliance audit. One check, before writing any upload code, and it determines whether the entire pipeline produces publishable videos or a folder of private ones you cannot appeal. Everything else here is ordinary engineering; this one is a wall.

Two habits make the difference. Submit the audit early, because it gates both the private lock and any quota increase, and the review takes time you cannot compress. And record the video id the moment an upload completes, since it is the handle for every later step and finding a video by title afterwards is unreliable.

Frequently asked questions

Why are my API-uploaded videos private?

Because the API project has not passed a compliance audit. Uploads from unverified projects are restricted to private, and for projects created since 28 July 2020 that is the default.

Can I appeal a video locked as private?

No. The remedy is to re-upload it through a verified project or through the YouTube app or website, which is why it is worth checking your project status before uploading anything real.

How many videos can I upload per day?

On the default allocation of 10,000 units, roughly six, because an upload is expensive relative to other operations. Raising it requires the same audit that lifts the private lock.

Can I upload with an API key?

No. An API key authorises nothing on a user's behalf. Uploading requires OAuth 2.0 with the upload scope, authorised by an account with rights on the target channel.

Why did my pipeline stop working after a week?

Most likely the OAuth consent screen is still in Testing status, where refresh tokens expire after seven days. Move the project to production.

What does the audit involve?

A review of whether your use complies with the API Services Terms, submitted through YouTube's audit and quota extension form. Describe the actual use rather than an aspirational one.

How should large files be uploaded?

With a resumable upload, so an interruption can be continued rather than restarting a multi-gigabyte transfer. Treat it as a long operation rather than something inside a short request.

What are the metadata limits?

Title 100 characters, description 5,000, tags against a combined character budget, category as an id, and scheduled publishing only for private videos. Truncate deliberately rather than letting the request fail.

Why is my thumbnail upload failing?

Usually because custom thumbnails require a verified channel, which is a channel-level requirement independent of the API.

What cannot be done through the API?

Some monetisation settings, many Shorts-specific operations, and the full analytics available in the interface. Those remain manual steps and should be visible in the process rather than assumed.

Related reading

• Which Google credential you need
• Where AI actually helps a channel
• Managing credentials across automations