# Upriver API Docs ## Docs - [Introduction](https://docs.upriver.ai/index): API for real-time context on creators, audiences, brands, trends, and sponsorships - [Creator Engagement Metrics](https://docs.upriver.ai/metrics): How engagement metrics and video metrics are calculated, which platforms they cover, and how to interpret them - [Changelog](https://docs.upriver.ai/changelog): Recent updates to the Upriver API - [Brand Research](https://docs.upriver.ai/api-reference/brands/brand-research): Get brand identity, positioning, and brand language. Preferred input: brand_url (brand website URL). Response is required before calling /v2/audience_insights. - [Product Details](https://docs.upriver.ai/api-reference/products/product-details): Get details for a specific product. Requires product_name and at least one of product_url, brand_url, or brand_name. Provide as much as you have — more context improves results. Use values from the /v1/brand/products response when chaining. - [Products List](https://docs.upriver.ai/api-reference/products/products-list): Get a paginated list of products for a brand. Provide brand_url on every request, including when paging with cursor. Returns a best-effort exhaustive list. Use cursor from the response to request the next page. - [Creator Profile by URL](https://docs.upriver.ai/api-reference/creators/creator-profile-by-url): Lookup a creator profile by social media profile URL. Returns the same payload shape as /v1/creators/{creator_id}; only the lookup key differs. Use `include` for optional enrichments (`engagement_metrics`, `video_metrics`, `relative_metrics`, `bio`, `audience`, `brand_safety`); see Creator Engagement Metrics (/metrics) for guide-level details. - [Batch Creator Details](https://docs.upriver.ai/api-reference/creators/batch-creator-details): Look up 1-10 creators at once by social media profile URL. Body takes a urls array of profile URLs (e.g., urls: ['https://...', ...]). Useful when checking multiple creators from sponsorship results or batch processing. Note: engagement metrics are not available in batch responses. - [Creator Profile by ID](https://docs.upriver.ai/api-reference/creators/creator-profile-by-id): Lookup a creator profile by stable Upriver creator ID. Returns the same payload shape as /v1/creators; only the lookup key differs. Merged IDs return redirect metadata in the response body/header. Use `include` for optional enrichments (`engagement_metrics`, `video_metrics`, `relative_metrics`, `bio`, `audience`, `brand_safety`); see Creator Engagement Metrics (/metrics) for guide-level details. - [Dimensions](https://docs.upriver.ai/api-reference/audience/dimensions): Extract atomic behavioral, motivational, and lifestyle dimensions for a brand's audience. Input: brand_url. Returns granular longtail audience facts useful for programmatic matching. Slower than Personas due to extensive research. In most cases, prefer /v3/audience_insights unless granular dimension-level data is specifically needed. Rate limited to 1 request per minute. - [Personas (v3)](https://docs.upriver.ai/api-reference/audience/personas-v3): Get detailed audience personas for a brand, grounded in real online conversations. Pass brand_url directly — no prior brand/research call needed. Returns personas with purchase triggers, barriers, behaviors, language patterns, and real-world citations. - [Sponsors](https://docs.upriver.ai/api-reference/sponsorships/sponsors): Search for brands that have recently sponsored content in media channels or publications. Filter by content category (e.g., gaming, tech) to find sponsors within a vertical, or by publication_url to find sponsors of a specific creator's channel or newsletter. Provide exactly one scope filter: categories or publication_url. Returns matching brands with an example of their latest sponsorship placement. - [Sponsorships](https://docs.upriver.ai/api-reference/sponsorships/sponsorships): Return individual sponsored placements (content-level rows). Provide at least one of: sponsor_name, brand_id, publication_url, or categories. These can be combined, except publication_url and categories cannot be used together. - [Trends List](https://docs.upriver.ai/api-reference/trends/trends-list): Get the latest trending TikTok video formats and templates — the primary endpoint for trend discovery. Trends are sourced from TikTok but are useful for ideation across platforms (Instagram Reels, YouTube Shorts, etc.). Filter by uses_specific_sound, participation_type, content_structure, has_text_template, include/exclude tags (e.g., exclude_tags=['nsfw']), and duration range. Each trend in the response has an id field — use it as the trend_id path parameter for the trend details, media, and playback endpoints. - [Trend Details](https://docs.upriver.ai/api-reference/trends/trend-details): Get full details for a specific trend by ID, including description, metrics, and metadata. Use after discovering trends via /v2/trends/broad. - [Media Samples](https://docs.upriver.ai/api-reference/trends/media-samples): Get video samples for a trend — returns URLs to example TikTok videos demonstrating the trend. Filter by kind (video, audio) and limit the number of samples. - [Audio Playback](https://docs.upriver.ai/api-reference/trends/audio-playback): Get the top associated audio playback URL for a trend's sound. Use when the user wants the audio/music behind a trend rather than full video samples. - [Similar Trends](https://docs.upriver.ai/api-reference/trends/similar-trends): Find trends similar to a given trend. Use a trend_id from /v2/trends/broad results. Returns up to limit (default 5, max 20) related trends ranked by similarity. - [Traction Graph](https://docs.upriver.ai/api-reference/trends/traction-graph): Get the traction graph for a trend — returns pre-computed estimated traction curves, plus the underlying blended activity curves, for both the full time range and a focused recent window. - [List Breakout Topics](https://docs.upriver.ai/api-reference/breakout-topics/list-breakout-topics): List emerging topics gaining traction in online communities. Filter by vertical — only valid values are: tech, sports, politics. Category filtering is currently only supported for sports in topic mode. Also filter by status (e.g., status=emerging for newly rising topics). Use surface_mode=story to return deduped derived story surfaces instead of raw topics. - [Get Breakout Topics Metadata](https://docs.upriver.ai/api-reference/breakout-topics/get-breakout-topics-metadata): Get available breakout topic filters. Valid verticals are: tech, sports, politics. Category filters are currently only supported for the sports vertical. - [List Narratives](https://docs.upriver.ai/api-reference/breakout-topics/list-narratives): List narrative arcs that group related breakout topics. Ordered by most recently updated. - [Get Narrative](https://docs.upriver.ai/api-reference/breakout-topics/get-narrative): Get a narrative arc with its member breakout topics. - [Search Breakout Topics](https://docs.upriver.ai/api-reference/breakout-topics/search-breakout-topics): Search for specific breakout topics by keyword within a vertical. Use when looking for topics about a particular subject (e.g., search 'AI' within the tech vertical). Uses hybrid search for relevance. - [Find Similar Topics](https://docs.upriver.ai/api-reference/breakout-topics/find-similar-topics): Find topics similar to a given topic by semantic similarity. Use when a user finds an interesting topic and wants to discover adjacent or related emerging topics. - [Get Breakout Topic](https://docs.upriver.ai/api-reference/breakout-topics/get-breakout-topic): Get full details for a single breakout topic by ID, including description, importance score, status, and citations. - [Get Topic Cluster View](https://docs.upriver.ai/api-reference/breakout-topics/get-topic-cluster-view): Get a derived cluster view around a breakout topic. This groups semantically related topics without implying linear order. - [Get Topic Story View](https://docs.upriver.ai/api-reference/breakout-topics/get-topic-story-view): Get the best available derived story surface around a breakout topic. Prefers a strict timeline when available, otherwise falls back to a related topical cluster or the topic itself. - [Get Topic Timeline View](https://docs.upriver.ai/api-reference/breakout-topics/get-topic-timeline-view): Get a derived timeline view around a breakout topic. This only returns multi-topic timeline surfaces when the graph supports a coherent progression. - [Media Categories Search](https://docs.upriver.ai/api-reference/taxonomy/media-categories-search): Find the most relevant categories from the taxonomy for a given freeform text (e.g., { "text": "gaming and esports" }). Useful for discovering valid category values to pass as filters to the sponsors, sponsorships, and breakout topics endpoints. Returns ordered category matches with confidence scores. - [Media Categories](https://docs.upriver.ai/api-reference/taxonomy/media-categories): Returns the media categories split into L1 (top-level) and L2 (second-level) lists. These categories can be used as a filter for sponsors, sponsorships, and other endpoints. ## Optional - [Upriver Website](https://upriver.ai)