The Semust YouTube API returns YouTube data as clean, structured JSON from one endpoint: search rankings for a keyword (videos, Shorts, playlists, channels and ads), full video details, transcripts with optional translation, and the comments of any public video. Pick the report with type, send a keyword or a video URL, and get the answer as a viewer in that country would see it. No daily quotas, OAuth setup or HTML parsing on your side.
It is built for SEO teams, content marketers and developers who need YouTube rank tracking, video competitor research, transcript extraction and comment analysis. The API is part of the Semust SEO platform.
Create an API user on the Semust API access page. You get a username and a password. Every request sends them as two headers:
| Header | Value |
|---|---|
SEMUST-API-USER |
Your API username |
SEMUST-API-PASSWORD |
Your API password |
The examples in this repository read them from environment variables, so they never end up in your code:
export SEMUST_API_USER="your_username"
export SEMUST_API_PASSWORD="your_password"Tip
There is no subscription. You top up a prepaid balance and pay only for successful requests; failed requests are refunded automatically. Prices are on the YouTube API page.
import os, time, requests
HEADERS = {
"SEMUST-API-USER": os.environ["SEMUST_API_USER"],
"SEMUST-API-PASSWORD": os.environ["SEMUST_API_PASSWORD"],
}
resp = requests.post(
"https://data.semust.com/v1/youtube",
params={"wait": 60},
headers=HEADERS,
json={"type": "search", "keyword": "technical seo", "country": "US", "language": "en", "limit": 20},
timeout=90,
)
while resp.status_code == 202: # still running: poll the task
time.sleep(int(resp.headers.get("Retry-After", 5)))
resp = requests.get(resp.json()["poll_url"], headers=HEADERS, timeout=30)
for row in resp.json()["items"]:
print(row["position"], row["type"], row["title"], row["views"])| Language | File | Run |
|---|---|---|
| Python | examples/python/youtube.py |
python youtube.py "technical seo" |
| Python, transcript downloader | examples/python/transcript.py |
python transcript.py "https://www.youtube.com/watch?v=_bewU9AvKwU" |
| Node.js 18+ | examples/node/youtube.mjs |
node youtube.mjs "technical seo" |
| Go | examples/go/main.go |
go run . "technical seo" |
| PHP | examples/php/youtube.php |
php youtube.php "technical seo" |
| cURL | examples/curl/youtube.sh |
./youtube.sh |
POST https://data.semust.com/v1/youtube with a JSON body. One endpoint serves four reports, chosen with type:
type |
Returns | Needs |
|---|---|---|
search (default) |
YouTube results for a keyword, in ranking order: videos, Shorts, playlists, channels and ads | keyword |
video |
One video's details: views, likes, comment count, channel and subscribers, exact publish date, duration, category, tags, and which transcripts it has | video_id |
transcript |
One video's transcript as plain text plus timed segments, optionally translated | video_id |
comments |
A video's top-level comments with author, likes and reply counts | video_id |
| Parameter | Type | Default | Used by | Description |
|---|---|---|---|---|
type |
string | search |
all | search, video, transcript or comments. |
keyword |
string | – | search (required) |
The search query, up to 200 characters. |
video_id |
string | – | video, transcript, comments (required) |
The 11-character video ID or any YouTube video URL (watch?v=, youtu.be/, shorts/, embed/, live/). |
country |
string | TR |
all | Two-letter country code: where the search runs from and the region a video is read in. Send it explicitly; the default is Türkiye. |
language |
string | tr for TR, else en |
search |
Interface language of the search, such as en, de, pt-BR. |
device |
string | desktop |
search |
desktop or mobile. |
limit |
integer | 20 |
search, comments |
Results to return, 1–200. Billed per started block of 20, so 20, 40 and 60 are the economical sizes. |
transcript_language |
string | tr for TR, else en |
transcript |
Which transcript to read, such as en or en-GB. type: "video" lists the transcripts a video has. |
translate_to |
string | – | transcript |
Translate the transcript into this language, such as de. |
idempotency_key |
string | – | all | Optional, up to 128 characters. Same as the Idempotency-Key header; if you send both, this field wins. |
A parameter the chosen type does not take is rejected with PARAMETER_NOT_ALLOWED instead of being ignored, and a misspelled one is named in the error with a suggestion. GET https://data.semust.com/v1/youtube/markets lists every supported country and search language, free of charge.
| Query parameter | Default | Description |
|---|---|---|
wait |
60 |
Seconds to hold the connection before answering 202, 0–80. 0 answers 202 at once (fire and collect). |
| Header | Description |
|---|---|
Idempotency-Key |
Optional, up to 128 characters. Repeating a request with the same key returns the same task and is charged once. |
Accept-Language |
Optional. tr returns error messages in Turkish. |
A shortened response for {"type": "search", "keyword": "technical seo", "country": "US", "language": "en", "limit": 20}. Lists are cut to two items; the complete response is in output-youtube-scraper.json. The per-call request_id is removed from the sample file.
{
"success": true,
"type": "search",
"keyword": "technical seo",
"country": "US",
"language": "en",
"device": "desktop",
"total": 4603789,
"count": 20,
"limit": 20,
"items": [
{
"position": 1,
"type": "video",
"title": "What is Technical SEO and Why is it Important? - 4.1. SEO Course by Ahrefs",
"url": "https://www.youtube.com/watch?v=_bewU9AvKwU",
"video_id": "_bewU9AvKwU"
},
{
"position": 2,
"type": "video",
"title": "9 Must-Know Technical SEO Practices for 2026",
"url": "https://www.youtube.com/watch?v=o7miIuomJoE",
"video_id": "o7miIuomJoE"
}
],
"cost": 0.0022,
"cached": false
}Every documented key is on every row. A value that does not exist or does not apply is null, never 0: a playlist has "views": null and a video has "video_count": null.
Envelope (every type)
| Field | Type | Description |
|---|---|---|
success |
boolean | true for a successful request. |
type |
string | The report that ran. |
keyword |
string | search only. The query as run. |
video_id |
string | video, transcript, comments. The 11-character ID, also when you sent a URL. |
country |
string | The country the request ran in. |
language, device |
string | search only. Interface language and device. |
total |
integer | search: the result count YouTube reports. comments: the video's comment count. |
count |
integer | search, comments. Rows in items. |
limit |
integer | search, comments. The limit that was requested. |
items |
array | search and comments rows. |
data |
object | video and transcript result. |
cost |
number | What this request cost, in USD. |
cached |
boolean | true when the answer came from cache. |
request_id |
string | Identifier of this request; quote it when you contact support. |
search row
| Field | Type | Description |
|---|---|---|
position |
integer | Rank on the results page, starting at 1. |
type |
string | video, short, playlist, channel or ad. |
title, url |
string | Title and canonical YouTube link. |
video_id |
string | null | For videos, Shorts and ads. |
channel_name, channel_url |
string | null | The channel that published it. |
views |
integer | null | View count, for videos. |
video_count |
integer | null | Number of videos, for playlists and channels. |
published_at |
string | null | Publish time, ISO 8601 in UTC. Approximate here, because YouTube shows relative dates in search ("5 years ago"); type: "video" gives the exact date. |
duration_seconds |
integer | null | Length in seconds, for videos. |
is_live |
boolean | null | true for a live stream. |
video → data
| Field | Type | Description |
|---|---|---|
video_id, title, url |
string | The video. |
description |
string | null | Full description. |
channel_name, channel_url |
string | null | The channel. |
channel_subscribers |
integer | null | The channel's subscriber count. |
views, likes, comments |
integer | null | Engagement counts. |
published_at |
string | null | Exact publish time, ISO 8601 in UTC. |
duration_seconds |
integer | null | Length in seconds. |
category |
string | null | YouTube category. |
tags |
array | The uploader's tags. |
is_live |
boolean | true for a live stream. |
transcripts |
array | Transcripts the video has, each {language, auto_generated}. Pass a language as transcript_language. |
transcript → data
| Field | Type | Description |
|---|---|---|
video_id |
string | The video. |
title |
string | null | Video title. |
language |
string | null | Language of the transcript that was read. |
translated_to |
string | null | Target language when translate_to was sent. |
text |
string | The whole transcript as one string. |
segments |
array | Timed lines, each {start, end, text}, times in seconds. |
comments row
| Field | Type | Description |
|---|---|---|
author, author_url |
string | Comment author and their channel link (author_url can be null). |
text |
string | Comment text. |
likes, replies |
integer | Like and reply counts. |
published_at |
string | null | When it was posted, ISO 8601 in UTC. |
Most requests finish in a few seconds and return 200 with the result. If a request is still running after wait seconds (60 by default, maximum 80), the API returns 202 Accepted with a task_id instead. Nothing is lost and you are not charged twice:
- Read
task_idfrom the body (also in theX-Task-Idheader). - Wait
Retry-Afterseconds. - Call
GET https://data.semust.com/v1/tasks/{task_id}with the same headers until the status is no longer202. The final answer is exactly what the original request would have returned.
Every example in examples/ already handles this. Results stay available for 72 hours, and fetching them again is free. Set your HTTP client's read timeout above wait (for example wait + 30 seconds). Send an Idempotency-Key header to retry a request safely without paying twice. Details: Tasks & long-running requests.
Errors return JSON with a readable error, a stable code and retryable; where it helps also field, hint and allowed. Errors are never charged.
| HTTP | code |
Meaning |
|---|---|---|
| 400 | INVALID_JSON, UNKNOWN_PARAMETER, INVALID_TYPE, PARAMETER_NOT_ALLOWED, INVALID_PARAMETER |
The body is not a JSON object, a parameter is misspelled or not taken by this type, or a value is out of range. field names it. |
| 400 | KEYWORD_REQUIRED, VIDEO_ID_REQUIRED, INVALID_VIDEO_ID |
search without a keyword, a video report without video_id, or a value that is not a video ID or URL. |
| 400 | UNSUPPORTED_MARKET |
Unknown country or language. GET /v1/youtube/markets lists them. |
| 401 | MISSING_CREDENTIALS, INVALID_CREDENTIALS, CREDENTIALS_EXPIRED |
Check the two auth headers. |
| 402 | INSUFFICIENT_CREDITS |
Your balance does not cover the request. Top up or lower limit. |
| 403 | IP_NOT_WHITELISTED, SERVICE_NOT_ENABLED |
Your API user only accepts listed IP addresses, or YouTube is not enabled for it. |
| 404 | VIDEO_NOT_FOUND, TRANSCRIPT_NOT_FOUND |
The video does not exist or is private, removed or blocked in that country; or it has no transcript in that language. |
| 429 | RATE_LIMIT_EXCEEDED, TOO_MANY_CONCURRENT_REQUESTS |
Slow down. At most 10 YouTube requests per API user run at the same time; wait Retry-After seconds. |
| 503 | REQUEST_FAILED, SERVICE_BUSY, SERVICE_UNAVAILABLE, TIMEOUT |
Temporary failure. If retryable is true, retry with the same Idempotency-Key. |
| Report | Price |
|---|---|
search, comments |
$0.0022 per started block of 20 results |
video |
$0.0066 per video |
transcript |
$0.0066 per video |
The cost of limit is reserved when a request starts and anything unused is refunded when it finishes, so a search with limit: 40 that returns 18 results costs one block. A search or comment list with no results is a valid answer, billed at one block. Answers are cached (search, video details and comments for 24 hours, transcripts for 30 days); a cached answer is marked "cached": true and costs the same as a live one. Failed requests are refunded automatically. Current prices are on the YouTube API page.
- YouTube rank tracking. Check where your videos rank for each keyword, by country and on desktop or mobile, and watch competitors move.
- Video competitor research. Pull the titles, tags, durations, views and channel sizes of the videos that rank, and see what a winning video looks like for a topic.
- Transcripts for content and AI. Turn videos into blog posts, summaries, subtitles or retrieval data for an LLM, in the original language or translated. Start from
transcript.py. - Comment mining. Collect audience questions, objections and feature requests from comments to plan FAQs, scripts and product pages.
- Creator and channel discovery. Find the channels that rank for your niche keywords, with subscriber counts, for partnerships or influencer outreach.
- Pay as you go. No monthly plan or minimum commitment for the API. Top up once, pay per successful request, and get failed requests refunded automatically.
- One account, every SEO dataset. SERP, keyword data, backlinks, domain research, YouTube, Google Trends, Lighthouse and Google Business data use the same credentials, the same error format and the same task system.
- Any country, any language. Localised results for every Google market, including strong coverage of Türkiye and Turkish-language queries.
- Built for AI workflows. Plug the same data into Claude, Cursor or ChatGPT with the open-source Semust MCP server.
The API reads public data: search results, public video pages, captions and comments. Collecting public data is generally lawful in many jurisdictions, but laws differ by country and how you store and reuse the data matters, especially transcripts, which belong to their creators. Check the rules that apply to you, or ask a lawyer. This is not legal advice.
No. You only need your Semust API credentials. There is no daily quota; you pay per request, and requests are limited by the rate limits on your API user.
Any public video that has a transcript, not only your own. Send type: "video" first to see which transcript languages a video has, then pass one as transcript_language. Add translate_to to get it in another language.
Yes. video_id accepts the 11-character ID or any common URL form: watch?v=, youtu.be/, shorts/, embed/ and live/, on www., m. and music. hosts.
Up to 200 search results or comments with limit. Billing is per started block of 20, so ask for the depth you will actually use.
Yes, through a tool your agent can call: the Python example is a ready-made starting point. The Semust MCP server also connects AI assistants to your Semust account data; see Semust MCP for what it covers.
- YouTube API documentation · Turkish documentation
- YouTube SEO guide (Turkish)
- What is a web scraping API? (Turkish)
- Best SERP API alternatives
- Free SEO tools
SEO data APIs
| Repository | What it does | Product page |
|---|---|---|
| google-serp-scraper | Organic results, People Also Ask, AI Overviews, ads and more as JSON | Google SERP API |
| google-images-scraper | Google Images results with titles, source pages and image URLs | Google Images API |
| google-trends-scraper | Interest over time, regions, related queries and demographics | Google Trends API |
| google-business-scraper | Google Business profiles, local search and reviews | Google Business Data API |
| keyword-research-api | Search volume, CPC, competition, intent and related keywords | Keyword Research API |
| backlinks-api | Backlinks, referring domains, anchors and link history | Backlinks API |
| domain-research-api | Organic keywords, competitors, top pages and keyword gaps for any domain | Domain Research API |
| technical-seo-api | 27 technical SEO checks for any URL in one call | Technical SEO API |
| lighthouse-on-page-api | Lighthouse scores, on-page audits and page content extraction | Lighthouse & On-Page API |
MCP servers for AI assistants
| Repository | What it does | Product page |
|---|---|---|
| semust-mcp | One MCP server for Search Console, GA4, Google Ads, rank tracking and social posting | Semust MCP Server |
| seo-mcp | Search Console, rank tracking, indexing and competitor tools for AI assistants | SEO MCP |
| google-search-console-mcp | Ask your AI assistant about clicks, queries and pages | Google Search Console MCP |
| google-analytics-mcp | GA4 traffic, channels and conversions in your AI assistant | Google Analytics MCP |
| google-ads-mcp | Campaigns, search terms and spend in your AI assistant | Google Ads MCP |
| rank-tracker-mcp | Keyword rankings and AI-search visibility for AI assistants | Rank Tracker MCP |
| web-analytics-mcp | Privacy-friendly first-party analytics in your AI assistant | Web Analytics MCP |
| bing-webmaster-mcp | Bing queries, pages, links and crawl issues | Bing Webmaster MCP |
| yandex-metrica-mcp | Yandex Metrica traffic and search phrases | Yandex Metrica MCP |
| social-media-mcp | Draft and schedule LinkedIn, Facebook and Instagram posts | Social Media MCP |
- Email: destek@semust.com
- Contact form
- LinkedIn · YouTube · Instagram
Found a problem with an example? Open an issue.
The code examples in this repository are released under the MIT License. Use of the Semust API is subject to the Semust Terms of Service.

