Developers
API Documentation
Programmatic access to community intelligence data — posts, signals and share-of-voice analytics across 10+ platforms.
Authentication
Base URL: https://api.communitytracker.ai/v1
All requests are GET requests and require an API key sent in the X-API-Key header. The API does not accept bearer tokens. Call it from a server, script or workflow tool: browsers block requests from other websites, and a key in browser code is visible to anyone.
Example
curl -H "X-API-Key: ct_live_abc123..." "https://api.communitytracker.ai/v1/posts?keyword=AI+tools"Getting your API key
- 1Log in to CommunityTracker at app.communitytracker.ai
- 2Open Claude & API in the sidebar (app.communitytracker.ai/mcp)
- 3Under API keys, click Create API Key and give the key a name
- 4Copy the key now. It is shown only once.
Keys use the format ct_live_ followed by 32 random characters. They are SHA-256 hashed server-side; the plaintext is never stored. You can have up to 5 active API keys and revoke any of them from the same screen.
Plan requirements
API access is included on paid plans and during the trial. If a trial ends without a paid plan, calls return 403 PLAN_NO_API_ACCESS. View plans
Rate limits
Each plan has a daily request limit per account, shared by both endpoints and reset at midnight UTC. The app shows today's usage and your limit next to your API keys. Successful responses include these headers:
Example response headers
X-RateLimit-Limit: <your daily limit>
X-RateLimit-Remaining: <calls left today>
X-RateLimit-Reset: 2026-10-24T00:00:00.000ZWhen the limit is exceeded, the API returns HTTP 429:
{
"error": {
"code": "RATE_LIMIT_EXCEEDED",
"message": "Daily API limit of <limit> requests exceeded. Resets at midnight UTC.",
"limit": <your daily limit>,
"used": <your daily limit>,
"resets_at": "2026-10-24T00:00:00.000Z"
}
}Community posts
Fetch AI-scored community posts for a keyword you track, newest first.
/v1/postsParameters
| Parameter | Type | Required | Description |
|---|---|---|---|
keyword | Typestring | RequiredRequired | DescriptionOne of the keywords you track in CommunityTracker (partial match). A keyword you don't track returns 404 KEYWORD_NOT_FOUND. |
source | Typestring | RequiredOptional | DescriptionFilter by platform, e.g. reddit, linkedin, x, hackernews, github |
min_score | Typenumber | RequiredOptional | DescriptionMinimum AI score, 0–100 (e.g. 70) |
intent | Typestring | RequiredOptional | DescriptionComma-separated: hot, warm, watch |
from | Typestring | RequiredOptional | DescriptionStart date, ISO 8601 (e.g. 2026-10-01) |
to | Typestring | RequiredOptional | DescriptionEnd date, ISO 8601 |
limit | Typenumber | RequiredOptional | DescriptionResults per page (default 50, max 200) |
offset | Typenumber | RequiredOptional | DescriptionPagination offset (default 0, max 10,000) |
Response
{
"data": [
{
"url": "https://reddit.com/r/SaaS/comments/abc123",
"title": "Looking for community monitoring tools",
"body": "We need something to track brand mentions across Reddit and HN...",
"author": "startup_founder",
"source": "reddit",
"kind": null,
"posted_at": "2026-10-21T14:22:00Z",
"ai_score": 82,
"ai_reason": "Direct buying intent for community monitoring tools.",
"intent": "hot",
"urgency": "respond_today",
"buying_stage": "research_phase",
"action_type": "reply_today",
"suggested_play": "Share a case study showing how CT solves this use case.",
"competitor_named": "Brandwatch",
"buying_signals": ["tool_comparison", "budget_mentioned"],
"engagement_status": "new",
"subreddit": "SaaS"
}
],
"meta": {
"total": 142,
"returned": 50,
"limit": 50,
"offset": 0,
"keyword": "community monitoring",
"filters_applied": {}
}
}Response fields
| Field | Type | Description |
|---|---|---|
url | Typestring | DescriptionDirect link to the original post |
title | Typestring | DescriptionPost title |
body | Typestring | DescriptionPost body text |
author | Typestring | DescriptionUsername of the poster |
source | Typestring | DescriptionPlatform the post came from: reddit, linkedin, x, hackernews, github and so on |
kind | Typestring | null | Descriptionpost (Dev.to, Indie Hackers), issue (GitHub), story (Hacker News), question or answer (Stack Overflow); null for Reddit, LinkedIn, X and Slack |
posted_at | Typestring | DescriptionISO 8601 timestamp of when the post was made |
ai_score | Typenumber | DescriptionAI buying-intent score, 0–100 |
ai_reason | Typestring | DescriptionShort explanation of the AI score |
intent | Typestring | Descriptionhot, warm or watch |
urgency | Typestring | Descriptionrespond_now, respond_today, monitor or watch_only |
buying_stage | Typestring | Descriptionbrowsing, problem_aware, research_phase or active_decision |
action_type | Typestring | Descriptionreply_now, reply_today, send_to_sales, send_to_product, monitor or watch_only |
suggested_play | Typestring | DescriptionAI-suggested next step or reply angle |
competitor_named | Typestring | null | DescriptionCompetitor brand mentioned in the post, if any |
buying_signals | Typestring[] | DescriptionBuying-signal tags, e.g. tool_comparison, budget_mentioned |
engagement_status | Typestring | null | DescriptionYour team's status for the post, e.g. new or contacted |
subreddit | Typestring | null | DescriptionSubreddit name for Reddit posts |
Example request
Fetch Reddit posts scored 70 or more since 1 October 2026:
curl -H "X-API-Key: ct_live_your_key_here" \
"https://api.communitytracker.ai/v1/posts?keyword=AI+tools&source=reddit&min_score=70&from=2026-10-01&limit=20"Share of voice
Get share-of-voice (SOV) snapshots and AI summaries for your intelligence queries, the brand and competitor sets you track in the app.
/v1/intelligence/sovHow it works
This endpoint has different modes depending on which parameters you provide:
- No parameters — Returns HTTP 400 with a list of your active queries and their IDs
- query_id only — Returns the latest SOV snapshot for that query
- query_id + date — Returns the snapshot for that specific date
- query_id + from/to — Returns up to
limitsnapshots in the date range, newest first.limitdefaults to 1, so pass it (max 30) to get a series
Step 1: find your query ID
Call the endpoint without parameters to get your active queries:
curl -H "X-API-Key: ct_live_your_key_here" "https://api.communitytracker.ai/v1/intelligence/sov"Response (HTTP 400, but includes your queries):
{
"error": {
"code": "MISSING_QUERY_ID",
"message": "The \"query_id\" parameter is required. ..."
},
"queries": [
{
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"primary_brand": "YourBrand",
"competitor_brands": ["Competitor A", "Competitor B"],
"communities": ["reddit", "hackernews"]
}
]
}Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
query_id | Typestring (UUID) | RequiredYes* | DescriptionYour intelligence query ID. Omit it to get the list of your query IDs. |
date | Typestring | RequiredNo | DescriptionSnapshot date, YYYY-MM-DD |
from | Typestring | RequiredNo | DescriptionStart of a date range, YYYY-MM-DD |
to | Typestring | RequiredNo | DescriptionEnd of a date range, YYYY-MM-DD |
limit | Typenumber | RequiredNo | DescriptionSnapshots to return with from/to (default 1, max 30). Pass limit to get more than one. |
Response: single snapshot
When fetching the latest snapshot or a specific date, data is a single object (shortened here):
{
"data": {
"snapshot_date": "2026-10-16",
"time_range": "rolling_30",
"range_days": 30,
"ai_summary": {
"executive_summary": "YourBrand holds 29.5% share of voice, ahead of Competitor A...",
"key_takeaways": ["..."],
"opportunities": ["..."],
"risks": ["..."],
"action_items": ["..."]
},
"total_mentions": 604,
"sov_breakdown": {
"YourBrand": { "sov_percentage": 29.5, "total_mentions": 203 },
"Competitor A": { "sov_percentage": 18.1, "total_mentions": 112 }
},
"community_sov": {
"reddit": {
"_total": 120,
"YourBrand": { "sov_pct": 41.7, "mentions": 50 },
"Competitor A": { "sov_pct": 25.0, "mentions": 30 }
}
},
"trending_topics": [
{ "term": "pricing", "mentions": 45 },
{ "term": "integrations", "mentions": 32 }
]
},
"query": {
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"primary_brand": "YourBrand",
"competitor_brands": ["Competitor A", "Competitor B"],
"communities": ["reddit", "hackernews"],
"range_days": 30
},
"meta": {
"snapshots_returned": 1,
"latest_snapshot_date": "2026-10-16"
}
}Note: each snapshot's share-of-voice data sits directly in data, not under a nested key. Besides sov_breakdown (per brand) and community_sov (per platform, then per brand), you will find keys such as total_mentions, trending_topics, intent_breakdown, source_breakdown and delta. ai_summary is an object, or null on older snapshots.
Response: multiple snapshots
When you pass from/to with a limit and more than one snapshot matches, data is an array, newest first. If only one matches, data is a single object as above.
{
"data": [
{
"snapshot_date": "2026-10-16",
"time_range": "rolling_30",
"range_days": 30,
"ai_summary": { ... },
"total_mentions": 604,
"sov_breakdown": { ... },
"community_sov": { ... }
},
{
"snapshot_date": "2026-10-09",
"time_range": "rolling_30",
"range_days": 30,
"ai_summary": { ... },
"total_mentions": 571,
"sov_breakdown": { ... },
"community_sov": { ... }
}
],
"query": { ... },
"meta": {
"snapshots_returned": 2,
"from": "2026-10-01",
"to": "2026-10-20"
}
}Example requests
Get the latest snapshot:
curl -H "X-API-Key: ct_live_your_key_here" \
"https://api.communitytracker.ai/v1/intelligence/sov?query_id=a1b2c3d4-e5f6-7890-abcd-ef1234567890"Get up to 30 snapshots for a date range:
curl -H "X-API-Key: ct_live_your_key_here" \
"https://api.communitytracker.ai/v1/intelligence/sov?query_id=a1b2c3d4-...&from=2026-10-01&to=2026-10-20&limit=30"Errors
All errors follow a consistent format:
{
"error": {
"code": "ERROR_CODE",
"message": "Human-readable description of what went wrong."
}
}Error codes
| HTTP status | Error code | Description |
|---|---|---|
| 401 | Error codeINVALID_API_KEY | DescriptionThe X-API-Key header is missing or malformed, or the key is unknown or revoked |
| 403 | Error codePLAN_NO_API_ACCESS | DescriptionYour trial has ended without a paid plan, or your plan does not include API access |
| 400 | Error codeMISSING_KEYWORD | DescriptionThe keyword parameter is missing (/v1/posts) |
| 400 | Error codeMISSING_QUERY_ID | DescriptionThe query_id parameter is missing (/v1/intelligence/sov). The response lists your query IDs. |
| 400 | Error codeINVALID_PARAM | DescriptionA date is not valid, the keyword is over 200 characters, or offset is over 10,000 |
| 404 | Error codeKEYWORD_NOT_FOUND | DescriptionThe keyword does not match any keyword you track (/v1/posts) |
| 404 | Error codeQUERY_NOT_FOUND | DescriptionNo active intelligence query with this query_id in your account |
| 404 | Error codeNO_SNAPSHOTS | DescriptionThe query has no snapshot yet, or none for the date you asked for |
| 405 | Error codeMETHOD_NOT_ALLOWED | DescriptionOnly GET is supported |
| 429 | Error codeRATE_LIMIT_EXCEEDED | DescriptionYou have used today's request limit; it resets at midnight UTC |
| 500 | Error codeQUERY_ERROR | DescriptionThe data query failed; try again |
| 500 | Error codeINTERNAL_ERROR | DescriptionAn unexpected server error occurred |
Code examples
Python
import requests
BASE_URL = "https://api.communitytracker.ai/v1"
API_KEY = "ct_live_your_key_here"
HEADERS = {"X-API-Key": API_KEY}
def get_posts(keyword, source=None, min_score=None, limit=50):
"""Fetch community posts for a keyword."""
params = {"keyword": keyword, "limit": limit}
if source:
params["source"] = source
if min_score is not None:
params["min_score"] = min_score
resp = requests.get(f"{BASE_URL}/posts", headers=HEADERS, params=params)
resp.raise_for_status()
# Check rate limits
remaining = resp.headers.get("X-RateLimit-Remaining")
print(f"Requests remaining today: {remaining}")
return resp.json()
def get_sov(query_id, from_date=None, to_date=None, limit=30):
"""Fetch SOV snapshots for an intelligence query.
With from/to, up to `limit` snapshots come back (max 30) and data is a
list when more than one matches. Without them, you get the latest one.
"""
params = {"query_id": query_id}
if from_date:
params["from"] = from_date
if to_date:
params["to"] = to_date
if from_date or to_date:
params["limit"] = limit
resp = requests.get(f"{BASE_URL}/intelligence/sov", headers=HEADERS, params=params)
resp.raise_for_status()
return resp.json()
def list_queries():
"""List your active intelligence queries and their IDs (the API answers 400 with the list)."""
resp = requests.get(f"{BASE_URL}/intelligence/sov", headers=HEADERS)
return resp.json().get("queries", [])
# Usage
posts = get_posts("AI tools", source="reddit", min_score=70)
for post in posts["data"]:
print(f'[{post["ai_score"]}] {post["title"]} -- {post["url"]}')
queries = list_queries()
if queries:
sov = get_sov(queries[0]["id"])
summary = sov["data"].get("ai_summary") or {}
print(summary.get("executive_summary"))JavaScript / Node.js
const BASE_URL = "https://api.communitytracker.ai/v1";
const API_KEY = "ct_live_your_key_here";
async function getPosts(keyword, { source, minScore, limit = 50 } = {}) {
const params = new URLSearchParams({ keyword, limit });
if (source) params.set("source", source);
if (minScore != null) params.set("min_score", minScore);
const resp = await fetch(`${BASE_URL}/posts?${params}`, {
headers: { "X-API-Key": API_KEY },
});
if (!resp.ok) {
const err = await resp.json();
throw new Error(`${err.error.code}: ${err.error.message}`);
}
console.log(`Remaining: ${resp.headers.get("X-RateLimit-Remaining")}`);
return resp.json();
}
// With from/to, up to `limit` snapshots (max 30); data is an array when more than one matches.
async function getSov(queryId, { from, to, limit = 30 } = {}) {
const params = new URLSearchParams({ query_id: queryId });
if (from) params.set("from", from);
if (to) params.set("to", to);
if (from || to) params.set("limit", limit);
const resp = await fetch(`${BASE_URL}/intelligence/sov?${params}`, {
headers: { "X-API-Key": API_KEY },
});
if (!resp.ok) {
const err = await resp.json();
throw new Error(`${err.error.code}: ${err.error.message}`);
}
return resp.json();
}
// The API answers 400 MISSING_QUERY_ID with your queries in the body.
async function listQueries() {
const resp = await fetch(`${BASE_URL}/intelligence/sov`, {
headers: { "X-API-Key": API_KEY },
});
const data = await resp.json();
return data.queries || [];
}
// Usage
const posts = await getPosts("AI tools", { source: "reddit", minScore: 70 });
posts.data.forEach((p) => console.log(`[${p.ai_score}] ${p.title}`));
const queries = await listQueries();
if (queries.length > 0) {
const sov = await getSov(queries[0].id);
console.log(sov.data.ai_summary?.executive_summary);
}Quick reference
All paths are relative to https://api.communitytracker.ai.
| Method | Endpoint | Description | Required parameter |
|---|---|---|---|
| GET | Endpoint/v1/posts?keyword=… | DescriptionFetch AI-scored posts for a keyword you track | Required parameterkeyword |
| GET | Endpoint/v1/intelligence/sov | DescriptionList your active intelligence queries (HTTP 400 with the list) | Required parameternone |
| GET | Endpoint/v1/intelligence/sov?query_id=… | DescriptionGet the latest share-of-voice snapshot | Required parameterquery_id |
| GET | Endpoint/v1/intelligence/sov?query_id=…&date=… | DescriptionGet the snapshot for a specific date | Required parameterquery_id, date |
| GET | Endpoint/v1/intelligence/sov?query_id=…&from=…&to=…&limit=… | DescriptionGet up to 30 snapshots over a date range | Required parameterquery_id, from or to |
Ready to get started?
Create your API key under Claude & API in the app and start building with CommunityTracker data.