SocQ Social and SEO Research

SocQ Social and SEO Research

SocQ Links

• Website:
• Platform catalog:
• API documentation:
• API key:
• MCP and CLI:
• Agent Skill guide:

Use this Skill to select and run SocQ endpoints for public social-platform and SEO research. SocQ requests are asynchronous and credit-metered.

Use When

• The user asks to discover, collect, compare, monitor, or analyze public social or SEO data.
• The workflow spans platforms or needs endpoint discovery through the Capability Registry.
• An agent must estimate credits, submit tasks, poll results, paginate normalized records, or retrieve raw exports.

Endpoint Selection

• Search the live Capability Registry first. Read catalog.md when tool discovery is unavailable.
• Read the matching generated platform reference before selecting endpoints or constructing input: Facebook, Facebook Ad Library, Facebook Marketplace, Google Ad Library, Instagram, LinkedIn, LinkedIn Ad Library, Pinterest, Reddit, Threads, TikTok, TikTok Ad Library, TikTok Shop, X, YouTube, or SEO.
• Choose endpoints from the requested resource shape rather than routing every request through broad search.
• Prefer direct URLs, canonical usernames, or platform IDs when supplied.
• For multi-network research, follow cross-platform.md and use comparable date windows, limits, locales, and content types.

Key Inputs

• Preserve the requested platforms, entities, query terms, date range, locale, filters, ordering, and result cap.
• Ask only for missing input required by the selected endpoint.
• Use view: "standard" for MCP and Skill result reads. Use _result_view: "standard" for typed MCP tools or --result-view standard for CLI output.
• Add a reusable idempotency key when a submission might be retried.
• Treat next_cursor as opaque and stop only at the requested scope or user-approved cap.

Execution

1. Prefer an already configured hosted SocQ MCP server at https://api.socq.ai/mcp.
2. Filter MCP with ?platforms=youtube,tiktok for up to five platforms or ?tools=youtube_comments,x_search for up to thirty endpoint tools when scope is known.
3. Use npx @socq/mcp for local stdio-only clients. If MCP is unavailable, use socq or npx @socq/cli; use REST only as the final fallback.
4. Read authentication.md, keep SOCQ_API_KEY in the environment, and never put it in prompts, URLs, committed files, or retained commands.
5. Read billing.md, report expected cost, and obtain confirmation before a paid large-volume, cross-platform, or multi-endpoint run.
6. Submit with _request_source: "skill", --request-source skill, or X-Socq-Source: skill-rest for MCP, CLI, or REST.
7. Save every task ID. Treat queued and running as incomplete and follow async-tasks.md until succeeded or failed.
8. Follow pagination.md for requested pages and retrieve task files when complete raw JSONL output is required.
9. Read errors.md before retrying authentication, credit, rate-limit, validation, or provider failures.

Output Expectations

Include:

• selected endpoints, platforms, and execution path
• concise input, filter, window, and comparability summary
• expected and reported credit usage when available
• task IDs and terminal statuses
• result counts, pages read, and whether more data remains
• normalized findings or raw export locations
• collection time, failed platforms, unsupported filters, and incomplete coverage

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 start a paid large-volume, cross-platform, or multi-endpoint run without user confirmation.
• Do not invent unsupported parameters; re-read the live endpoint schema after validation errors.
• Do not claim completeness when pagination stopped early, a provider failed, or the requested date filter is unsupported.
• Do not compare metrics collected with different windows, filters, locales, or content types without labeling the difference.
• Keep task IDs in working notes so interrupted research can resume without resubmitting.