API reference

YouTube Hashtag Search API

Best-effort hashtag search — a search.list keyword query for the "#tag" token (Data API has no dedicated hashtag endpoint; noted in _warnings).

Read as Markdown Use with an AI agent

Endpoint

GET/v1/youtube/search/hashtaglive · proven1 credit

Try in Playground

Parameters

Query parameters

Useful optional inputs

fit — Use fit=goal with a task description to replace confidently irrelevant records with recall stubs and reduce agent context.
No fit surcharge; full evidence is retained for 24 hours when stored, and the response size target is soft.
cursor — Continue the same source traversal with the complete returned cursor.
Saved-result retrieval and a new source page can have different prices; quote the next call.
dry_run — Read a free estimate before fetching sources or scheduling paid work.
Zero credits; cache status and availability are snapshots rather than guarantees.

Name	Required	Description	Example
`hashtag`	yes	Hashtag with or without the leading #	`shorts`
`type`	no	Result kind (defaults to video) Accepted values (comma-separated): video, channel, playlist. Case, spaces, hyphens and underscores are interchangeable.	`video`
`max_results`	no	Requested page size, 1–50. The paid primary defaults to 50; the source may return fewer. Keep an explicit size unchanged while paginating.	`50`
`cursor`	no	Opaque page token from a previous response	`CAUQAA`
`dry_run`	no	Read a zero-credit estimate without fetching sources, running AI, or reserving credits. Cache status is a snapshot, not a guarantee at execution. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable.	`1`
`judgments`	no	Add bounded AI labels to eligible returned records (default on). off preserves the original data shape. Unclassified records remain present; labels depend on evidence, time, capacity and the existing request budget. No label surcharge. Accepted values: on, off. Case, spaces, hyphens and underscores are interchangeable.	`on`
`label`	no	Set none to disable labels; default enables the endpoint’s label set. Equivalent to judgments=off. Accepted values: default, none. Case, spaces, hyphens and underscores are interchangeable.	`none`
`label_evidence`	no	Include exact supporting sentences and zero-based sentence indexes when a label has validated evidence. No extra charge or change to decisions. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable.	`1`
`exclude`	no	Optionally remove confidently labelled engagement bait. Uncertain and unclassified records stay; removed IDs and an owner-bound recall reference are returned. Accepted values: engagement_bait. Case, spaces, hyphens and underscores are interchangeable.	`engagement_bait`
`fit`	no	Use goal to replace confidently irrelevant records with recall stubs. Keeps first, last, relevant and uncertain records; preserves order. Full evidence is stored for 24 hours when available. Accepted values: goal. Case, spaces, hyphens and underscores are interchangeable.	`goal`
`goal`	no	Required with fit=goal: describe the task in at most 600 characters. Supplied text is task context, never permission to act on posts.	`Find concrete product complaints`
`tokens`	no	Optional soft response target for fit=goal, 256–32000. Safety and evidence retention take priority, so the returned result may exceed it.	`4000`

Examples

Make the request

curl

curl "https://www.monocrawl.com/v1/youtube/search/hashtag?hashtag=shorts" \
  -H "x-api-key: mn_your_key_here"

TypeScript

typescript

const key = process.env.MONOCRAWL_API_KEY;
if (!key) throw new Error('Set MONOCRAWL_API_KEY on your server.');
const res = await fetch(
  "https://www.monocrawl.com/v1/youtube/search/hashtag?hashtag=shorts",
  { headers: { "x-api-key": key } },
);
const body = await res.json();

if (!body.success) {
  // one error shape for every endpoint — see /docs/errors
  throw new Error(`${body.error.type}: ${body.error.message}`);
}

console.log(body.data, "credits left:", body.credits_remaining);

Python

python

import os
import requests

res = requests.get(
    "https://www.monocrawl.com/v1/youtube/search/hashtag?hashtag=shorts",
    headers={"x-api-key": os.environ["MONOCRAWL_API_KEY"]},
    timeout=60,
)
body = res.json()

if not body["success"]:
    # one error shape for every endpoint — see /docs/errors
    raise RuntimeError(f"{body['error']['type']}: {body['error']['message']}")

print(body["data"], "credits left:", body["credits_remaining"])

Response

Response fields and example

This example is illustrative, not a captured live response. Variable-cost operations may settle a charge different from the list price below. A successful response puts the platform payload in data and reports the exact credits used, remaining balance, request id and cache status beside it.

200 · application/json

{
  "success": true,
  "platform": "youtube",
  "endpoint": "/v1/youtube/search/hashtag",
  "data": {
    "items": [
      {
        "kind": "video",
        "id": "abcdefghijk",
        "url": "https://www.youtube.com/watch?v=abcdefghijk",
        "title": "A quieter desk setup",
        "channel": {
          "id": "UC_example",
          "name": "Example Channel"
        }
      }
    ],
    "cursor": null,
    "has_more": null
  },
  "credits_used": 1,
  "credits_remaining": 99,
  "request_id": "req_…",
  "cached": false
}

The example is illustrative and shows a documented subset of data. The fields below are optional across supported sources; nullable fields can also be absent. Preserve unknown values and accept additional fields.

Schema basis: reviewed response shaper. See schema coverage and validation limits.

Download the data JSON Schema. Validate response.data, not the whole envelope. A valid shape does not establish that every field or source record was returned.

Field inside data	Type	Meaning
`items`	`array`	Records in this response page.
`items[].kind`	`string \| null`	Result kind: video, channel or playlist.
`items[].id`	`string \| null`	Source identifier. Preserve its exact string value; do not convert large IDs to numbers.
`items[].url`	`string \| null`	Original source URL when supplied.
`items[].title`	`string \| null`	Search-result title.
`items[].description`	`string \| null`	Search snippet, not the full video description.
`items[].published_at`	`string \| null`	Source publication time, normalized to an ISO date-time when available.
`items[].channel`	`object`	Nested response fields; optional unless explicitly documented.
`items[].channel.id`	`string \| null`	Source identifier. Preserve its exact string value; do not convert large IDs to numbers.
`items[].channel.name`	`string \| null`	Channel display name.
`count`	`number \| null`	Returned row count when supplied; not the full source total.
`cursor`	`string \| null`	Opaque next-page token. A missing token does not prove full history was retrieved.
`has_more`	`boolean \| null`	Source continuation indicator; null means unknown.
`_warnings`	`array`	Collection limitations or component warnings. Read before interpreting coverage.

Search rows describe discovery results. Use the appropriate detail endpoint for statistics and full record fields.

Failures use the typed error envelope. A confirmed uncharged or refunded failure reports zero; a pending reconciliation can report an unknown charge. Read credits_used and error.details.billing_status, and keep request_id for recovery. Response contract · Error reference

YouTube Hashtag Search API

Query parameters

Make the request

Response fields and example

Useful next calls

First call in under a minute