{ "openapi": "3.0.1", "info": { "title": "YouTube Search Scraper - Keyword Rankings", "description": "Give it keywords, get YouTube's ranked results: position, title, channel, views and publish date for every result. Built for rank tracking and competitor research. No transcripts or comment text: the Video Scraper does those.", "version": "0.1", "x-build-id": "qPXSf24ResCVMBX55" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/tubelens~youtube-search-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-tubelens-youtube-search-scraper", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } }, "/acts/tubelens~youtube-search-scraper/runs": { "post": { "operationId": "runs-sync-tubelens-youtube-search-scraper", "x-openai-isConsequential": false, "summary": "Executes an Actor and returns information about the initiated run in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/runsResponseSchema" } } } } } } }, "/acts/tubelens~youtube-search-scraper/run-sync": { "post": { "operationId": "run-sync-tubelens-youtube-search-scraper", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } } }, "components": { "schemas": { "inputSchema": { "type": "object", "required": [ "keywords" ], "properties": { "keywords": { "title": "Keywords", "minItems": 1, "type": "array", "description": "Search terms to run on YouTube. Each result row carries the keyword that produced it. Paste one per line.", "items": { "type": "string" } }, "maxResultsPerKeyword": { "title": "Max results per keyword", "minimum": 1, "maximum": 1000, "type": "integer", "description": "How many rows to return per keyword. This caps the rows returned, not how many results the actor scans.", "default": 50 }, "resultType": { "title": "Result type", "enum": [ "video", "channel", "playlist", "movie", "shorts" ], "type": "string", "description": "Which kind of result to search for.", "default": "video" }, "sortBy": { "title": "Sort by", "enum": [ "relevance", "popularity" ], "type": "string", "description": "How YouTube orders the results. Only Relevance and Popularity are real, working sorts on YouTube's own search page, so those are the only two offered here.", "default": "relevance" }, "uploadedWithin": { "title": "Uploaded within", "enum": [ "any", "today", "week", "month", "year" ], "type": "string", "description": "Only return results uploaded within this time window.", "default": "any" }, "duration": { "title": "Duration", "enum": [ "any", "short", "medium", "long" ], "type": "string", "description": "Only return results in this length range: short is under 3 minutes, medium is 3 to 20 minutes, long is over 20 minutes.", "default": "any" }, "features": { "title": "Feature filters", "type": "array", "description": "Only return videos with these properties. Leave empty for no restriction.", "items": { "type": "string", "enum": [ "subtitles", "4k", "360", "vr180", "live" ], "enumTitles": [ "Subtitles or closed captions", "4K", "360 degree", "VR180", "Live now" ] }, "default": [] }, "language": { "title": "Language", "pattern": "^[a-z]{2}$", "type": "string", "description": "Language YouTube uses to rank results, as a two-letter code such as en or hi. This genuinely changes which results come back, not just how they are labelled. Publish dates are read in ar, de, en, es, fr, hi, id, it, ja, ko, nl, pt, ru and tr; any other language still returns every other field, keeps YouTube's own date wording in publishedText, and warns in the run log that publishedAt will be empty.", "default": "en" }, "includeShelves": { "title": "Include shelf results", "type": "boolean", "description": "YouTube mixes extra shapes into the results page: shelves, grids, a channel card between two videos, catalogue films. Off by default so you only get the organic, ranked search results, and anything without a rank is neither returned nor billed. Turn it on and all of it comes back with position null and is billed, and a video that appears both in the ranked list and inside a shelf comes back as two rows, one ranked and one marked shelfItem.", "default": false }, "proxyConfiguration": { "title": "Proxy", "type": "object", "description": "Datacenter proxy is used by default and is enough for YouTube. Residential is used automatically if a datacenter address gets blocked.", "default": { "useApifyProxy": true } } } }, "runsResponseSchema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "actId": { "type": "string" }, "userId": { "type": "string" }, "startedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "finishedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "status": { "type": "string", "example": "READY" }, "meta": { "type": "object", "properties": { "origin": { "type": "string", "example": "API" }, "userAgent": { "type": "string" } } }, "stats": { "type": "object", "properties": { "inputBodyLen": { "type": "integer", "example": 2000 }, "rebootCount": { "type": "integer", "example": 0 }, "restartCount": { "type": "integer", "example": 0 }, "resurrectCount": { "type": "integer", "example": 0 }, "computeUnits": { "type": "integer", "example": 0 } } }, "options": { "type": "object", "properties": { "build": { "type": "string", "example": "latest" }, "timeoutSecs": { "type": "integer", "example": 300 }, "memoryMbytes": { "type": "integer", "example": 1024 }, "diskMbytes": { "type": "integer", "example": 2048 } } }, "buildId": { "type": "string" }, "defaultKeyValueStoreId": { "type": "string" }, "defaultDatasetId": { "type": "string" }, "defaultRequestQueueId": { "type": "string" }, "buildNumber": { "type": "string", "example": "1.0.0" }, "containerUrl": { "type": "string" }, "usage": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "integer", "example": 1 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } }, "usageTotalUsd": { "type": "number", "example": 0.00005 }, "usageUsd": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "number", "example": 0.00005 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } } } } } } } } }