Cloutfind API

Run a natural-language creator search.

Request body

{
  "query": "beauty creators under 50K subs who've done paid skincare promos",
  "manual_filters": {
    "platform": "youtube",
    "min_subscribers": 5000,
    "max_subscribers": 50000
  }
}

Example

curl -X POST https://cloutfind.com/cf/search/ai \
  -H "X-API-Key: cf_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"query": "beauty creators under 50K subs who have done paid skincare promos"}'

Response

{
  "query": "...",
  "tier": "agency",
  "filters": {"platform": "youtube", "min_subscribers": null, "max_subscribers": 50000, ...},
  "rationale": "Filtering YouTube beauty channels under 50K subs with paid promo history.",
  "results": [
    {
      "id": "...uuid...",
      "display_name": "...",
      "platform": "youtube",
      "subscriber_count": 28400,
      "engagement_rate": 5.6,
      "has_done_sponsors": true,
      "sponsor_count_90d": 4,
      "ai_fit_score": 87,
      "ai_rationale": "Skincare-focused with three recent paid promotions ...",
      "niche_matched_terms": ["skincare", "anti-aging"],
      "niche_match_count": 2,
      "niche_total_terms": 3,
      "niche_density_pct": 64.2
    }
  ],
  "total": 23,
  "ranked": true,
  "coverage_thin": false,
  "niche_term_count": 3,
  "ingest_job_id": null,
  "ingest_job_status": null
}

# When coverage_thin is true, ingest_job_id will reference a queued
# background YouTube ingest job. Poll GET /ingest-jobs/{id} for status.
# Hard rule: low ai_fit_score creators (< 30) are still returned but
# UIs should hide them by default - they're truly off-niche.

Poll the status of a background search-ingest job.

Example

curl https://cloutfind.com/cf/ingest-jobs/<job-uuid> \
  -H "X-API-Key: cf_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Response

{
  "id": "...uuid...",
  "keyword": "vegan recipe creator",
  "status": "done",
  "creators_added": 7,
  "videos_added": 145,
  "channels_searched": 8,
  "created_at": "2026-05-17T14:21:09Z",
  "started_at": "2026-05-17T14:21:11Z",
  "completed_at": "2026-05-17T14:21:54Z",
  "error_message": null
}

# Status enum: queued | running | done | failed | rate_limited.
# Use this to render a live "expanding the index..." UI in your
# integration when /search/ai returns coverage_thin = true.

Score a single creator against your brand profile.

Request body

{
  "brand_context": "Skincare brand for sensitive skin",
  "outreach_goal": "Sponsored review video"
}

Example

curl -X POST https://cloutfind.com/cf/creators/<id>/brand-fit \
  -H "X-API-Key: cf_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{}'

Response

{
  "creator_id": "...uuid...",
  "fit_score": 84,
  "rationale": "Audience strongly overlaps your target demo ...",
  "concerns": ["Heavy sponsor cadence may dilute your message"],
  "suggested_angle": "Lead with a unique-skin-type framing ..."
}

Generate three personalized outreach variants for one creator.

Request body

{
  "brand_context": "Indie game studio shipping Steam-bound puzzle title",
  "outreach_goal": "Paid sponsorship for launch week"
}

Example

curl -X POST https://cloutfind.com/cf/creators/<id>/outreach-draft \
  -H "X-API-Key: cf_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{}'

Response

{
  "creator_id": "...uuid...",
  "drafts": [
    {"tone": "casual",      "subject": "...", "body": "..."},
    {"tone": "professional","subject": "...", "body": "..."},
    {"tone": "direct",      "subject": "...", "body": "..."}
  ]
}

Fetch a full creator profile by ID.

Example

curl https://cloutfind.com/cf/creators/<id> \
  -H "X-API-Key: cf_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Response

{
  "id": "...uuid...",
  "platform": "youtube",
  "display_name": "...",
  "subscriber_count": 12300,
  "engagement_rate": 4.2,
  "estimated_price_low": 80000,
  "estimated_price_high": 220000,
  "has_done_sponsors": true,
  "sponsor_count_90d": 3,
  ...
}

Index size, useful for cache invalidation.

Example

curl https://cloutfind.com/cf/stats/public

Response

{"creators": 800, "videos": 19000, "verticals": 60, "refreshed_at": "..."}

Save a search to your watchlist (Agency + Enterprise for alerts).

Request body

{
  "name": "Top mid-tier beauty creators",
  "query": "beauty creators with paid skincare promotions, 5k-30k subs",
  "alerts_enabled": true,
  "alert_email": "ops@yourcompany.com",
  "webhook_url": "https://hooks.example.com/incoming/abc"
}

Example

curl -X POST https://cloutfind.com/cf/me/saved-searches \
  -H "X-API-Key: cf_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d @body.json

Response

{
  "id": "...uuid...",
  "name": "...",
  "query": "...",
  "alerts_enabled": true,
  "alert_email": "ops@yourcompany.com",
  "webhook_url": "https://...",
  "last_run_at": null,
  "last_match_count": null,
  ...
}

Force-run a watchlist immediately, bypassing the hourly schedule.

Example

curl -X POST https://cloutfind.com/cf/me/saved-searches/<id>/run-now \
  -H "X-API-Key: cf_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Response

{
  "ok": true,
  "match_count": 14,
  "alert_sent": true,
  "webhook_sent": true
}