Causeway

API Reference

Read-only REST API for accessing your growth data programmatically. Pro plan required.

Authentication

All requests must include your API key in the Authorization header:

Authorization: Bearer cwy_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Generate keys in Settings → API & Integrations. Keys are shown once at creation.

Rate Limits

1,000 requests per day per key. Resets at midnight UTC. Exceeding the limit returns a 429 RATE_LIMIT_EXCEEDED error.

Endpoints

GEThttps://causeway.you/api/v1/me

Your profile and all connected platforms.

Response

{
  "user": {
    "id": "uuid",
    "name": "Jane Smith",
    "email": "jane@example.com",
    "subscription_tier": "pro",
    "subscription_status": "active",
    "member_since": "2025-01-01T00:00:00Z"
  },
  "connected_platforms": [
    { "platform": "tiktok", "username": "janecreates", "last_synced_at": "..." }
  ]
}

GEThttps://causeway.you/api/v1/followers

Follower history across all connected platforms.

ParamTypeDescription

daysinteger1–90, default 30

platformstringFilter: youtube | instagram | tiktok | facebook

Response

{
  "total_current": 84302,
  "history": [
    { "date": "2025-01-15", "total": 83100, "tiktok": 40200, "instagram": 28400 }
  ]
}

GEThttps://causeway.you/api/v1/spikes

Detected follower spike events.

ParamTypeDescription

limitinteger1–50, default 10

severitystringminor | moderate | major | viral

platformstringPlatform filter

Response

{
  "spikes": [
    {
      "id": "uuid",
      "date": "2025-01-15",
      "platform": "tiktok",
      "followers_before": 40000,
      "followers_after": 41240,
      "delta": 1240,
      "delta_percent": 3.1,
      "severity": "major",
      "ai_insight": "Spike likely caused by a viral duet from @creator..."
    }
  ]
}

GEThttps://causeway.you/api/v1/spikes/:id

Full spike detail with all ranked correlations.

Response

{
  "id": "uuid",
  "date": "2025-01-15",
  "platform": "tiktok",
  "delta": 1240,
  "delta_percent": 3.1,
  "severity": "major",
  "ai_insight": "...",
  "correlations": [
    {
      "id": "uuid",
      "confidence_score": 0.91,
      "hours_before_spike": 3,
      "is_likely_cause": true,
      "mention": {
        "author": "bigcreator",
        "content_url": "https://tiktok.com/...",
        "view_count": 2400000,
        "platform": "tiktok"
      }
    }
  ]
}

GEThttps://causeway.you/api/v1/mentions

Shoutouts and mentions across all platforms.

ParamTypeDescription

limitinteger1–100, default 20

platformstringPlatform filter

sincestringISO date — e.g. 2025-01-01

Response

{
  "mentions": [
    {
      "id": "uuid",
      "platform": "instagram",
      "author_username": "bigcreator",
      "content_url": "https://instagram.com/p/...",
      "content_text": "Check out @yourchannel!",
      "view_count": 340000,
      "like_count": 12000,
      "mentioned_at": "2025-01-14T18:00:00Z"
    }
  ]
}

GEThttps://causeway.you/api/v1/summary

One-call snapshot designed for MCP and AI tool consumption. Returns current follower totals, last spike, top mention, and latest AI insight.

Response

{
  "as_of": "2025-02-28",
  "total_followers": 84302,
  "platforms": [
    { "platform": "tiktok", "username": "janecreates", "follower_count": 48000 }
  ],
  "last_spike": { "date": "2025-01-15", "platform": "tiktok", "delta": 1240, "severity": "major", "ai_insight": "..." },
  "top_mention": { "author": "bigcreator", "content_url": "...", "view_count": 2400000 }
}

Error Codes

All errors return a JSON body:

{ "error": { "code": "INVALID_KEY", "message": "API key not found or revoked." } }

401UNAUTHORIZEDMissing Authorization header

401INVALID_KEYKey not found, revoked, or inactive

403SUBSCRIPTION_REQUIREDActive Pro subscription required

404NOT_FOUNDRequested resource does not exist

429RATE_LIMIT_EXCEEDED1,000 requests/day limit reached

500INTERNAL_ERRORUnexpected server error

MCP Integration

Query your growth data in natural language using Claude Desktop or any MCP-compatible AI tool.

npm install -g causeway-mcp

Then add to your claude_desktop_config.json:

{
  "mcpServers": {
    "causeway": {
      "command": "causeway-mcp",
      "env": { "CAUSEWAY_API_KEY": "cwy_live_..." }
    }
  }
}

Available tools: get_summary, get_spikes, get_spike_detail, get_mentions, get_followers.

Get your API key in Settings → API & Integrations.