Skip to content
CommunityTracker

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

  1. 1Log in to CommunityTracker at app.communitytracker.ai
  2. 2Open Claude & API in the sidebar (app.communitytracker.ai/mcp)
  3. 3Under API keys, click Create API Key and give the key a name
  4. 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.000Z

When 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.

GET/v1/posts

Parameters

Parameters for GET /v1/posts
ParameterTypeRequiredDescription
keywordTypestringRequiredRequiredDescriptionOne of the keywords you track in CommunityTracker (partial match). A keyword you don't track returns 404 KEYWORD_NOT_FOUND.
sourceTypestringRequiredOptionalDescriptionFilter by platform, e.g. reddit, linkedin, x, hackernews, github
min_scoreTypenumberRequiredOptionalDescriptionMinimum AI score, 0–100 (e.g. 70)
intentTypestringRequiredOptionalDescriptionComma-separated: hot, warm, watch
fromTypestringRequiredOptionalDescriptionStart date, ISO 8601 (e.g. 2026-10-01)
toTypestringRequiredOptionalDescriptionEnd date, ISO 8601
limitTypenumberRequiredOptionalDescriptionResults per page (default 50, max 200)
offsetTypenumberRequiredOptionalDescriptionPagination 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

Fields in each post returned by GET /v1/posts
FieldTypeDescription
urlTypestringDescriptionDirect link to the original post
titleTypestringDescriptionPost title
bodyTypestringDescriptionPost body text
authorTypestringDescriptionUsername of the poster
sourceTypestringDescriptionPlatform the post came from: reddit, linkedin, x, hackernews, github and so on
kindTypestring | nullDescriptionpost (Dev.to, Indie Hackers), issue (GitHub), story (Hacker News), question or answer (Stack Overflow); null for Reddit, LinkedIn, X and Slack
posted_atTypestringDescriptionISO 8601 timestamp of when the post was made
ai_scoreTypenumberDescriptionAI buying-intent score, 0–100
ai_reasonTypestringDescriptionShort explanation of the AI score
intentTypestringDescriptionhot, warm or watch
urgencyTypestringDescriptionrespond_now, respond_today, monitor or watch_only
buying_stageTypestringDescriptionbrowsing, problem_aware, research_phase or active_decision
action_typeTypestringDescriptionreply_now, reply_today, send_to_sales, send_to_product, monitor or watch_only
suggested_playTypestringDescriptionAI-suggested next step or reply angle
competitor_namedTypestring | nullDescriptionCompetitor brand mentioned in the post, if any
buying_signalsTypestring[]DescriptionBuying-signal tags, e.g. tool_comparison, budget_mentioned
engagement_statusTypestring | nullDescriptionYour team's status for the post, e.g. new or contacted
subredditTypestring | nullDescriptionSubreddit 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.

GET/v1/intelligence/sov

How 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 limit snapshots in the date range, newest first. limit defaults 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

Parameters for GET /v1/intelligence/sov
ParameterTypeRequiredDescription
query_idTypestring (UUID)RequiredYes*DescriptionYour intelligence query ID. Omit it to get the list of your query IDs.
dateTypestringRequiredNoDescriptionSnapshot date, YYYY-MM-DD
fromTypestringRequiredNoDescriptionStart of a date range, YYYY-MM-DD
toTypestringRequiredNoDescriptionEnd of a date range, YYYY-MM-DD
limitTypenumberRequiredNoDescriptionSnapshots 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

Error codes
HTTP statusError codeDescription
401Error codeINVALID_API_KEYDescriptionThe X-API-Key header is missing or malformed, or the key is unknown or revoked
403Error codePLAN_NO_API_ACCESSDescriptionYour trial has ended without a paid plan, or your plan does not include API access
400Error codeMISSING_KEYWORDDescriptionThe keyword parameter is missing (/v1/posts)
400Error codeMISSING_QUERY_IDDescriptionThe query_id parameter is missing (/v1/intelligence/sov). The response lists your query IDs.
400Error codeINVALID_PARAMDescriptionA date is not valid, the keyword is over 200 characters, or offset is over 10,000
404Error codeKEYWORD_NOT_FOUNDDescriptionThe keyword does not match any keyword you track (/v1/posts)
404Error codeQUERY_NOT_FOUNDDescriptionNo active intelligence query with this query_id in your account
404Error codeNO_SNAPSHOTSDescriptionThe query has no snapshot yet, or none for the date you asked for
405Error codeMETHOD_NOT_ALLOWEDDescriptionOnly GET is supported
429Error codeRATE_LIMIT_EXCEEDEDDescriptionYou have used today's request limit; it resets at midnight UTC
500Error codeQUERY_ERRORDescriptionThe data query failed; try again
500Error codeINTERNAL_ERRORDescriptionAn 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.

Quick reference of every endpoint
MethodEndpointDescriptionRequired parameter
GETEndpoint/v1/posts?keyword=…DescriptionFetch AI-scored posts for a keyword you trackRequired parameterkeyword
GETEndpoint/v1/intelligence/sovDescriptionList your active intelligence queries (HTTP 400 with the list)Required parameternone
GETEndpoint/v1/intelligence/sov?query_id=…DescriptionGet the latest share-of-voice snapshotRequired parameterquery_id
GETEndpoint/v1/intelligence/sov?query_id=…&date=…DescriptionGet the snapshot for a specific dateRequired parameterquery_id, date
GETEndpoint/v1/intelligence/sov?query_id=…&from=…&to=…&limit=…DescriptionGet up to 30 snapshots over a date rangeRequired 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.