{
  "openapi": "3.0.1",
  "info": {
    "title": "YouTube Keyword Research - Autocomplete & Competition Score",
    "description": "Expands seed topics into YouTube autocomplete keywords and scores each for demand, competition and opportunity via the official YouTube Data API v3: median views of top results, ranking channel size, small-channel share and upload age.",
    "version": "1.0",
    "x-build-id": "4xmz1FNl37vqGaQWw"
  },
  "servers": [
    {
      "url": "https://api.apify.com/v2"
    }
  ],
  "paths": {
    "/acts/mibedk~youtube-keyword-opportunity-scorer/run-sync-get-dataset-items": {
      "post": {
        "operationId": "run-sync-get-dataset-items-mibedk-youtube-keyword-opportunity-scorer",
        "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/mibedk~youtube-keyword-opportunity-scorer/runs": {
      "post": {
        "operationId": "runs-sync-mibedk-youtube-keyword-opportunity-scorer",
        "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/mibedk~youtube-keyword-opportunity-scorer/run-sync": {
      "post": {
        "operationId": "run-sync-mibedk-youtube-keyword-opportunity-scorer",
        "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",
        "properties": {
          "seeds": {
            "title": "Seed topics",
            "minItems": 1,
            "maxItems": 25,
            "type": "array",
            "description": "One or more seed topics to expand into YouTube autocomplete keywords. Each seed is expanded into many autocomplete queries according to 'Expansion level'. Plain words work best — type what a viewer would type into the YouTube search box.",
            "default": [
              "ai tools",
              "home gym"
            ],
            "items": {
              "type": "string"
            }
          },
          "apiKey": {
            "title": "YouTube Data API v3 key (optional — required for scoring)",
            "type": "string",
            "description": "Your own YouTube Data API v3 key. LEAVE EMPTY to get the deduplicated autocomplete keyword list only (no API key, no signup, works immediately). Provide a key to also get the competition profile and opportunity score for each keyword. Free key: console.cloud.google.com/apis/credentials -> Create credentials -> API key, then enable 'YouTube Data API v3' in the API Library for that project. Scoring one keyword costs ~102 units of your 10,000/day free quota, so keep 'Max scored keywords' at or below 90."
          },
          "expansionLevel": {
            "title": "Expansion level",
            "enum": [
              "basic",
              "standard",
              "deep"
            ],
            "type": "string",
            "description": "How hard to expand each seed against YouTube autocomplete. 'basic' = the seed alone (1 query per seed). 'standard' = the seed plus 10 suffix modifiers (how, what, why, best, vs, for, without, tutorial, review, free) and 3 prefix modifiers (14 queries per seed). 'deep' = standard plus alphabet soup, seed + a..z (40 queries per seed).",
            "default": "standard"
          },
          "regionCode": {
            "title": "Country code",
            "type": "string",
            "description": "Two-letter ISO 3166-1 country code. Controls which country's autocomplete suggestions are returned (the 'gl' parameter) and which country's search results are used for scoring (YouTube Data API 'regionCode'). Autocomplete differs a lot by country.",
            "default": "US"
          },
          "language": {
            "title": "Language code",
            "type": "string",
            "description": "Two-letter ISO 639-1 language code. Controls the language of autocomplete suggestions (the 'hl' parameter) and biases scoring search results toward that language ('relevanceLanguage').",
            "default": "en"
          },
          "maxScoredKeywords": {
            "title": "Max scored keywords",
            "minimum": 1,
            "maximum": 500,
            "type": "integer",
            "description": "How many keywords get the full competition profile and opportunity score. Only used when an API key is supplied. Each scored keyword costs about 102 units of your daily YouTube API quota (10,000/day by default), so 90 is the practical ceiling for one day on a fresh key. Keywords are scored in order of autocomplete prominence, spread evenly across your seeds.",
            "default": 20
          },
          "maxKeywords": {
            "title": "Max keywords in output",
            "minimum": 1,
            "maximum": 5000,
            "type": "integer",
            "description": "Hard cap on the total number of keyword records saved to the dataset, scored and unscored combined. Scored keywords are always saved first.",
            "default": 200
          },
          "includeUnscoredKeywords": {
            "title": "Include unscored keywords",
            "type": "boolean",
            "description": "Save the remaining autocomplete keywords that were discovered but not scored (because they fell outside 'Max scored keywords', or because no API key was given). Turn this off to get only fully scored keywords.",
            "default": true
          },
          "topResultsPerKeyword": {
            "title": "Top results analysed per keyword",
            "minimum": 5,
            "maximum": 50,
            "type": "integer",
            "description": "How many of the top YouTube search results are profiled per scored keyword. All competition metrics (median views, median subscribers, small-channel share, median upload age) are computed over this set. Higher is more stable but does not cost extra API quota.",
            "default": 25
          },
          "smallChannelMaxSubscribers": {
            "title": "\"Small channel\" subscriber ceiling",
            "minimum": 100,
            "maximum": 100000000,
            "type": "integer",
            "description": "A ranking channel with fewer subscribers than this counts as a 'small channel'. The share of top results held by small channels is the strongest single signal that a keyword is winnable, and it feeds the competition score.",
            "default": 100000
          },
          "proxyConfiguration": {
            "title": "Proxy configuration",
            "type": "object",
            "description": "Optional. Off by default so the actor is cheap to try. Turn on Apify Proxy (datacenter is enough) if YouTube's autocomplete endpoint starts rate-limiting your runs, or to pull suggestions as if from another country.",
            "default": {
              "useApifyProxy": false
            }
          }
        }
      },
      "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
                  },
                  "PROXY_UNBLOCKER_UNITS": {
                    "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
                  },
                  "PROXY_UNBLOCKER_UNITS": {
                    "type": "integer",
                    "example": 0
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}