Content Research

Find trending videos in your niche with engagement metrics, view velocity, and competition data.

POST /api/v1/research/content

Search for trending videos matching given keywords. Returns detailed video metrics including view velocity, engagement rates, and tags. When no keywords are provided, Soke automatically uses keywords extracted from your connected YouTube channel.

Credits: 2 per request

Authentication

X-Soke-Key: sk_live_your_api_key

Authorization: Bearer your_jwt_token

Request Body

Field	Type	Required	Default	Description
`keywords`	string[]	No	—	Keywords to search for. Omit to use your connected channel's keywords. Max 10, each up to 100 characters.
`platform`	string	No	`"youtube"`	Target platform
`region`	string	No	`"US"`	Region code for localized results
`maxResults`	integer	No	`20`	Maximum videos to return (1–50)
`recencyDays`	integer	No	`365`	Only return videos published within this many days. Range: 1–3650.

When keywords is omitted or empty, Soke automatically extracts keywords from your connected YouTube channel's top-performing videos and uses the top 5. Channel keywords are cached for 6 hours for fast responses. If no channel is connected and no keywords are provided, the endpoint returns a KEYWORDS_REQUIRED error.

Results are filtered to the last 12 months by default so you see what's working now, not old viral content. Pass recencyDays to widen or narrow the window (e.g., 30 for the last month, 730 for the last two years).

Example Requests

With keywords

curl -X POST https://api.usesoke.ai/api/v1/research/content \
  -H "Content-Type: application/json" \
  -H "X-Soke-Key: sk_live_your_api_key" \
  -d '{
    "keywords": ["stoicism", "philosophy"],
    "platform": "youtube",
    "recencyDays": 90
  }'

Without keywords (channel auto-detect)

curl -X POST https://api.usesoke.ai/api/v1/research/content \
  -H "Content-Type: application/json" \
  -H "X-Soke-Key: sk_live_your_api_key" \
  -d '{}'

Response

200 OK

{
  "success": true,
  "data": {
    "keywords": ["stoicism", "philosophy"],
    "videos": [
      {
        "videoId": "EFkyxzJtiv4",
        "title": "Stoicism: Become Undefeatable",
        "description": "Follow Aperture on Spotify and take these thoughts with you...",
        "channelId": "UCO5QSoES5yn2Dw7YixDYT5Q",
        "channelTitle": "Aperture",
        "thumbnailUrl": "https://i.ytimg.com/vi/EFkyxzJtiv4/mqdefault.jpg",
        "publishedAt": "2025-11-15T18:30:00Z",
        "duration": "PT12M52S",
        "viewCount": 13183781,
        "likeCount": 645609,
        "commentCount": 9229,
        "tags": ["stoicism", "stoic", "stoicism philosophy", "practical stoicism"],
        "viewVelocity": 7373.1,
        "engagementRate": 4.97
      }
    ],
    "totalResults": 40,
    "dataSources": "YouTube Data API v3"
  },
  "meta": {
    "platform": "youtube",
    "request_id": "550e8400-e29b-41d4-a716-446655440000",
    "processing_time_ms": 2400
  }
}

Response Fields

Field	Type	Description
`keywords`	string[]	The keywords used for the search (may be auto-detected from channel)
`videos`	array	Videos sorted by view count (descending)
`videos[].videoId`	string	YouTube video ID
`videos[].title`	string	Video title
`videos[].description`	string	Truncated description (max 300 characters)
`videos[].channelId`	string	YouTube channel ID
`videos[].channelTitle`	string	Channel name
`videos[].thumbnailUrl`	string \| null	Thumbnail image URL
`videos[].publishedAt`	string	ISO 8601 publish date
`videos[].duration`	string \| null	ISO 8601 duration (e.g., `PT12M52S`)
`videos[].viewCount`	integer	Total view count
`videos[].likeCount`	integer	Total like count
`videos[].commentCount`	integer	Total comment count
`videos[].tags`	string[]	Video tags (up to 15)
`videos[].viewVelocity`	number	Average views per day since publish
`videos[].engagementRate`	number	(likes + comments) / views × 100
`totalResults`	integer	Total unique videos found across all keywords
`dataSources`	string	Data sources used

Error Codes

Code	Status	Description
`KEYWORDS_REQUIRED`	400	No keywords provided and no YouTube channel connected
`BAD_REQUEST`	400	Invalid parameters (e.g., too many keywords, keyword too long)
`RATE_LIMIT_EXCEEDED`	429	Rate limit exceeded
`INSUFFICIENT_CREDITS`	402	Not enough credits
`PLATFORM_NOT_IMPLEMENTED`	501	Platform not yet supported

On this page