SocialHolmes

API reference

YouTube API

Channels, videos, shorts, live streams, playlists, comments and replies.

POST

/api/public/v1/scrape/youtube/channel

Channel details — name, handle, subscriber and video counts.

Returns profile_api

Parameters

Name Required Description Example
handle required Channel handle, with or without the @. NASA

Request

curl -X POST https://socialholmes.com/api/public/v1/scrape/youtube/channel \
  -H "Authorization: Bearer $SOCIALHOLMES_KEY" \
  -H "Content-Type: application/json" \
  -d '{"parameters":{"handle":"NASA"}}'

Response 202 Accepted

{
  "id": "8f14e45f-ceea-467a-9c2e-1b0f5a4c7d21",
  "status": "queued",
  "platform": "youtube",
  "endpoint": "channel",
  "target": "NASA",
  "url": "https://www.youtube.com/@NASA",
  "result_count": 0,
  "created_at": "2026-08-26T19:08:00Z"
}

This endpoint errs towards returning more rather than less, so expect a few extra rows alongside what you asked for. Everything still comes back typed and parsed the same way.

POST

/api/public/v1/scrape/youtube/channels

Channels this channel features or subscribes to publicly.

Returns user_feed_api

Parameters

Name Required Description Example
handle required Channel handle, with or without the @. NASA

Takes limit — how many results you want. The run is sized from it, and you are billed for exactly that many.

Request

curl -X POST https://socialholmes.com/api/public/v1/scrape/youtube/channels \
  -H "Authorization: Bearer $SOCIALHOLMES_KEY" \
  -H "Content-Type: application/json" \
  -d '{"parameters":{"handle":"NASA"},"limit":25}'

Response 202 Accepted

{
  "id": "8f14e45f-ceea-467a-9c2e-1b0f5a4c7d21",
  "status": "queued",
  "platform": "youtube",
  "endpoint": "channels",
  "target": "NASA",
  "url": "https://www.youtube.com/@NASA/channels",
  "result_count": 0,
  "created_at": "2026-08-26T19:08:00Z"
}

This endpoint errs towards returning more rather than less, so expect a few extra rows alongside what you asked for. Everything still comes back typed and parsed the same way.

POST

/api/public/v1/scrape/youtube/videos

A channel's uploads, newest first. Use `limit` to say how many.

Returns post_feed_api

Parameters

Name Required Description Example
handle required Channel handle, with or without the @. NASA

Takes limit — how many results you want. The run is sized from it, and you are billed for exactly that many.

Request

curl -X POST https://socialholmes.com/api/public/v1/scrape/youtube/videos \
  -H "Authorization: Bearer $SOCIALHOLMES_KEY" \
  -H "Content-Type: application/json" \
  -d '{"parameters":{"handle":"NASA"},"limit":25}'

Response 202 Accepted

{
  "id": "8f14e45f-ceea-467a-9c2e-1b0f5a4c7d21",
  "status": "queued",
  "platform": "youtube",
  "endpoint": "videos",
  "target": "NASA",
  "url": "https://www.youtube.com/@NASA/videos",
  "result_count": 0,
  "created_at": "2026-08-26T19:08:00Z"
}

This endpoint errs towards returning more rather than less, so expect a few extra rows alongside what you asked for. Everything still comes back typed and parsed the same way.

POST

/api/public/v1/scrape/youtube/shorts

A channel's Shorts. Use `limit` to say how many you want.

Returns reel_feed_api

Parameters

Name Required Description Example
handle required Channel handle, with or without the @. NASA

Takes limit — how many results you want. The run is sized from it, and you are billed for exactly that many.

Request

curl -X POST https://socialholmes.com/api/public/v1/scrape/youtube/shorts \
  -H "Authorization: Bearer $SOCIALHOLMES_KEY" \
  -H "Content-Type: application/json" \
  -d '{"parameters":{"handle":"NASA"},"limit":25}'

Response 202 Accepted

{
  "id": "8f14e45f-ceea-467a-9c2e-1b0f5a4c7d21",
  "status": "queued",
  "platform": "youtube",
  "endpoint": "shorts",
  "target": "NASA",
  "url": "https://www.youtube.com/@NASA/shorts",
  "result_count": 0,
  "created_at": "2026-08-26T19:08:00Z"
}

This endpoint errs towards returning more rather than less, so expect a few extra rows alongside what you asked for. Everything still comes back typed and parsed the same way.

POST

/api/public/v1/scrape/youtube/live

A channel's live streams, past and present. Use `limit` for how many.

Returns post_feed_api

Parameters

Name Required Description Example
handle required Channel handle, with or without the @. NASA

Takes limit — how many results you want. The run is sized from it, and you are billed for exactly that many.

Request

curl -X POST https://socialholmes.com/api/public/v1/scrape/youtube/live \
  -H "Authorization: Bearer $SOCIALHOLMES_KEY" \
  -H "Content-Type: application/json" \
  -d '{"parameters":{"handle":"NASA"},"limit":25}'

Response 202 Accepted

{
  "id": "8f14e45f-ceea-467a-9c2e-1b0f5a4c7d21",
  "status": "queued",
  "platform": "youtube",
  "endpoint": "live",
  "target": "NASA",
  "url": "https://www.youtube.com/@NASA/streams",
  "result_count": 0,
  "created_at": "2026-08-26T19:08:00Z"
}

This endpoint errs towards returning more rather than less, so expect a few extra rows alongside what you asked for. Everything still comes back typed and parsed the same way.

POST

/api/public/v1/scrape/youtube/playlists

A channel's playlists — title, video count and owner.

Returns playlist_feed_api

Parameters

Name Required Description Example
handle required Channel handle, with or without the @. NASA

Takes limit — how many results you want. The run is sized from it, and you are billed for exactly that many.

Request

curl -X POST https://socialholmes.com/api/public/v1/scrape/youtube/playlists \
  -H "Authorization: Bearer $SOCIALHOLMES_KEY" \
  -H "Content-Type: application/json" \
  -d '{"parameters":{"handle":"NASA"},"limit":25}'

Response 202 Accepted

{
  "id": "8f14e45f-ceea-467a-9c2e-1b0f5a4c7d21",
  "status": "queued",
  "platform": "youtube",
  "endpoint": "playlists",
  "target": "NASA",
  "url": "https://www.youtube.com/@NASA/playlists",
  "result_count": 0,
  "created_at": "2026-08-26T19:08:00Z"
}

This endpoint errs towards returning more rather than less, so expect a few extra rows alongside what you asked for. Everything still comes back typed and parsed the same way.

POST

/api/public/v1/scrape/youtube/playlist

The videos inside one playlist. Use `limit` to say how many.

Returns post_feed_api

Parameters

Name Required Description Example
playlist_id required The id from /playlist?list=<id>, as returned by the `playlists` endpoint. PL2aBZuCeDwlRaF6AIey7ulmW1X0SHI1mQ

Takes limit — how many results you want. The run is sized from it, and you are billed for exactly that many.

Request

curl -X POST https://socialholmes.com/api/public/v1/scrape/youtube/playlist \
  -H "Authorization: Bearer $SOCIALHOLMES_KEY" \
  -H "Content-Type: application/json" \
  -d '{"parameters":{"playlist_id":"PL2aBZuCeDwlRaF6AIey7ulmW1X0SHI1mQ"},"limit":25}'

Response 202 Accepted

{
  "id": "8f14e45f-ceea-467a-9c2e-1b0f5a4c7d21",
  "status": "queued",
  "platform": "youtube",
  "endpoint": "playlist",
  "target": "PL2aBZuCeDwlRaF6AIey7ulmW1X0SHI1mQ",
  "url": "https://www.youtube.com/playlist?list=PL2aBZuCeDwlRaF6AIey7ulmW1X0SHI1mQ",
  "result_count": 0,
  "created_at": "2026-08-26T19:08:00Z"
}

This endpoint errs towards returning more rather than less, so expect a few extra rows alongside what you asked for. Everything still comes back typed and parsed the same way.

POST

/api/public/v1/scrape/youtube/video

One video's full record — description, counts, keywords, channel.

Returns post_detail_api

Parameters

Name Required Description Example
video_id required The id from watch?v=<id> in the video URL. dQw4w9WgXcQ

Request

curl -X POST https://socialholmes.com/api/public/v1/scrape/youtube/video \
  -H "Authorization: Bearer $SOCIALHOLMES_KEY" \
  -H "Content-Type: application/json" \
  -d '{"parameters":{"video_id":"dQw4w9WgXcQ"}}'

Response 202 Accepted

{
  "id": "8f14e45f-ceea-467a-9c2e-1b0f5a4c7d21",
  "status": "queued",
  "platform": "youtube",
  "endpoint": "video",
  "target": "dQw4w9WgXcQ",
  "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
  "result_count": 0,
  "created_at": "2026-08-26T19:08:00Z"
}

This endpoint errs towards returning more rather than less, so expect a few extra rows alongside what you asked for. Everything still comes back typed and parsed the same way.

POST

/api/public/v1/scrape/youtube/comments

Top-level comments on a video. Use `limit` to say how many.

Returns comment_api

Parameters

Name Required Description Example
video_id required The id from watch?v=<id> in the video URL. dQw4w9WgXcQ

Takes limit — how many results you want. The run is sized from it, and you are billed for exactly that many.

Request

curl -X POST https://socialholmes.com/api/public/v1/scrape/youtube/comments \
  -H "Authorization: Bearer $SOCIALHOLMES_KEY" \
  -H "Content-Type: application/json" \
  -d '{"parameters":{"video_id":"dQw4w9WgXcQ"},"limit":25}'

Response 202 Accepted

{
  "id": "8f14e45f-ceea-467a-9c2e-1b0f5a4c7d21",
  "status": "queued",
  "platform": "youtube",
  "endpoint": "comments",
  "target": "dQw4w9WgXcQ",
  "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
  "result_count": 0,
  "created_at": "2026-08-26T19:08:00Z"
}

This endpoint errs towards returning more rather than less, so expect a few extra rows alongside what you asked for. Everything still comes back typed and parsed the same way.

POST

/api/public/v1/scrape/youtube/replies

Comment replies on a video. Use `limit` to say how many you want.

Returns comment_reply_api

Parameters

Name Required Description Example
video_id required The id from watch?v=<id> in the video URL. dQw4w9WgXcQ

Takes limit — how many results you want. The run is sized from it, and you are billed for exactly that many.

Request

curl -X POST https://socialholmes.com/api/public/v1/scrape/youtube/replies \
  -H "Authorization: Bearer $SOCIALHOLMES_KEY" \
  -H "Content-Type: application/json" \
  -d '{"parameters":{"video_id":"dQw4w9WgXcQ"},"limit":25}'

Response 202 Accepted

{
  "id": "8f14e45f-ceea-467a-9c2e-1b0f5a4c7d21",
  "status": "queued",
  "platform": "youtube",
  "endpoint": "replies",
  "target": "dQw4w9WgXcQ",
  "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
  "result_count": 0,
  "created_at": "2026-08-26T19:08:00Z"
}

This endpoint errs towards returning more rather than less, so expect a few extra rows alongside what you asked for. Everything still comes back typed and parsed the same way.

POST

/api/public/v1/scrape/youtube/hashtag

Videos under a hashtag. Use `limit` to say how many you want.

Returns post_feed_api

Parameters

Name Required Description Example
tag required Tag, with or without the spacex

Takes limit — how many results you want. The run is sized from it, and you are billed for exactly that many.

Request

curl -X POST https://socialholmes.com/api/public/v1/scrape/youtube/hashtag \
  -H "Authorization: Bearer $SOCIALHOLMES_KEY" \
  -H "Content-Type: application/json" \
  -d '{"parameters":{"tag":"spacex"},"limit":25}'

Response 202 Accepted

{
  "id": "8f14e45f-ceea-467a-9c2e-1b0f5a4c7d21",
  "status": "queued",
  "platform": "youtube",
  "endpoint": "hashtag",
  "target": "spacex",
  "url": "https://www.youtube.com/hashtag/spacex",
  "result_count": 0,
  "created_at": "2026-08-26T19:08:00Z"
}

This endpoint errs towards returning more rather than less, so expect a few extra rows alongside what you asked for. Everything still comes back typed and parsed the same way.