> ## Documentation Index
> Fetch the complete documentation index at: https://docs.upriver.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Changelog

> Recent updates to the Upriver API

# Changelog

Stay up to date with the latest changes to the Upriver API.

***

## July 2026

<Update label="July 4, 2026" tags={["Improvement"]}>
  ### Trends API: Legacy `sort_by` Values Resolve to Current Sorts

  `/v2/trends/broad` accepts the legacy `sort_by` values `timeliness` and `momentum` and resolves them to their closest current equivalents: `newest` and `rising` respectively. The documented sort modes are `recommended`, `newest`, and `rising`; see the [Sorting & Ranking guide](/trends/sorting) for what each mode is for, the full legacy-value table, and how to build freshness badges from `freshness_score` and `timeliness_status`.
</Update>

## June 2026

<Update label="June 27, 2026" tags={["New Feature"]}>
  ### Creator API: MCP Tools for Creator Search and Discovery

  Two new MCP tools are now available at `mcp.upriver.ai`: `creator_search` finds creators by name, handle, content description, platform, category, or follower tier; `creator_get` returns a full creator profile by Upriver creator ID or channel URL, with optional enrichments (`bio`, `audience`, `brand_safety`).
</Update>

<Update label="June 27, 2026" tags={["New Feature"]}>
  ### Sponsors API: `monetization_type`, `disclosure_tier`, and `is_first_party` Fields

  `/v1/sponsors` and `/v1/sponsorships` responses now include three new optional fields: `monetization_type` (`paid_partnership`, `affiliate`, `gifted`, `unknown`), `disclosure_tier` (confidence level of the disclosure signal), and `is_first_party`. Currently populated for Instagram sponsorships; YouTube placements return `null` for these fields.
</Update>

<Update label="June 26, 2026" tags={["New Feature"]}>
  ### Breakout Topics: Entity `event` Filter

  `GET /v1/entities/breakout` now accepts an `event` query parameter to narrow results to entities breaking out in a specific competition — pass a freeform name like `"world cup"` or slug `world_cup` to filter entities linked to that event. Composes with existing `tag` and `temporal_status` filters.
</Update>

<Update label="June 26, 2026" tags={["Improvement"]}>
  ### Breakout Topics: Entity List No Longer Includes Per-Topic Citations

  Per-topic `citations` and `citation_rate` fields on `GET /v1/entities/breakout` list responses are now empty — both load on demand from `GET /v1/entities/{entity_id}/breakout`. Callers relying on citations in the list response should switch to the detail endpoint.
</Update>

<Update label="June 26, 2026" tags={["Bug Fix"]}>
  ### Categories API: Search No Longer Returns Invalid Category IDs

  Fixed `/v1/categories/search` returning category IDs outside the known taxonomy, which caused downstream errors when those IDs were passed to other endpoints.
</Update>

<Update label="June 26, 2026" tags={["Bug Fix"]}>
  ### Breakout Topics: `temporal_status=upcoming` Returning HTTP 500

  Fixed `temporal_status=upcoming` on `/v1/topics/breakout` and `/v1/entities/breakout` returning HTTP 500.
</Update>

<Update label="June 24, 2026" tags={["New Feature"]}>
  ### Breakout Topics: Event `temporal_status` Field and Filter

  Topics linked to scheduled events now include a `temporal_status` field (`upcoming`, `ongoing`, `past`). Pass `temporal_status` as a filter on `/v1/topics/breakout` and `/v1/entities/breakout` to focus results on active or upcoming event-linked topics; the `breakout_list_topics` and `breakout_search_topics` MCP tools expose the same filter.
</Update>

<Update label="June 22, 2026" tags={["Improvement"]}>
  ### Breakout Topics: Expanded Sort Options

  `/v1/topics/breakout` now accepts `sort_by=recommended` (default), `rising` (fastest-gaining), `top` (highest volume), and `newest` (most recently discovered); `importance` is accepted as an alias for `top`. The same vocabulary is available on `/v1/entities/breakout` with an additional `emerging` sort for forward-looking signals.
</Update>

<Update label="June 22, 2026" tags={["New Feature"]}>
  ### Breakout Topics: `discovered_within_hours` Filter

  `/v1/topics/breakout` and `/v1/entities/breakout` now accept `discovered_within_hours` to limit results to topics or entities first seen within the last N hours — useful for surfacing only the freshest signals regardless of sort order.
</Update>

<Update label="June 22, 2026" tags={["Improvement"]}>
  ### Trends API: `rising` Sort Alias

  `/v2/trends/broad` now accepts `sort_by=rising` as an alias for `momentum`, aligning sort vocabulary with the Breakout Topics API.
</Update>

<Update label="June 21, 2026" tags={["Improvement"]}>
  ### Creator API: `limit` Parameter and Default Change

  `/v1/creators/search` now accepts a `limit` parameter (1–50). The default has changed from 20 to 10 — update any calls that relied on the previous default.
</Update>

<Update label="June 19, 2026" tags={["New Feature"]}>
  ### Creator API: Natural-Language Content Search

  `/v1/creators/search` now accepts `content_query` for semantic discovery — describe what a creator makes (e.g. `"outdoor cooking tutorials"`) and the API returns the closest matching creators, ranked by content relevance.
</Update>

<Update label="June 18, 2026" tags={["New Feature"]}>
  ### Breakout Topics: Entity Breakout API

  `GET /v1/entities/breakout` surfaces players, teams, and other named entities generating emerging coverage, with sort options including `recommended`, `recent`, `rising`, `emerging`, and `newest`. `GET /v1/entities/breakout/tags` returns active entity tag facets (sport, league, country) for filter discovery. `GET /v1/entities/{entity_id}/breakout` returns topics mentioning a specific entity.
</Update>

<Update label="June 18, 2026" tags={["New Feature"]}>
  ### Creator API: `include=email` and `has_email` Filter

  Creator endpoints now support `include=email` to return a publicly available email address. Use `has_email=true` on `/v1/creators/search` to restrict results to creators with known contact emails.
</Update>

<Update label="June 15, 2026" tags={["Bug Fix"]}>
  ### Products API: Garbled Product Descriptions

  Fixed product descriptions containing raw HTML character references (e.g., `&#x20;`, `&#x28;`) returned by certain e-commerce sites — affected descriptions now decode to readable text.
</Update>

<Update label="June 13, 2026" tags={["New Feature"]}>
  ### Products API: Product Images and `include` Parameter

  `/v1/brand/products` now accepts an `include` parameter (`"description"`, `"image_url"`) to declare what each product entry should contain. Pass `include=["image_url"]` to receive a product image URL when one is available; omitting `include` returns descriptions only. Fields not requested are omitted from responses rather than returned as `null`.
</Update>

<Update label="June 13, 2026" tags={["Bug Fix"]}>
  ### Creator API: Non-ASCII YouTube Handle Lookup

  Fixed creator lookups for YouTube handles that contain non-ASCII characters (e.g., accented letters like `é`) — handles were being silently truncated at the first non-ASCII character, causing lookups to fail or return the wrong creator.
</Update>

<Update label="June 11, 2026" tags={["New Feature"]}>
  ### Breakout Topics: Citation Source Filter

  `/v1/topics/breakout` (list and search) now accepts `citation_sources` to restrict returned citations to specific source categories: `news`, `reddit`, and `twitter`. Useful for surfacing only journalistic sources or platform-specific discussion when the default mix isn't what you need. The filter is also available on the MCP `breakout_list_topics` and `breakout_search_topics` tools.
</Update>

<Update label="June 10, 2026" tags={["New Feature"]}>
  ### Breakout Topics: MCP Server

  The Breakout Topics API is now accessible via the Model Context Protocol at `mcp.upriver.ai`, enabling AI agents (Claude, ChatGPT, Cursor, and others) to discover emerging topics natively. Available tools are `breakout_search_topics` and `breakout_list_topics`.
</Update>

<Update label="June 6, 2026" tags={["Bug Fix"]}>
  ### Trends API: Momentum Sort Pagination

  Fixed pagination for `sort_by=momentum` — page 2 and beyond could return duplicate or permanently-skipped trends. Existing momentum pagination cursors are invalidated; restart pagination from the beginning to get consistent results.
</Update>

<Update label="June 4, 2026" tags={["New Feature"]}>
  ### Sponsors API: Instagram Sponsorships

  Instagram sponsorship data is now available via `/v1/sponsors` and `/v1/sponsorships`. Native paid-partnership labels from Instagram posts are detected and resolved to brands, expanding coverage alongside existing YouTube and podcast sponsorships.
</Update>

<Update label="June 4, 2026" tags={["Improvement"]}>
  ### Creator API: `name_or_handle` for Creator Search

  `/v1/creators/search` now accepts `name_or_handle` to resolve a creator by handle or display name — exact, prefix, and fuzzy substring matches are supported (e.g. `"beast"` finds `"MrBeast"`). The previous `query` and `creator_name` parameters are accepted as deprecated aliases for `name_or_handle` and will be removed in a future release.
</Update>

<Update label="June 4, 2026" tags={["New Feature"]}>
  ### Creator API: Audience Country Filter

  `/v1/creators/search` now accepts `audience_country` (one or more ISO 3166-1 alpha-2 codes) to filter by where a creator's measured audience is located. `creator_country` also now accepts multiple codes in a single request for multi-country queries.
</Update>

<Update label="June 3, 2026" tags={["Improvement"]}>
  ### Breakout Topics: Parameter Validation

  The breakout list endpoint now returns HTTP 400 for unknown `vertical` values (with a pointer to `GET /v1/topics/breakout/metadata`) and unknown `status` values instead of silently returning empty results or HTTP 500. `status=archived` has been removed — archived topics are never surfaced; use `emerging`, `active`, or `resolved`. The `include` parameter now validates against its allowed values (`citations`, `entities`).
</Update>

<Update label="June 2, 2026" tags={["Bug Fix"]}>
  ### Creator API: Text Search Reliability

  Fixed `query` and `creator_name` searches on `POST /v1/creators/search` returning HTTP 500. URL-based lookups and filter-only browse were not affected.
</Update>

<Update label="June 1, 2026" tags={["Bug Fix"]}>
  ### Creator API: Search Pagination Reliability

  Fixed pagination in `/v1/creators/search` so that browsing by category or follower tier reliably returns every page of results.
</Update>

***

## May 2026

<Update label="May 31, 2026" tags={["Improvement"]}>
  ### Creator API: Improved Country Matching and Coverage

  Filtering creator search by country (`creator_country`) is now more accurate and covers more creators.
</Update>

<Update label="May 27, 2026" tags={["New Feature"]}>
  ### Trends API: New `newest` and `momentum` Sort Options

  `/v2/trends/broad` now accepts two more values for `sort_by`: `newest` orders trends by when they were first confirmed as real, and `momentum` surfaces trends with accelerating activity, comparing recent video volume to the prior period.
</Update>

<Update label="May 18, 2026" tags={["Improvement"]}>
  ### Trends API: `emerged_at` Field

  `/v2/trends/broad` list and detail responses now include `emerged_at`, the timestamp when a trend first gathered enough activity to be considered emerging. This is the signal behind the `emerging` sort, so you can explain why one trend outranks another.
</Update>

<Update label="May 5, 2026" tags={["Improvement"]}>
  ### Trends API: Commercial Music Approval Flag

  Trend list and detail responses now include `commercial_music_approved`, indicating whether a sound has been explicitly cleared for commercial and business use. This pairs with the existing `commercial_music_status=approved` filter.
</Update>

<Update label="May 1, 2026" tags={["New Feature"]}>
  ### Creator API: Creator Search — Pagination, Follower Bucket, and Category Filters

  `/v1/creators/search` is now available. Use `follower_bucket` parameter (e.g. `10k_50k`, `100k_500k`) to browse creators by follower tier; and a free-text `categories` field automatically resolves search terms to category filters.
</Update>

***

## April 2026

<Update label="April 29, 2026" tags={["New Feature"]}>
  ### Creator API: Associated Creator Relationships

  Creator responses now include an `associated_creators` array. Each entry contains a stable `creator_id` and a `creator_role` (`surface`, `primary_creator`, `group`, `member`, or `peer`) describing how the creators are related across the platform.
</Update>

<Update label="April 29, 2026" tags={["New Feature"]}>
  ### Trends API: Commercial Music Filter

  `POST /v2/trends/broad` now accepts `commercial_music_status=approved` to limit results to sound trends explicitly cleared for commercial and business use.
</Update>

<Update label="April 27, 2026" tags={["Bug Fix"]}>
  ### Trends API: Duplicate Trend Deduplication

  Fixed same-sound trends appearing as multiple distinct entries in `/v2/trends/broad`; same-sound rows are now correctly merged before results are published. AI-effect trend families are also better consolidated, reducing near-duplicate trend entries.
</Update>

<Update label="April 24, 2026" tags={["Bug Fix"]}>
  ### Creator API: Relative Metrics Category Accuracy

  Fixed `include=relative_metrics` benchmarking a creator's channel against the wrong category cohort on warm cache hits.
</Update>

<Update label="April 22, 2026" tags={["Bug Fix"]}>
  ### Sponsors API: Publication Category Labels

  Fixed `publication_categories` returning empty in `/v1/sponsors` and `/v1/sponsorships` responses even when category data was present.
</Update>

<Update label="April 22, 2026" tags={["Bug Fix"]}>
  ### Creator API: Enrichment Key Presence

  Restored the key-presence contract for `bio`, `audience`, and `brand_safety` — these keys are now absent (rather than present with null values) when enrichment is unavailable for small-follower creators.
</Update>

<Update label="April 18, 2026" tags={["Improvement"]}>
  ### Trends API: `emerging` Sort Replaces `newest`

  `/v2/trends/broad` now accepts `sort_by=emerging` in place of the previously introduced `sort_by=newest`. The `emerging` sort surfaces trends at the moment they cross from noise to signal — ranked by when they first accumulated enough confirmed video evidence to look like a real trend. Update any calls using `sort_by=newest` to use `sort_by=emerging`; existing pagination cursors from `newest` results are also invalidated.
</Update>

<Update label="April 17, 2026" tags={["New Feature"]}>
  ### Creator API: Enrichment Coverage Status

  The `bio`, `audience`, and `brand_safety` enrichment blocks now include a `status` field (`full_coverage`, `limited_coverage`, `no_coverage`) indicating how much evidence backed the result — helping callers distinguish confident findings from inconclusive ones.
</Update>

<Update label="April 16, 2026" tags={["Improvement"]}>
  ### Brand API: `/v1/brand` Endpoint Removed

  The deprecated `/v1/brand` endpoint has been removed. Use `/v1/brand/research` instead.
</Update>

<Update label="April 15, 2026" tags={["Improvement"]}>
  ### Sponsors API: Expanded Default Sponsor Types

  `/v1/sponsors`, `/v1/sponsors/search`, and `/v1/sponsorships` now include `implicit_ad` and `affiliate` in the default `sponsor_types` set. Previously, only `explicit_ad`, `promotion`, and `unknown` were returned when the parameter was omitted. Pass `sponsor_types` explicitly to restrict results to specific types.
</Update>

<Update label="April 14, 2026" tags={["New Feature"]}>
  ### Trends API: `newest` Sort for Broad Trends

  `/v2/trends/broad` now accepts `sort_by=newest` to surface trends most recently activated in the API, ranked by latest published video activity.
</Update>

<Update label="April 14, 2026" tags={["Improvement"]}>
  ### Sponsorships API: Scope Filter Now Required

  `/v1/sponsorships` (GET and POST) now requires at least one of `sponsor_name`, `brand_id`, `publication_url`, or `categories`. Requests with no scope filters now return HTTP 400.
</Update>

<Update label="April 13, 2026" tags={["Improvement"]}>
  ### Products API: `brand_url` Required on All Requests

  `brand_url` is now required on all `/v1/brand/products` requests, including pagination requests that supply a `cursor`. Previously, `brand_url` could be omitted when paginating.
</Update>

<Update label="April 12, 2026" tags={["Bug Fix"]}>
  ### Creator API: Engagement Metrics Reliability

  Improved reliability of engagement metrics for creator profiles.
</Update>

<Update label="April 11, 2026" tags={["Improvement"]}>
  ### Trends API: Singular Tag Parameter Aliases

  `/v2/trends/broad` now accepts `tag` and `exclude_tag` as aliases for the `tags` and `exclude_tags` parameters, and accepts a bare string in addition to an array for both fields.
</Update>

<Update label="April 11, 2026" tags={["New Feature"]}>
  ### Creator API: General Keyword Search

  `/v1/creators/search` now accepts a `query` parameter for name and keyword-based creator discovery — no URL required. Supports filtering by `platforms`, `category_ids`, follower range, `creator_country`, and `creator_language`. Results include `score` and `match_signals` ranking metadata.
</Update>

<Update label="April 11, 2026" tags={["New Feature"]}>
  ### Products API: App Store Support

  `/v1/brand/products` now supports Apple App Store and Google Play URLs, returning a structured product entry with the app's name, description, price, and developer without requiring a full brand search.
</Update>

<Update label="April 11, 2026" tags={["Improvement"]}>
  ### Products API: Input Validation and `brand_name` Deprecation

  The `brand_name` parameter on `/v1/brand/products` is deprecated — brand name is now always resolved automatically from the URL for better accuracy. Marketplace, social media, and other non-brand URLs now return HTTP 400 immediately.
</Update>

<Update label="April 9, 2026" tags={["New Feature"]}>
  ### Trends API: `sort_by` Parameter for Broad Trends

  `/v2/trends/broad` now accepts a `sort_by` parameter: `recommended` (default, ranked by relevance and engagement) and `timeliness` to prioritize freshest currently-rising trends. The alias `freshness` is also accepted.
</Update>

<Update label="April 8, 2026" tags={["New Feature"]}>
  ### Audience Insights: `purchase_motivations` Field

  `/v3/audience_insights` persona segments now include a `purchase_motivations` field — the enduring outcomes, problems solved, and identity payoffs that drive the segment's interest in the product category. This complements the existing `purchase_triggers` and `purchase_barriers` fields.
</Update>

<Update label="April 8, 2026" tags={["New Feature"]}>
  ### Sponsors API: Date Filtering

  `/v1/sponsors` and `/v1/sponsors/search` now accept `days_back` (1–365, default 90), `since` (YYYY-MM-DD), and `until` (YYYY-MM-DD) parameters for filtering by sponsorship date range, matching the existing parameters on the sponsorships endpoints.
</Update>

<Update label="April 8, 2026" tags={["Improvement"]}>
  ### Sponsors API: `industries` Parameter Removed

  The deprecated `industries` filter has been removed from `/v1/sponsors` and `/v1/sponsors/search`. Use `categories` instead.
</Update>

<Update label="April 7, 2026" tags={["New Feature"]}>
  ### Products API: Configurable Result Limit

  `/v1/brand/products` now accepts a `limit` parameter (5–20, default 10) to control how many products are returned per request. Per-result credit pricing is now active at 1.2 credits per product with a 5-credit minimum per request.
</Update>

<Update label="April 5, 2026" tags={["New Feature"]}>
  ### Usage API: Custom Date Range

  `GET /v1/usage` now accepts optional `start_date` and `end_date` query parameters (YYYY-MM-DD) to retrieve usage data for a specific date range.
</Update>

***

## March 2026

<Update label="March 29, 2026" tags={["Improvement"]}>
  ### Audience Insights: v3 Grounded Segments

  `/v3/audience_insights` now returns two new fields per segment — `communities` (online spaces where the segment gathers) and `buying_mindset` (plain observations about purchasing behavior) — replacing the earlier fictional persona format with grounded audience intelligence. The `personality_traits` field is deprecated and now returns an empty array.
</Update>

<Update label="March 26, 2026" tags={["New Feature"]}>
  ### Sponsors API: `newsletter` Platform Alias

  The `platforms` filter on `/v1/sponsors/search` and `/v1/sponsorships/search` now accepts `"newsletter"` as a convenience alias, automatically expanding to Substack, Beehiiv, and Ghost publications.
</Update>

<Update label="March 23, 2026" tags={["Improvement"]}>
  ### API: Authenticated Rate Limit Increase

  Authenticated API requests are now rate-limited at 2,000 requests per 5 minutes, up from 300.
</Update>

<Update label="March 23, 2026" tags={["Improvement"]}>
  ### Audience Insights: v2 Endpoint Deprecated

  `/v2/audience_insights` is now deprecated; use `/v3/audience_insights` instead.
</Update>

<Update label="March 22, 2026" tags={["Improvement"]}>
  ### Products API: Simplified Input Contract

  `/v1/brand/products` now requires `brand_url` and returns `brand_name` in responses; the `auto` free-text input has been removed from both `/v1/brand/products` and `/v1/brand/research`. The legacy `/v1/product` endpoint has been removed.
</Update>

<Update label="March 20, 2026" tags={["New Feature"]}>
  ### Creator API: Relative Engagement Benchmarks

  Creator endpoints now support `include=relative_metrics` to see how a creator's engagement compares to peers in the same category and follower bucket. Returns per-channel engagement benchmarks with a `band` of `bottom_25`, `mid_50`, or `top_25`, along with the cohort details used for the comparison.
</Update>

<Update label="March 20, 2026" tags={["Improvement"]}>
  ### Creator API: `channel_relationship` Field

  The `channels[].relationship_type` field has been replaced by `channels[].channel_relationship` with clearer semantics. Primary channels are omitted (no field); secondary channels are now `"attached"` (a distinct show, brand, or project surface) or `"group"` (a shared or collab surface). The old `relationship_type` values (`owner`, `shared_owner`, `member_of_group`) are no longer returned.
</Update>

<Update label="March 20, 2026" tags={["New Feature"]}>
  ### Sponsors API: `sort_by` Parameter

  `POST /v1/sponsors/search` now accepts a `sort_by` parameter. The default `total_ads` ranks brands by most placements; `recent` ranks by most recent ad date instead.
</Update>

<Update label="March 18, 2026" tags={["Improvement"]}>
  ### Usage API: Clarified Credit Fields

  The `UsageByFeature` object in usage responses has been updated for clarity: `credit_cost` is renamed to `credit_rate` (the per-result credit multiplier), `usage` is renamed to `quantity` (the raw count of items delivered), and a new `credits_used` field is added showing the total credits charged (`quantity × credit_rate`).
</Update>

<Update label="March 14, 2026" tags={["New Feature"]}>
  ### Creator API: Stable Creator ID Redirects

  When a stored creator ID has been merged into another creator, `GET /v1/creators/{creator_id}` now returns HTTP 200 with the canonical creator, a `redirect` object in the body (`requested_creator_id`, `canonical_creator_id`, `reason`), and an `X-Creator-Redirect` response header — clients should update any stored ID to `redirect.canonical_creator_id`. Stable creator IDs are also now returned in `/v1/creators/search` results when `include=creator_id` is specified.
</Update>

<Update label="March 13, 2026" tags={["New Feature"]}>
  ### Trends API: `content_structure` Field and Filter

  Trend responses now include a `content_structure` field indicating the shared non-audio pattern across videos: `none` (sound-led only), `loose` (shared theme or aesthetic without a repeatable template), or `structured` (repeatable text, editing, or visual template). The trends list endpoint now accepts `content_structure` as a filter parameter.
</Update>

<Update label="March 13, 2026" tags={["Improvement"]}>
  ### Creator API: Comma-Separated `include` Values

  Creator endpoints now accept comma-separated `include` values (e.g., `include=engagement_metrics,bio`) in addition to repeated query parameters.
</Update>

<Update label="March 12, 2026" tags={["Bug Fix"]}>
  ### Creator API: Batch Endpoint Cross-Platform Coverage

  Fixed `/v1/creators/batch` returning incomplete single-platform profiles when the stored record was sparse — batch lookups now fall through to live research and return complete cross-platform profiles, matching single-creator lookup behavior. Labels are also now returned correctly on cached batch hits.
</Update>

<Update label="March 12, 2026" tags={["Improvement"]}>
  ### Sponsors API: `brand_name` Hint for Brand-URL Search

  `POST /v1/sponsors/search` now accepts an optional `brand_name` field alongside `brand_url`. Supplying the brand name improves category classification accuracy when discovering sponsors by URL.
</Update>

<Update label="March 11, 2026" tags={["Improvement"]}>
  ### Creator API: Video Inventory Metrics

  `include=video_metrics` now derives upload frequency from a dedicated trailing 12-week inventory window instead of the recent engagement sample. Responses include new `lookback_weeks`, `weeks_observed`, and `window_complete` fields.
</Update>

<Update label="March 9, 2026" tags={["Bug Fix"]}>
  ### Breakout Topics: Search Result Fields

  Fixed `relevance_score` and `computed_status` returning null or stale values in search results — both now reflect live scoring consistent with the list endpoint.
</Update>

<Update label="March 6, 2026" tags={["Improvement"]}>
  ### Creator API: By-ID Endpoint Include Parity

  `GET /v1/creators/{creator_id}` now supports all `include` values (`engagement_metrics`, `video_metrics`, `bio`, `audience`, `brand_safety`), matching `GET /v1/creators?url=`. Requests with invalid URLs now return HTTP 400 immediately instead of timing out.
</Update>

<Update label="March 6, 2026" tags={["New Feature"]}>
  ### Trends API: `uses_specific_sound` Field

  Trend responses now include a `uses_specific_sound` boolean indicating whether a trend requires a specific audio clip, making it easier to filter by creative flexibility.
</Update>

<Update label="March 6, 2026" tags={["Bug Fix"]}>
  ### Trends API: Complete Video Sample Metadata

  Fixed the trend detail endpoint stripping `published_at` and `duration_seconds` from `video_samples`. Both fields are now returned correctly.
</Update>

<Update label="March 6, 2026" tags={["New Feature"]}>
  ### Breakout Topics: Citation Rate

  Topic detail responses now include a `citation_rate` field — a daily breakdown of citation counts for charting topic momentum over time.
</Update>

<Update label="March 5, 2026" tags={["New Feature"]}>
  ### Breakout Topics: Narratives

  Breakout topics can now be grouped into narratives — storylines that connect related topics across angles and time.
</Update>

<Update label="March 1, 2026" tags={["New Feature"]}>
  ### Trends API: New Filters

  Added three new filter parameters: `timeliness_status` to control trend freshness (`recent`, `active`, `stale`), `brand_safety` for brand suitability filtering, and `topic_scope` to filter by how transferable a trend is (`universal`, `niche`, `event_specific`, `person_specific`).
</Update>

<Update label="March 1, 2026" tags={["Improvement"]}>
  ### Trends API: Updated Response Fields

  `content_format` has been replaced by `participation_type` (`open`, `timed`, `lip_sync`, `choreography`) with new `topic_scope` and `content_scenarios` response fields. Fields `origin`, `virality_reason`, `brand_categories`, and `audience_vibes` have been removed from trend responses.
</Update>

***

## February 2026

<Update label="February 28, 2026" tags={["Improvement"]}>
  ### Creator API: Audience Demographics Schema

  Audience age data now uses structured `min_age`/`max_age` integers instead of string ranges, and the `interests` field has been removed from audience responses. Geography segments now include a `country_name` field alongside the ISO code.
</Update>

<Update label="February 27, 2026" tags={["New Feature"]}>
  ### Creator API: Audience Demographics

  Audience demographics are now available on all creator endpoints via `include=audience`. Returns directional signals for age, gender, geography, languages, and interests.
</Update>

<Update label="February 27, 2026" tags={["New Feature"]}>
  ### Creator API: Stable Creator IDs

  Creator endpoints now support `include=creator_id` to return a stable Upriver creator ID. Use this ID with `GET /creators/{creator_id}` to reference the same creator across sessions without re-resolving URLs.
</Update>

<Update label="February 26, 2026" tags={["New Feature"]}>
  ### Trends API: Content Filtering

  Improved content filtering for trend recommendations.
</Update>

<Update label="February 26, 2026" tags={["Improvement"]}>
  ### Audience Insights: Search and Citation Quality

  Improved search relevance and citation quality for audience insights.
</Update>

<Update label="February 26, 2026" tags={["Improvement"]}>
  ### Creator API: Audience Demographics Accuracy

  Improved accuracy of creator audience demographic data.
</Update>

<Update label="February 26, 2026" tags={["Bug Fix"]}>
  ### Brand Research: Brand Color Extraction

  Improved accuracy of brand color extraction.
</Update>

<Update label="February 25, 2026" tags={["Improvement"]}>
  ### Breakout Topics: Keyword Search Accuracy

  Improved accuracy of breakout topics keyword search with better stemming, so queries return more relevant results.
</Update>

<Update label="February 24, 2026" tags={["New Feature"]}>
  ### Breakout Topics: Entities

  Added `include=entities` parameter to breakout topics. Returns named entities (people, organizations, places) extracted from each topic, ranked by mention frequency with fine-grained Wikidata type classifications.
</Update>

<Update label="February 24, 2026" tags={["Improvement"]}>
  ### Creator API: Brand Safety Advisories

  Brand safety `flags` have been renamed to `advisories` in API responses. Advisories now include inline citation markers with source attribution.
</Update>

<Update label="February 19, 2026" tags={["New Feature"]}>
  ### Trends API: Sound Attribute Filters

  The trends list endpoint now supports filtering by sound attributes for more targeted trend discovery.
</Update>

<Update label="February 19, 2026" tags={["New Feature"]}>
  ### Breakout Topics: Improved Grouping

  Related breakout topics are now grouped together, making it easier to follow a story across multiple angles.
</Update>

<Update label="February 18, 2026" tags={["Improvement"]}>
  ### Creator API: Brand Safety

  Brand safety analysis is now available for creators.
</Update>

<Update label="February 18, 2026" tags={["Improvement"]}>
  ### Creator API: Terminated Account Filtering

  Terminated creator accounts are now automatically excluded from API responses.
</Update>

<Update label="February 16, 2026" tags={["Bug Fix"]}>
  ### Creator API: Engagement Metrics Latency

  Engagement metrics now return significantly faster.
</Update>

<Update label="February 14, 2026" tags={["Improvement"]}>
  ### Trends API: Sound Duration Fields

  Trend responses now include a `sound_duration` field.
</Update>

<Update label="February 13, 2026" tags={["New Feature"]}>
  ### Agent Skill & llms.txt

  Upriver docs now include [`skill.md`](/ai/skillmd) and [`llms.txt`](/ai/llmstxt) for AI agents and coding assistants. These files provide structured API guidance, endpoint descriptions, and recommended workflows so your AI tools can integrate Upriver more effectively.
</Update>

<Update label="February 13, 2026" tags={["Bug Fix"]}>
  ### Creator API: YouTube Data Freshness

  Fixed an issue where YouTube creator follower counts could become stale and fail to refresh automatically.
</Update>

<Update label="February 12, 2026" tags={["Improvement"]}>
  ### Audience Dimensions: Rate Limiting

  Added per-user rate limiting to the `/v1/audience_dimensions` endpoint to ensure fair usage and system stability.
</Update>

<Update label="February 12, 2026" tags={["Improvement"]}>
  ### Creator API: Enhanced Video Metrics

  Creator video metrics now include `pct_over_8m` field showing the percentage of videos exceeding 8 minutes, useful for identifying long-form content creators. Also improved gaming category classification accuracy.
</Update>

<Update label="February 12, 2026" tags={["Improvement"]}>
  ### Creator API: Real-Time Follower Counts

  Creator API now refreshes stale subscriber and follower counts at request time, ensuring you always get current audience size data.
</Update>

<Update label="February 11, 2026" tags={["New Feature"]}>
  ### Creator API: Video Metrics Enrichment

  Added `include=video_metrics` parameter to creator endpoints. Get video duration and upload frequency data to estimate ad inventory opportunities.
</Update>

<Update label="February 11, 2026" tags={["New Feature"]}>
  ### Audience Insights v3

  New `/v3/audience_insights` endpoint with improved audience segmentation, simplified calling (just pass a `brand_url` instead of chaining endpoints), and a configurable `effort` parameter for faster or deeper analysis.
</Update>

<Update label="February 10, 2026" tags={["New Feature"]}>
  ### Creator API: Twitch Metadata

  Improved Twitch metadata in API responses.
</Update>

<Update label="February 9, 2026" tags={["New Feature"]}>
  ### TikTok Trends: Enhanced Metadata

  Trends API responses now include `tags` and `trend_type` fields for better trend categorization and filtering.
</Update>

<Update label="February 9, 2026" tags={["New Feature"]}>
  ### Trends API: Duration Filtering

  Added duration filtering to trends endpoints. Filter TikTok trends by video length to find content that matches your target format.
</Update>

<Update label="February 7, 2026" tags={["New Feature"]}>
  ### Breakout Topics: Politics Vertical

  Added Politics vertical to breakout topics filtering. Use the `/v1/breakout/metadata` endpoint to discover available verticals including the new Politics category.
</Update>

<Update label="February 7, 2026" tags={["Improvement"]}>
  ### Trends API: Expanded Trend Types

  Trends endpoints now support additional trend type classifications for more granular filtering and discovery.
</Update>

<Update label="February 6, 2026" tags={["New Feature"]}>
  ### Trends API: Individual Trend Lookup

  New GET `/v1/trends/{trend_id}` endpoint to retrieve a specific trend by ID with full trend details.
</Update>

<Update label="February 6, 2026" tags={["New Feature"]}>
  ### Trends API: Optional Playback URLs

  Added `include=playback` parameter to trend endpoints. Audio playback URLs are now fetched on demand rather than included by default, reducing response times when playback data isn't needed.
</Update>

<Update label="February 6, 2026" tags={["Improvement"]}>
  ### Trends Search: Enhanced Metadata

  Trends search results now include complete trend metadata (engagement stats, example videos, audio details) for richer context without requiring additional API calls.
</Update>

<Update label="February 4, 2026" tags={["Improvement"]}>
  ### Breakout Topics: Citation Quality

  Improved citation quality with better deduplication of wire service articles across topics.
</Update>

<Update label="February 4, 2026" tags={["Improvement"]}>
  ### Breakout Topics: Improved Sorting Control

  Replaced `use_dynamic_scoring` boolean with `sort_by` enum parameter. Choose `'relevance'` for time-sensitive trending topics or `'importance'` for stable base scores.
</Update>

<Update label="February 4, 2026" tags={["New Feature"]}>
  ### Breakout Topics: Metadata Endpoint

  New `/v1/breakout/metadata` endpoint for discovering available verticals and categories to filter breakout topics.
</Update>

<Update label="February 4, 2026" tags={["Improvement"]}>
  ### Breakout Topics: Field Rename

  Renamed `canonical_name` to `topic_name` in breakout topics responses. The old `canonical_name` field remains available but is deprecated.
</Update>

<Update label="February 2, 2026" tags={["New Feature"]}>
  ### Creator API: Bio Enrichment

  Creator profiles now include biographical summaries. Use `include=bio` to get a concise summary of the creator's background and content focus.

  ```bash theme={null}
  GET /v1/creators?url=https://youtube.com/@MrBeast&include=bio
  ```
</Update>

***

## January 2026

<Update label="January 31, 2026" tags={["Improvement"]}>
  ### Creator API: Enhanced Profile Data

  Creator API responses now include enriched profile metadata and primary publication identifiers for better creator identification and categorization.
</Update>

<Update label="January 31, 2026" tags={["Improvement"]}>
  ### TikTok Trends: Improved Video Relevance

  Better video relevance scoring for more accurate trend recommendations.
</Update>

<Update label="January 30, 2026" tags={["Improvement"]}>
  ### API Performance Improvements

  * 3x speed improvement to the `/v1/audience_dimensions` endpoint
  * Faster response times for `/v1/trends/broad` endpoint
  * Improved YouTube channel resolution performance
</Update>

<Update label="January 28, 2026" tags={["Bug Fix"]}>
  ### Creator API: Duplicate Profiles

  Fixed an issue where the same YouTube channel could appear multiple times in search results.
</Update>

<Update label="January 26, 2026" tags={["New Feature"]}>
  ### Breakout Topics: Multi-Label Classification

  Topics can now be tagged with multiple labels simultaneously, enabling more nuanced topic categorization and filtering.
</Update>

<Update label="January 22, 2026" tags={["Improvement"]}>
  ### Breakout Topics: Relevance and Momentum Tracking

  Renamed `dynamic_score` to `relevance_score` for clarity. Added `trend` object to topic responses showing momentum indicators like velocity and acceleration for better understanding of topic trajectory.
</Update>

<Update label="January 22, 2026" tags={["Improvement"]}>
  ### Breakout Topics: Enhanced Signal Quality

  * Improved Reddit signal filtering to exclude routine discussion threads
  * Added engagement scores to topic responses for better signal assessment
  * Expanded sports coverage in topic monitoring
</Update>

<Update label="January 22, 2026" tags={["Improvement"]}>
  ### Breakout Topics: Volume-Aware Momentum

  Topic momentum scoring now adapts to conversation volume, providing more accurate trending signals across topics of different scales.
</Update>

<Update label="January 21, 2026" tags={["New Feature"]}>
  ### Creator API: Labels and Tags

  Added `labels` field to Creator API responses with stable category classifications. Labels use the same taxonomy as `media_categories` for consistent categorization across the platform. The existing `tags` field continues to provide flexible, free-form tagging.
</Update>

<Update label="January 21, 2026" tags={["Improvement"]}>
  ### Breakout Topics: Improved Scoring

  Better topic scoring with improved decay functions that adapt to the nature and popularity of each topic.
</Update>

<Update label="January 20, 2026" tags={["New Feature"]}>
  ### Breakout Topics: Citations

  Added `include_citations` parameter to the breakout topics endpoint. When enabled, returns source URLs for each detected topic.
</Update>

<Update label="January 20, 2026" tags={["Improvement"]}>
  ### Breakout Topics: Quality Improvements

  * More accurate topic deduplication
  * More accurate citation attribution
  * Added engagement scoring for better signal quality
</Update>

<Update label="January 20, 2026" tags={["Improvement"]}>
  ### Brand Research API

  Brand research endpoints consolidated to the v1 API path.
</Update>

<Update label="January 18, 2026" tags={["Bug Fix"]}>
  ### Creator API: Performance

  Major API performance improvements, especially for creators not previously tracked in our database.
</Update>

<Update label="January 15, 2026" tags={["New Feature"]}>
  ### Breakout Topics API

  New API for discovering emerging trending topics across news and social media.
</Update>

<Update label="January 10, 2026" tags={["New Feature"]}>
  ### Audience Dimensions API

  New `/v1/audience_dimensions` endpoint for structured audience profiling.
</Update>

<Update label="January 8, 2026" tags={["New Feature"]}>
  ### Creator Batch Endpoint

  New `/v1/creators/batch` endpoint for bulk creator lookups.
</Update>

<Update label="January 5, 2026" tags={["Improvement"]}>
  ### Creator API: GET Endpoint

  New GET `/v1/creators` endpoint for simplified creator lookups.
</Update>

<Update label="January 4, 2026" tags={["New Feature"]}>
  ### Creator API: Engagement Metrics

  Creator responses now include engagement metrics such as average views, likes, and comments across platforms. Metrics are computed from recent content and cached for performance.
</Update>

<Update label="January 3, 2026" tags={["New Feature"]}>
  ### Creator API: Categories

  Creator search results now include media categories and taxonomy classification.
</Update>

***

## December 2025

<Update label="December 10, 2025" tags={["New Feature"]}>
  ### Trends Search API

  New trend search endpoint for finding relevant TikTok trends by keyword.
</Update>

<Update label="December 9, 2025" tags={["New Feature"]}>
  ### Sponsors Search API

  New `/v1/sponsors/search` and `/v1/sponsorships/search` endpoints. Search by brand URL for sponsorship data.
</Update>

<Update label="December 4, 2025" tags={["New Feature"]}>
  ### Per-Result Pricing

  Flexible per-result billing for products, sponsors, and trends endpoints.
</Update>

<Update label="December 3, 2025" tags={["New Feature"]}>
  ### Trends: Audio Playback

  Added `playback_url` for audio trend samples.
</Update>

***

## November 2025

<Update label="November 20, 2025" tags={["Improvement"]}>
  ### Product Research API

  Improved product deduplication and filtering. Brand name search support for sponsors.
</Update>

<Update label="November 19, 2025" tags={["Improvement"]}>
  ### Products API: Enhanced Search

  Parallel search mode using multiple data providers. Response caching for faster lookups.
</Update>

<Update label="November 9, 2025" tags={["Improvement"]}>
  ### Products API: Pagination

  Added cursor-based pagination for products endpoint. Improved product result ranking.
</Update>

<Update label="November 6, 2025" tags={["New Feature"]}>
  ### Categories Search API

  New `/v1/categories/search` endpoint to explore media categories.
</Update>

<Update label="November 5, 2025" tags={["New Feature"]}>
  ### Trends Matching API

  New `/v1/trends/match` endpoint to find relevant TikTok trends for brands.
</Update>

<Update label="November 4, 2025" tags={["New Feature"]}>
  ### Creator Search API

  New `/v1/creators/search` endpoint to discover creators. Cross-platform profile resolution for YouTube, Instagram, TikTok, Twitter, and Twitch. Includes subscriber counts and profile metadata.
</Update>

<Update label="November 4, 2025" tags={["New Feature"]}>
  ### Brand Research API

  New `/v1/brand/research` endpoint for comprehensive brand intelligence. Returns brand overview, target audience, and positioning.
</Update>

***

## October 2025

<Update label="October 27, 2025" tags={["New Feature"]}>
  ### Audience Insights v2: Personas

  New `/v2/audience_insights` endpoint with improved persona generation. Includes personality traits and behavioral insights. Separate citations endpoint for source attribution.
</Update>

<Update label="October 20, 2025" tags={["Improvement"]}>
  ### Sponsors API: Enhanced Data

  Added brand domain and LinkedIn URL to sponsor responses.
</Update>

<Update label="October 15, 2025" tags={["Improvement"]}>
  ### Sponsors API: Categories

  Filter sponsorships by media categories.
</Update>

<Update label="October 8, 2025" tags={["New Feature"]}>
  ### Categories API

  New `/v1/categories` endpoint to browse the media category taxonomy.
</Update>

<Update label="October 7, 2025" tags={["Improvement"]}>
  ### Sponsors API: Performance

  Major performance improvements for sponsor and sponsorship lookups.
</Update>

<Update label="October 2, 2025" tags={["Improvement"]}>
  ### TikTok Trends: Scoring

  Enhanced trend scoring with engagement metrics. Audio and video quality scoring.
</Update>

***

## September 2025

<Update label="September 26, 2025" tags={["New Feature"]}>
  ### Products API

  New `/v1/brand/products` endpoint to discover products from brand websites.
</Update>

<Update label="September 19, 2025" tags={["New Feature"]}>
  ### TikTok Trends API

  New `/v1/trends/broad` endpoint for discovering trending TikTok content. Audio and video trend samples with usage instructions. Pagination support.
</Update>

<Update label="September 4, 2025" tags={["New Feature"]}>
  ### Sponsor Discovery API

  New `/v1/sponsors` endpoint to discover brands sponsoring content. New `/v1/sponsorships` endpoint for detailed sponsorship data. Industry and URL-based filtering.
</Update>

<Update label="September 3, 2025" tags={["New Feature"]}>
  ### Audience Insights: Citations

  Added citation finding capability with source URLs. Enhanced creative guidance with citations.
</Update>

<Update label="September 1, 2025" tags={["Improvement"]}>
  ### Audience Insights: Schema Improvements

  Simplified response schema with cleaner field naming. Updated personality and psychology field structures.
</Update>