Reading data

Campaigns

Campaigns are the top-level unit of work in UGCBloom: a brief, a budget, a set of creators, and the videos they make. Most of the read API hangs off a campaign id, so the typical pattern is: list campaigns first, pick the one you care about, then drill in.

GET/campaigns

List all campaigns

Paginated list of campaigns in your org. Use the campaign ids from the response in every other endpoint.

pageinteger

Page number (default: 1)

per_pageinteger

Items per page, max 100 (default: 25)

searchstring

Search by campaign title

statusenum

draft, requires_payment, active, under_review, ended, disapproved

sortstring

Field to sort by (e.g. created_at, budget)

orderenum

asc or desc (default: desc)

sincedate

Filter campaigns created after this date (ISO 8601)

untildate

Filter campaigns created before this date (ISO 8601)

const response = await fetch(
  "https://ugcbloom.com/api/v1/campaigns", {
  headers: {
    "Authorization": "Bearer ugcb_live_your_api_key_here"
  }
}
);

const data = await response.json();

›Example response

response.json

json

{
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "title": "Summer TikTok Campaign",
      "status": "active",
      "budget": 5000,
      "platforms": ["tiktok", "instagram"],
      "created_at": "2026-01-15T10:00:00Z"
    }
  ],
  "meta": { "page": 1, "per_page": 25, "total": 3 }
}

GET/campaigns/{campaignId}

Get a single campaign

Full campaign detail: brief URL, geo targeting, content requirements, payout config. Handy as the second call after listing.

const response = await fetch(
  "https://ugcbloom.com/api/v1/campaigns/:campaignId", {
  headers: {
    "Authorization": "Bearer ugcb_live_your_api_key_here"
  }
}
);

const data = await response.json();

GET/campaigns/{campaignId}/stats

Campaign statistics

The big rollup. Always returns overview (creators, videos, views, spend, CPM). Use ?include= to add growth (48h/7d deltas), production funnel breakdowns, spend by unit, and the top videos.

includestring

Comma-separated: growth, production, spend, top_videos. Omit for all.

const response = await fetch(
  "https://ugcbloom.com/api/v1/campaigns/:campaignId/stats", {
  headers: {
    "Authorization": "Bearer ugcb_live_your_api_key_here"
  }
}
);

const data = await response.json();

›Example response

response.json

json

{
  "data": {
    "overview": {
      "total_creators": 12, "total_videos": 28,
      "videos_by_status": { "submitted": 3, "approved": 10, "live": 15 },
      "total_views": 450000, "total_spend": 2340.50,
      "cpm": 5.20, "cpm_with_fees": 6.80
    },
    "growth":     { "active_creators": 8, "new_creators_7d": 3, "new_creators_48h": 1 },
    "production": { "total_live": 15, "new_live_7d": 4 }
  }
}

GET/campaigns/{campaignId}/chart

Daily time-series for the campaign

One row per day with views, likes, comments, CPM, and budget remaining. Use it to chart growth trajectories and budget burn.

daysinteger

Number of days (default: 30, max: 365)

const response = await fetch(
  "https://ugcbloom.com/api/v1/campaigns/:campaignId/chart", {
  headers: {
    "Authorization": "Bearer ugcb_live_your_api_key_here"
  }
}
);

const data = await response.json();

›Example response

response.json

json

{
  "data": [
    {
      "date": "2026-03-15",
      "total_views": 125000,
      "total_likes": 8500,
      "cpm": 5.20,
      "cpm_with_fees": 6.80,
      "budget_remaining": 2660.50
    }
  ]
}

GET/campaigns/{campaignId}/analytics

Creator cohort analysis

Follower tier and country distribution, active creator rate, average reach. Answers “who are my creators?” at a glance.

const response = await fetch(
  "https://ugcbloom.com/api/v1/campaigns/:campaignId/analytics", {
  headers: {
    "Authorization": "Bearer ugcb_live_your_api_key_here"
  }
}
);

const data = await response.json();

›Example response

response.json

json

{
  "data": {
    "total_participants": 45,
    "active_creator_rate": 0.67,
    "average_creator_reach": 28500,
    "follower_distribution": [
      { "tier": "0-5K",   "count": 12 },
      { "tier": "10K-50K","count": 15 }
    ],
    "country_distribution": [
      { "country": "US", "label": "United States", "count": 18 }
    ]
  }
}

GET/campaigns/{campaignId}/leaderboard

Ranked list of top-performing videos

Sort by views, likes, comments, or payout. Use for in-app leaderboard widgets or to identify whom to ask for more content.

limitinteger

Number of entries, max 100 (default: 25)

sortenum

views, likes, comments, or payout (default: views)

const response = await fetch(
  "https://ugcbloom.com/api/v1/campaigns/:campaignId/leaderboard", {
  headers: {
    "Authorization": "Bearer ugcb_live_your_api_key_here"
  }
}
);

const data = await response.json();

Each campaign also exposes creator and video sub-resources. See the next sections for those.