From citedy-seo-agent
Find what your audience is searching for right now — scout X/Twitter and Reddit for trending topics, discover and deep-analyze competitors, and find content gaps. Combine social signals with SEO intelligence. Powered by Citedy.
npx claudepluginhub citedy/claude-plugins --plugin citedy-seo-agentThis skill uses the workspace's default tool permissions.
Find what your audience is searching for right now. This skill combines real-time social signals from X/Twitter and Reddit with SEO intelligence — giving you trending topics, competitor deep-dives, and content gaps in one workflow.
Conducts topic and competitor research for content types like YouTube, blogs, and social media. Identifies gaps, analyzes landscapes before creation. Triggers on 'research this' or competitor queries.
Analyzes website URL to deploy AI agents generating SEO audits with fix snippets, ready-to-publish content for Reddit/HN/Twitter, competitor intel, and prioritized marketing plans.
Researches topics by collecting 5-10 source articles, auto-tagging by theme, extracting key data points, and generating structured research briefs for content creation.
Share bugs, ideas, or general feedback.
Find what your audience is searching for right now. This skill combines real-time social signals from X/Twitter and Reddit with SEO intelligence — giving you trending topics, competitor deep-dives, and content gaps in one workflow.
What sets this apart from DataForSEO or Semrush: those tools show you historical search volume. This skill shows you what people are talking about today on social — and maps those signals directly to content opportunities your competitors haven't covered yet.
Use cases:
| Situation | What to do |
|---|---|
| "What should I write about today?" | Scout X + Reddit for trending topics in your niche |
| "What is my competitor doing?" | Discover + analyze competitor domains |
| "What content am I missing?" | Generate content gaps vs competitor URLs |
| "Morning briefing on AI trends" | Full workflow: X scout + Reddit scout + gaps |
| "Find competitors in [niche]" | Discover competitors by keywords |
POST https://www.citedy.com/api/agent/register
Content-Type: application/json
{
"name": "My Trend Scout",
"blog_url": "https://yourblog.com"
}
Response:
{
"api_key": "citedy_agent_xxxxxxxxxxxx",
"tenant_id": "uuid",
"blog_handle": "yourblog",
"credits": 100
}
Store api_key as CITEDY_API_KEY in your environment.
All API calls require:
Authorization: Bearer $CITEDY_API_KEY
GET https://www.citedy.com/api/agent/health
Authorization: Bearer $CITEDY_API_KEY
{ "status": "ok", "version": "3.0.0" }
Step 1: Start the scout run
POST https://www.citedy.com/api/agent/scout/x
Authorization: Bearer $CITEDY_API_KEY
Content-Type: application/json
{
"query": "AI content automation",
"mode": "fast",
"limit": 20
}
Response:
{
"run_id": "x_run_abc123",
"status": "processing",
"estimated_seconds": 15
}
Step 2: Poll for results (poll every 5s until status: "completed")
GET https://www.citedy.com/api/agent/scout/x/x_run_abc123
Authorization: Bearer $CITEDY_API_KEY
{
"run_id": "x_run_abc123",
"status": "completed",
"results": [
{
"topic": "GPT-5 rumored release date",
"engagement_score": 94,
"tweet_count": 1240,
"sentiment": "excited",
"top_posts": ["..."],
"content_angle": "Break down what GPT-5 means for content creators"
}
],
"credits_used": 35
}
Step 1: Start the scout run
POST https://www.citedy.com/api/agent/scout/reddit
Authorization: Bearer $CITEDY_API_KEY
Content-Type: application/json
{
"query": "AI writing tools comparison",
"subreddits": ["SEO", "marketing", "artificial"],
"limit": 15
}
Response:
{
"run_id": "reddit_run_xyz789",
"status": "processing",
"estimated_seconds": 12
}
Step 2: Poll for results
GET https://www.citedy.com/api/agent/scout/reddit/reddit_run_xyz789
Authorization: Bearer $CITEDY_API_KEY
{
"run_id": "reddit_run_xyz789",
"status": "completed",
"results": [
{
"topic": "People frustrated with Jasper pricing",
"subreddit": "r/SEO",
"upvotes": 847,
"comments": 134,
"pain_point": "Too expensive for small teams",
"content_angle": "Write a comparison targeting budget-conscious teams"
}
],
"credits_used": 30
}
Step 1: Generate gaps (synchronous, returns when done)
POST https://www.citedy.com/api/agent/gaps/generate
Authorization: Bearer $CITEDY_API_KEY
Content-Type: application/json
{
"competitor_urls": [
"https://jasper.ai/blog",
"https://copy.ai/blog"
]
}
{
"status": "completed",
"gaps_count": 23,
"top_gaps": [
{
"topic": "AI content for e-commerce product descriptions",
"competitor_coverage": "none",
"search_volume_est": "high",
"difficulty": "medium",
"recommended_angle": "Step-by-step guide with real examples"
}
],
"credits_used": 40
}
Step 2: Retrieve all gaps
GET https://www.citedy.com/api/agent/gaps
Authorization: Bearer $CITEDY_API_KEY
Discover by keywords:
POST https://www.citedy.com/api/agent/competitors/discover
Authorization: Bearer $CITEDY_API_KEY
Content-Type: application/json
{
"keywords": ["AI blog automation", "SEO content tool", "autopilot blogging"]
}
{
"competitors": [
{ "domain": "jasper.ai", "relevance_score": 0.94, "category": "direct" },
{ "domain": "surfer.seo", "relevance_score": 0.81, "category": "partial" }
],
"credits_used": 20
}
Deep-analyze a competitor:
POST https://www.citedy.com/api/agent/competitors/scout
Authorization: Bearer $CITEDY_API_KEY
Content-Type: application/json
{
"domain": "jasper.ai",
"mode": "fast"
}
{
"domain": "jasper.ai",
"content_strategy": {
"posting_frequency": "3x/week",
"top_topics": ["copywriting", "AI tools", "marketing"],
"avg_word_count": 1850,
"formats": ["how-to", "listicle", "comparison"]
},
"top_performing_content": [...],
"weaknesses": ["No Reddit presence", "Ignores technical SEO topics"],
"credits_used": 25
}
1. POST /api/agent/scout/x { "query": "AI tools 2025", "mode": "fast" }
2. Poll GET /api/agent/scout/x/{runId} until status = "completed"
3. POST /api/agent/scout/reddit { "query": "AI tools", "subreddits": ["MachineLearning", "artificial"] }
4. Poll GET /api/agent/scout/reddit/{runId}
5. Summarize top 5 opportunities with content angles
Estimated cost: 35 + 30 = 65 credits
1. POST /api/agent/competitors/scout { "domain": "competitor.com", "mode": "ultimate" }
2. POST /api/agent/gaps/generate { "competitor_urls": ["https://competitor.com/blog"] }
3. GET /api/agent/gaps
4. Return top 10 gaps sorted by opportunity score
Estimated cost: 50 + 40 = 90 credits
1. POST /api/agent/scout/x { "query": "[your niche]", "mode": "fast" }
2. POST /api/agent/scout/reddit { "query": "[your niche]", "subreddits": [...] }
3. Poll both runs in parallel
4. GET /api/agent/gaps (use cached gaps from last generate)
5. Compile briefing: trending topics + audience pain points + open content gaps
Estimated cost: 35 + 30 = 65 credits (gaps free if cached)
| Endpoint | Method | Credits | Description |
|---|---|---|---|
/api/agent/health | GET | 0 | Service health check |
/api/agent/me | GET | 0 | Your account info, credits balance |
/api/agent/status | GET | 0 | Current run statuses |
POST /api/agent/scout/xStart an async X/Twitter trend scout run.
| Parameter | Type | Required | Description |
|---|---|---|---|
query | string | yes | Topic or keyword to scout |
mode | fast | ultimate | no | fast = top posts (35 credits), ultimate = deep analysis (70 credits). Default: fast |
limit | number | no | Max results to return (default: 20, max: 50) |
Response: { run_id, status: "processing", estimated_seconds }
GET /api/agent/scout/x/{runId}Poll X scout run status and results.
Response when processing: { run_id, status: "processing" }
Response when completed: { run_id, status: "completed", results: [...], credits_used }
Credits: 0 (polling is free)
POST /api/agent/scout/redditStart an async Reddit trend scout run.
| Parameter | Type | Required | Description |
|---|---|---|---|
query | string | yes | Topic or keyword to scout |
subreddits | string[] | no | Specific subreddits to search (default: auto-select by topic) |
limit | number | no | Max results (default: 15, max: 30) |
Response: { run_id, status: "processing", estimated_seconds }
Credits: 30 per run
GET /api/agent/scout/reddit/{runId}Poll Reddit scout run status and results.
Credits: 0 (polling is free)
POST /api/agent/gaps/generateAnalyze competitor content and generate gaps for your blog. Synchronous.
| Parameter | Type | Required | Description |
|---|---|---|---|
competitor_urls | string[] | yes | Blog/content URLs to analyze (max: 5) |
Response: { status: "completed", gaps_count, top_gaps: [...], credits_used }
Credits: 40 per call
GET /api/agent/gapsRetrieve all previously generated content gaps for your account.
Credits: 0
POST /api/agent/competitors/discoverFind competitors by keywords.
| Parameter | Type | Required | Description |
|---|---|---|---|
keywords | string[] | yes | Keywords that define your niche (min: 1, max: 10) |
Response: { competitors: [{ domain, relevance_score, category }], credits_used }
Credits: 20 per call
POST /api/agent/competitors/scoutDeep-analyze a competitor's content strategy.
| Parameter | Type | Required | Description |
|---|---|---|---|
domain | string | yes | Competitor domain (e.g. jasper.ai) |
mode | fast | ultimate | no | fast = summary (25 credits), ultimate = full deep-dive (50 credits). Default: fast |
Response: { domain, content_strategy, top_performing_content, weaknesses, credits_used }
Credits: 25 (fast) / 50 (ultimate)
| Action | Credits |
|---|---|
| Scout X — fast | 35 |
| Scout X — ultimate | 70 |
| Scout Reddit | 30 |
| Content gaps generate | 40 |
| Retrieve gaps (cached) | 0 |
| Discover competitors | 20 |
| Scout competitor — fast | 25 |
| Scout competitor — ultimate | 50 |
| Polling (any run) | 0 |
| Health / me / status | 0 |
Credits are deducted at job start. Failed runs are refunded automatically.
Top up credits at: https://www.citedy.com/dashboard/billing
| Category | Limit |
|---|---|
| Scout (X + Reddit combined) | 10 runs / hour |
| Content gaps generate | 10 calls / hour |
| Competitor scout | 20 calls / hour |
| General API | 60 requests / minute |
Rate limit headers are returned on every response:
X-RateLimit-Limit: 10
X-RateLimit-Remaining: 7
X-RateLimit-Reset: 1709295600
| HTTP Status | Code | Meaning |
|---|---|---|
| 401 | unauthorized | Invalid or missing API key |
| 402 | insufficient_credits | Not enough credits for this operation |
| 404 | run_not_found | Run ID doesn't exist or expired |
| 422 | validation_error | Invalid request parameters |
| 429 | rate_limited | Too many requests — check X-RateLimit-Reset header |
| 500 | internal_error | Server error — run will be auto-refunded |
Error response format:
{
"error": {
"code": "insufficient_credits",
"message": "This operation requires 35 credits, you have 12.",
"required": 35,
"available": 12
}
}
On 429: Wait until X-RateLimit-Reset timestamp, then retry.
On 500: The run is automatically refunded. Retry after 30 seconds.
When presenting scout results to the user:
This skill covers trend scouting, competitor analysis, and content gaps.
For the full Citedy agent suite:
Register at https://www.citedy.com or contact team@citedy.com for enterprise plans.