Tool

Find standout posts

Use to find posts that beat their own creator's usual views at least twice. The outlier score is views / the creator's baseline, the median views of their latest 10 unpinned posts at least a day old. Searches up to 10 named creators when creators is given, the creators this workspace tracks with scope competitors, and otherwise every post Cuekoo has stored, there only from creators whose usual post reaches 1,000 views. Named or tracked creators Cuekoo has not stored, or without enough posts for a baseline, come back in skipped. Returns 10 posts per page with a next_cursor. API, MCP and Koo cost 1 credit per non-empty page; empty pages and direct web browsing are free.

POSTtools.read1 credit per non-empty API/MCP results page

POST/openapi/v1/tools/list_outliers

Call it

curl -X POST https://api.cuekoo.com/openapi/v1/tools/list_outliers \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

The MCP tool is named cuekoo_list_outliers. Arguments and results are identical to the REST call.

Arguments

Send a JSON object with these fields. Scope: tools.read.

Name	Type	Required	Description
`content_types`	`string[] \| null`	Optional	Only these formats: video, slideshow (photo posts and carousels)
`creators`	`object[] \| null`	Optional	Up to 10 creators to search; naming creators without a scope searches them; not allowed with scope all or competitors
`creators[].handle`	`string`	Required	The creator's handle, with or without the leading @
`creators[].platform`	`string`	Required	The creator's platform: tiktok, instagram or youtube
`cursor`	`string`	Optional	next_cursor from the previous page, to continue the same search
`hashtags`	`string[] \| null`	Optional	Up to 10 hashtags, with or without #. A post carrying any of them matches
`keyword`	`string`	Optional	Only posts whose caption contains this text or that carry it as a hashtag; up to 100 characters
`languages`	`string[] \| null`	Optional	ISO 639-1 language codes; posts in other languages are left out, posts with no detectable language are kept. Default: ["en"], or every language when creators are named; pass [] for every language
`limit`	`integer \| null`	Optional	Posts per page, 1 to 10. Default: 10
`max_followers`	`integer \| null`	Optional	Only creators with at most this many followers
`max_outlier_score`	`number \| null`	Optional	Only posts with at most this outlier score, to leave out freak multiples on tiny baselines
`max_views`	`integer \| null`	Optional	Only posts with at most this many views
`min_followers`	`integer \| null`	Optional	Only creators with at least this many followers
`min_outlier_score`	`number \| null`	Optional	Only posts with at least this outlier score, views / the creator's usual views; at least 2. Default: 2, the outlier threshold
`min_views`	`integer \| null`	Optional	Only posts with at least this many views
`niches`	`string[] \| null`	Optional	Up to 5 niche slugs from Cuekoo's taxonomy, level 1 or level 2 (for example beauty or skincare). A post matches when it is labeled with any of them; combined with hashtags, a post matching either is kept
`one_per_creator`	`boolean`	Optional	Return only each creator's best post under the sort, so one prolific creator does not fill the page
`platforms`	`string[] \| null`	Optional	Only these platforms: tiktok, instagram, youtube. Default: all three
`published_within_days`	`integer`	Optional	Only posts published in the last 7, 30 or 90 days. Default: 30
`regions`	`string[] \| null`	Optional	ISO 3166-1 alpha-2 region codes of the creator's account registration (not the audience). Default: no region filter
`scope`	`string`	Optional	Whose posts to search: all (every post Cuekoo has stored), competitors (the creators this workspace tracks) or creators (the creators listed in creators)
`sort`	`string`	Optional	Order, highest first: outlier_score, views or published_at. Default: outlier_score

Response

Name	Type	Required
`items`	`object[] \| null`	Required
`items[].ai_labeled`	`boolean`	Required
`items[].baseline`	`object \| null`	Required
`items[].baseline.captured_at`	`string`	Required
`items[].baseline.samples`	`integer`	Required
`items[].baseline.views`	`integer`	Required
`items[].creator`	`object`	Required
`items[].creator.display_name`	`string`	Required
`items[].creator.followers`	`integer`	Required
`items[].creator.handle`	`string`	Required
`items[].creator.language`	`string \| null`	Required
`items[].creator.platform`	`string`	Required
`items[].creator.region`	`string \| null`	Required
`items[].engagement_rate`	`number \| null`	Required
`items[].language`	`string \| null`	Required
`items[].metrics`	`object`	Required
`items[].metrics.comments`	`integer \| null`	Required
`items[].metrics.latest_captured_at`	`string \| null`	Required
`items[].metrics.likes`	`integer \| null`	Required
`items[].metrics.saves`	`integer \| null`	Required
`items[].metrics.shares`	`integer \| null`	Required
`items[].metrics.views`	`integer \| null`	Required
`items[].niche`	`object \| null`	Required
`items[].niche.l1`	`string`	Required
`items[].niche.l2`	`string[] \| null`	Required
`items[].outlier_score`	`number \| null`	Required
`items[].post`	`object`	Required
`items[].post.caption`	`string`	Required
`items[].post.content_type`	`string`	Required
`items[].post.duration_seconds`	`integer \| null`	Required
`items[].post.id`	`string`	Required
`items[].post.platform`	`string`	Required
`items[].post.platform_post_id`	`string`	Required
`items[].post.published_at`	`string`	Required
`items[].post.thumbnail_url`	`string`	Required
`items[].post.url`	`string`	Required
`items[].region`	`string \| null`	Required
`items[].virality_score`	`number \| null`	Required
`next_cursor`	`string`	Optional
`skipped`	`object[] \| null`	Required
`skipped[].handle`	`string`	Required
`skipped[].platform`	`string`	Required
`skipped[].reason`	`string`	Required

A call returns the Tool's output object at HTTP 200. Failures use the error envelope.

Credits

1 credit per non-empty API/MCP results page

How credits work