# Creator Breakdown

> For the complete documentation index, see [llms.txt](https://www.shortsintel.com/llms.txt). Every docs page is also available as markdown: add .md to its URL. To connect, read [agents.md](https://www.shortsintel.com/agents.md).

> What works for named Creators, by each one's normal.

See what works for specific creators, measured against each one’s normal. A Creator Breakdown reads the creators you name, analyses their recent videos and writes one digest, with every video scored against its own creator rather than against the set.

## What you send

`POST /v1/breakdowns` takes `creators`: up to 10, each a platform and handle or a profile URL, on any mix of tiktok, instagram, youtube, facebook. Or send `collection_id` for a creator collection, frozen when the run starts. `videos_per_creator` sets how many recent videos are read from each, 1 to 50, 25 by default, and 200 at most across all of them. It is a count, not a time window. An optional `intent` drops off-intent videos before they are analysed. Keyword fields are refused: for a niche, use [Research](https://www.shortsintel.com/docs/concepts/research).

`POST /v1/breakdowns` · 9 credits per Creator plus 20 credits per analysed Video, at most 4,090 credits; failed ones are free.

curl:

```bash
curl -X POST "https://www.shortsintel.com/v1/breakdowns" \
  -H "Authorization: Bearer sk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"creators":[{"platform":"tiktok","handle":"glowwithmaya"},{"platform":"tiktok","handle":"skinbyjo"}],"videos_per_creator":25}'
```

TypeScript:

```typescript
const response = await fetch(
  "https://www.shortsintel.com/v1/breakdowns",
  {
    method: "POST",
    headers: {
      "Authorization": "Bearer sk_live_YOUR_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      "creators": [
        {
          "platform": "tiktok",
          "handle": "glowwithmaya"
        },
        {
          "platform": "tiktok",
          "handle": "skinbyjo"
        }
      ],
      "videos_per_creator": 25
    }),
  },
);

if (!response.ok) {
  throw new Error(`ShortsIntel ${response.status}`);
}

const data = await response.json();
```

Python:

```python
import requests

response = requests.post(
    "https://www.shortsintel.com/v1/breakdowns",
    headers={
        "Authorization": "Bearer sk_live_YOUR_KEY",
        "Content-Type": "application/json",
    },
    json={
        "creators": [
            {
                "platform": "tiktok",
                "handle": "glowwithmaya",
            },
            {
                "platform": "tiktok",
                "handle": "skinbyjo",
            },
        ],
        "videos_per_creator": 25,
    },
)
response.raise_for_status()

data = response.json()
```

[Run it in the Playground](https://www.shortsintel.com/console/playground?op=createBreakdown&videos_per_creator=25) (no API Key needed)

200 · The Run finished: a research result with `mode: creators`.

```json
{
  "run": {
    "id": "run_8f2c1ad04b",
    "kind": "research",
    "status": "completed",
    "created_at": "2026-09-08T09:14:02.418Z",
    "completed_at": "2026-09-08T09:14:04.930Z",
    "charge_credits": 1018,
    "list_price_credits": 1018,
    "cached": false
  },
  "result": {
    "digest_version": 5,
    "mode": "creators",
    "coverage": {
      "tiktok": "complete"
    },
    "digest": {
      "summary": "Cold plunge videos are travelling on measured personal diaries rather than on science explainers. The videos that break out open on an unimpressive first number and pay it off with a later one, and keep the discomfort on camera instead of cutting around it. Sentiment is broadly positive, with the negative share concentrated on the cost of equipment.",
      "themes": [
        {
          "name": "30-day diaries",
          "share": 0.45,
          "description": "One creator, one tub, a counter on screen, and the change stated as a number rather than a feeling.",
          "video_ids": [
            "tiktok:7300000000000000000"
          ]
        },
        {
          "name": "Before-workout plunging",
          "share": 0.2,
          "description": "Shorter clips arguing about timing relative to training, usually with a gym setting.",
          "video_ids": [
            "tiktok:7300000000000000042"
          ]
        }
      ],
      "hooks": [
        {
          "text": "Day one I lasted eleven seconds.",
          "video_id": "tiktok:7300000000000000000",
          "hook_type": "stat",
          "why_it_works": "An unimpressive concrete number sets up a payoff the viewer stays for.",
          "template": "Day one I lasted [small number] [unit].",
          "lift": {
            "value": "STORY",
            "video_count": 9,
            "median_views": 1840000,
            "median_engagement_rate": 0.0912,
            "views_lift": 1.6,
            "engagement_lift": 1.21,
            "low_confidence": false
          }
        }
      ],
      "sentiment": {
        "positive": 0.62,
        "neutral": 0.23,
        "negative": 0.15,
        "note": "Enthusiasm for the routine itself; the negative share is almost entirely the price of a tub."
      },
      "angles": [
        {
          "angle": "Open on the day-30 number and work backwards to day one.",
          "rationale": "Every diary in the shortlist that led with the outcome outperformed the ones that led with the method."
        }
      ],
      "gaps": [
        {
          "ask": "Viewers want a cold plunge setup that does not cost hundreds.",
          "comments": [
            {
              "text": "ok but what do I do if I can't afford a 600 dollar tub",
              "video_id": "tiktok:7300000000000000000"
            }
          ],
          "angle": "A 30-day diary on a chest freezer or bathtub build, with the receipt on screen."
        }
      ]
    },
    "videos": [
      {
        "platform": "tiktok",
        "id": "7300000000000000000",
        "url": "https://www.tiktok.com/@someone/video/7300000000000000000",
        "description": "3 minutes at 4°C every morning for 30 days. Here is what actually changed. #coldplunge #recovery",
        "posted_at": "2026-09-05T06:32:11.000Z",
        "duration_seconds": 41,
        "thumbnail_url": "https://p16-sign.tiktokcdn.com/obj/tos-cover-7300000000000000000.jpeg",
        "hashtags": [
          "coldplunge",
          "recovery",
          "morningroutine"
        ],
        "sound": {
          "id": "7180000000000000000",
          "title": "original sound - someone",
          "author": "someone",
          "is_original": true
        },
        "creator": {
          "id": "cre_9d4b2a7f1c",
          "handle": "someone",
          "name": "Someone",
          "follower_count": 184300,
          "avatar_url": "https://p16-sign.tiktokcdn.com/obj/tos-avatar-someone.jpeg",
          "verified": false
        },
        "region": "US",
        "language": "en",
        "title": null,
        "commerce": {
          "is_ad": false,
          "paid_partnership": null,
          "affiliate": null,
          "shop_url": null,
          "anchors": [
            {
              "kind": "54",
              "label": "CapCut · Editing made easy"
            }
          ]
        },
        "people": {
          "mentions": [
            "coldplungeco"
          ],
          "collaborators": []
        },
        "location": null,
        "topics": {
          "keywords": [],
          "genre": null,
          "labels": [
            "Fitness",
            "Health"
          ]
        },
        "chapters": null,
        "ai_generated": false,
        "snapshot": {
          "at": "2026-09-08T09:14:04.219Z",
          "views": 1284000,
          "likes": 143200,
          "comments": 2810,
          "shares": 9040,
          "saves": 21600
        },
        "scores": {
          "outlier": 4.21,
          "outlier_p90": 1.6,
          "percentile": 95,
          "velocity": {
            "views_per_hour": 6698.6,
            "window": "snapshot"
          },
          "reason": null,
          "baseline": {
            "median_views": 305000,
            "p90_views": 802000,
            "engagement_rate": 0.1342,
            "posts_per_week": 4.1,
            "sample": 20,
            "confidence": "high",
            "source": "videos",
            "computed_at": "2026-09-08T09:14:03.902Z",
            "stale": false
          }
        }
      },
      {
        "platform": "tiktok",
        "id": "7300000000000000042",
        "url": "https://www.tiktok.com/@anotherone/video/7300000000000000042",
        "description": "I tried cold plunging before every workout for a week. #coldplunge",
        "posted_at": "2026-09-06T13:04:52.000Z",
        "duration_seconds": 28,
        "thumbnail_url": "https://p16-sign.tiktokcdn.com/obj/tos-cover-7300000000000000042.jpeg",
        "hashtags": [
          "coldplunge",
          "gym"
        ],
        "sound": {
          "id": "7180000000000000099",
          "title": "Winter Air",
          "author": "Northbound",
          "is_original": false
        },
        "creator": {
          "id": "cre_1a77c0b3de",
          "handle": "anotherone",
          "name": "Another One",
          "follower_count": 21400,
          "avatar_url": null,
          "verified": null
        },
        "region": "GB",
        "language": "en",
        "title": null,
        "commerce": {
          "is_ad": false,
          "paid_partnership": null,
          "affiliate": null,
          "shop_url": null,
          "anchors": []
        },
        "people": null,
        "location": null,
        "topics": null,
        "chapters": null,
        "ai_generated": null,
        "snapshot": {
          "at": "2026-09-08T09:14:04.219Z",
          "views": 96200,
          "likes": 8140,
          "comments": 212,
          "shares": 401,
          "saves": 1180
        },
        "scores": null
      }
    ],
    "creators": [
      {
        "platform": "tiktok",
        "id": "cre_9d4b2a7f1c",
        "handle": "someone",
        "name": "Someone",
        "follower_count": 184300,
        "avatar_url": "https://p16-sign.tiktokcdn.com/obj/tos-avatar-someone.jpeg",
        "video_count": 3,
        "best_outlier": 4.21,
        "median_views": 305000,
        "total_views": 1611400,
        "video_ids": [
          "tiktok:7300000000000000000"
        ]
      }
    ],
    "hashtags": [
      {
        "value": "coldplunge",
        "platforms": [
          "instagram",
          "tiktok"
        ],
        "video_count": 34,
        "total_views": 18402000,
        "video_ids": [
          "tiktok:7300000000000000000",
          "instagram:C9xExampleShortcode"
        ]
      }
    ],
    "sounds": [
      {
        "value": "7180000000000000000",
        "title": "original sound - someone",
        "author": "someone",
        "is_original": true,
        "platforms": [
          "tiktok"
        ],
        "video_count": 4,
        "total_views": 2140000,
        "video_ids": [
          "tiktok:7300000000000000000"
        ]
      }
    ],
    "breakdown": {
      "videos_per_creator": 25,
      "creators": [
        {
          "platform": "tiktok",
          "handle": "glowwithmaya",
          "id": "6800000000000000101",
          "videos_read": 25,
          "ended": false
        },
        {
          "platform": "tiktok",
          "handle": "skinbyjo",
          "id": "6800000000000000102",
          "videos_read": 25,
          "ended": false
        }
      ]
    },
    "research": {
      "requested": 50,
      "completed": 50,
      "failed": 0,
      "cached": 6,
      "fresh": 44,
      "max_videos": 50,
      "included_videos": 0
    }
  }
}
```

## Lift against each creator’s median

Each video’s `outlier` is its views over its own creator’s median across the videos this run read, so a small creator’s breakout counts as much as a big one’s. The lift tables are built from those ratios and say so with `lift_tables.basis: creator_median`, and the creators read reports each creator’s `median_views`, the yardstick every lift was computed against.

## Price

9 credits per creator read plus 20 credits per analysed video, fresh or already stored; at most 4,090 credits. There is no flat fee. `estimate=true` quotes the ceiling, which assumes every video is analysed. A creator that cannot be read, an off-intent video and a video whose analysis fails are not charged, and every read below is free.

## Partial and failed

A creator that cannot be read (not found, private, or its source unavailable) is a failed item with its reason, and the run settles `partial` on the rest, charging for what it got. When no creator could be read, or no digest could be written, the run is `failed` and charges nothing. See [Runs](https://www.shortsintel.com/docs/concepts/runs).

## Reading it back

A Creator Breakdown is a research run, so its id is a run id and it reads like a research, under its own paths. Each answers as its [Research](https://www.shortsintel.com/docs/concepts/research) counterpart does:

- `GET /v1/breakdowns/{id}` · Free, forever. Collection is the only thing charged.
- `GET /v1/breakdowns/{id}/videos` · Free, forever, filtered or not. Collection is the only thing charged.
- `GET /v1/breakdowns/{id}/creators` · Free, forever, filtered or not. Collection is the only thing charged.
- `GET /v1/breakdowns/{id}/hashtags` · Free, forever, filtered or not. Collection is the only thing charged.
- `GET /v1/breakdowns/{id}/sounds` · Free, forever, filtered or not. Collection is the only thing charged.
- `GET /v1/breakdowns/{id}/digest` · Free, forever. Collection is the only thing charged.
- `POST /v1/breakdowns/{id}/refresh` · 3 credits per video that comes back.

The research paths still answer for its id; a breakdown path given an intent research’s id answers 404. Every operation is in the [reference](https://www.shortsintel.com/docs/reference/breakdowns).

## From an assistant

Over MCP, `breakdown` runs one and charges, and `get_research` re-reads it for nothing, taking the run id and an aspect. See the [MCP quickstart](https://www.shortsintel.com/docs/mcp).