SocQ YouTube Research

Research public YouTube data

Use SocQ to collect public YouTube data through an asynchronous, credit-metered workflow.

Choose the integration

1. In OpenClaw, prefer the socq CLI when installed; otherwise use npx @socq/cli.
2. Use the hosted MCP server at https://api.socq.ai/mcp?platforms=youtube when SocQ MCP is already configured.
3. Use REST only when neither CLI nor MCP is available.
4. Attribute executions with --request-source skill, _request_source: "skill", or X-Socq-Source: skill-rest for CLI, MCP, or REST respectively.

Never place an API key in a prompt, query string, committed file, or retained shell command. Read authentication.md before configuring credentials.

SocQ is an external, credit-metered service. A SocQ account and SOCQ_API_KEY are required, and requests may consume paid credits.

Plan YouTube research

Select an endpoint based on the YouTube content object the user needs:

• Use youtube/search or youtube/hashtag-search for discovery, then resolve selected results with youtube/videos or youtube/channels when detailed metadata is required.
• Use youtube/channel-videos, youtube/channel-live-videos, and youtube/shorts for format-specific channel inventories. Keep regular uploads, live streams, and Shorts separate in comparisons.
• Use youtube/playlist-videos only when playlist membership or ordering matters; do not treat a playlist as the channel's complete catalog.
• Use youtube/comments for top-level discussion and youtube/comment-replies for a selected thread. Preserve parent comment IDs so replies remain attributable.
• Use youtube/transcripts for spoken-content analysis. Report unavailable, disabled, auto-generated, or language-mismatched transcripts instead of substituting descriptions.
• Use youtube/community-posts for channel community activity and keep it distinct from video publishing activity.

Resolve channel and video URLs to canonical IDs before joining results across endpoints. For performance comparisons, align publication windows and distinguish cumulative counters from activity observed during the requested period. A video's current views or comments are not the number gained inside a historical date range. When analyzing themes from transcripts and comments, identify which evidence comes from creator speech and which comes from audience discussion. State whether the result includes videos, Shorts, live streams, playlists, community posts, or only a subset.

Execute research

1. Restate the requested YouTube entities, date range, filters, and result volume.
2. Read platform.md, select the endpoint, and validate inputs against its current schema.
3. Check account credits before a large request. Read billing.md.
4. Submit with a reusable idempotency key when a transport retry is possible.
5. Treat queued and running as incomplete. Poll until succeeded or failed; follow async-tasks.md.
6. Follow every next_cursor required for the requested scope. Read pagination.md.
7. Retrieve task files when complete raw JSONL output is needed.
8. Report filters, collection time, partial coverage, and provider failures with the results.

For authentication, rate limits, provider failures, and recovery, follow errors.md.

Guardrails

• Collect only public data supported by the selected endpoint.
• Do not retry a failed paid request blindly; inspect the normalized error first.
• Do not invent unsupported parameters; re-read the endpoint schema after validation errors.
• Do not claim completeness when pagination stops early, a provider fails, or a requested filter is unsupported.
• Keep task IDs in working notes so interrupted research can resume without resubmission.