> ## 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.

***

## October 2026

<Update label="October 4, 2026" tags={["Improvement"]}>
  ### Creator API: Nearly 20 Million Creator Profiles

  Upriver's creator coverage now spans nearly 20 million profiles across its supported
  platforms. Use the Creator API to search, filter, and enrich creators by content,
  audience size, platform, category, country, and other campaign criteria.
</Update>

<Update label="October 1, 2026" tags={["Improvement"]}>
  ### Private Feeds: Newsletter Coverage

  Private feeds now include newsletter coverage alongside news, web, and social sources.
  This broader evidence base helps you spot emerging topics and niche industry narratives
  earlier.
</Update>

## September 2026

<Update label="September 29, 2026" tags={["Improvement"]}>
  ### Products: Filter products by their role

  Use `tier=primary` or `tier=secondary` on `POST /v1/brand/products` to focus results on
  a brand's main or additional offerings; omit `tier` to include both groups and products
  with no assigned tier. Request 1–20 products per page, then pass the response's
  `next_cursor` as `cursor` with the same brand URL and tier to retrieve the next page.
</Update>

<Update label="September 25, 2026" tags={["Bug Fix"]}>
  ### Trends: Exclude archived trends

  Searches, recommendations, and other trend responses now exclude archived trends. A
  request for an archived trend ID returns HTTP 404. Your application can then remove the
  trend from a saved list or mark it as unavailable.
</Update>

<Update label="September 23, 2026" tags={["New Feature"]}>
  ### Images: Download product images

  Use product images in a brand report, catalog, or dashboard. Send an image URL from
  product research to `POST /v1/images/download` to get the image file. The endpoint
  accepts public HTTPS URLs for JPEG, PNG, WebP, GIF, and AVIF images. File size, pixel,
  and frame limits apply.
</Update>

<Update label="September 22, 2026" tags={["New Feature"]}>
  ### Creators: Check Creator Location

  Use `include=location` on an exact creator lookup to get available location information.
  This can help you select creators for a local campaign or event, with no additional
  enrichment charge.
</Update>

<Update label="September 16, 2026" tags={["Improvement"]}>
  ### Usage: View Credits by Allowance

  The new `breakdown` field in `GET /v1/usage` shows the balance, usage, and reset date
  for each credit allowance. You can now see recurring and lifetime credits separately,
  rather than only a combined balance.
</Update>

<Update label="September 10, 2026" tags={["Improvement"]}>
  ### Sponsorships: Use Commas in Platform Filters

  You can now pass multiple platforms in one value, such as `platforms=youtube,tiktok`.
  This works on GET requests for sponsors, sponsorships, and sponsor channels; repeated
  parameters still work.
</Update>

## August 2026

<Update label="August 27, 2026" tags={["Bug Fix"]}>
  ### Private Feeds: Trajectory Reports Unknown Instead of a Fixed Value

  `trajectory` on private-feed observations previously read `emerging` for every
  newly built item regardless of its age, which made it unusable as a signal. It
  now reports `unknown` where activity direction has not been measured. Treat
  `unknown` as "no direction available" rather than as a stage; a measured value
  will return once direction is derived from observed activity.
</Update>

<Update label="August 24, 2026" tags={["New Feature"]}>
  ### Sponsorships: Pagination and Sync Tokens for New Placements

  Sponsors and sponsorships now support paginated requests for newly added placements.
  Start with `activity_after`, follow `next_cursor` through the result pages, then save
  `next_sync_token` for your next check.

  This lets you fetch new additions without requesting the same history again. It does not
  report later corrections or deletions.
</Update>

<Update label="August 20, 2026" tags={["New Feature"]}>
  ### Trends, Breakout Topics, and Private Feeds: Earliest Evidence Filter

  Use `earliest_evidence_at_or_after` to return only trends, raw Breakout topics,
  and private-feed items whose earliest known supporting activity falls within a
  recent window. Matching results now include `earliest_evidence_at`; results with
  older evidence or no dated evidence are excluded as a whole rather than having
  their individual evidence trimmed.
</Update>

<Update label="August 20, 2026" tags={["New Feature"]}>
  ### Sponsorships API: First-Party Field and Filter

  `/v1/sponsorships` placements now include `is_first_party`: true when the creator promotes their own product, service, or store, false when a third-party sponsor was identified, and omitted when undetermined. Filter with `is_first_party=true` to retrieve first-party placements, which are excluded by default, or `is_first_party=false` to exclude them explicitly.
</Update>

<Update label="August 20, 2026" tags={["Improvement"]}>
  ### Sponsors API: Classification Fields on the Most Recent Ad

  `/v1/sponsors` results now include `monetization_type` and `disclosure_tier` on `most_recent_ad`, alongside the legacy `sponsor_type`. Both fields are omitted when they were never populated for that placement.
</Update>

<Update label="August 20, 2026" tags={["New Feature"]}>
  ### Sponsorships API: Filter by Monetization and Disclosure

  `/v1/sponsorships` now accepts `monetization_type` and `disclosure_tier` as filter parameters (one or more values each), alongside the existing `sponsor_type` filter. Filters on the newer fields match only placements where the field is populated, and requesting `disclosure_tier=inferred` includes inferred placements without setting `include_inferred=true`; see the [Sponsorship types guide](/sponsorships/types) for details.
</Update>

<Update label="August 5, 2026" tags={["Improvement"]}>
  ### Trends API: Multiple Content Structure Filters

  `/v2/trends/broad` now accepts a list for `content_structure`, such as `["structured", "loose"]`, and returns trends matching any requested value. Existing single-string requests continue to work.
</Update>

<Update label="August 5, 2026" tags={["Bug Fix"]}>
  ### Trends API: Momentum Values Restored

  Trend list and detail responses now return the computed `momentum` value when posting-activity evidence is available, instead of leaving the field empty.
</Update>

## July 2026

<Update label="July 24, 2026" tags={["New Feature"]}>
  ### Sponsorships: Find a sponsor across channels and names

  Use `sponsor_id` to find sponsorships for the same brand across channels and different
  names. For example, “Acme” on YouTube and “Acme UK” on Instagram can share an ID if
  Upriver identifies the same sponsor. Use that ID for later searches. Use
  `GET /v1/sponsors/{sponsor_id}/channels` to find the social accounts for that sponsor. IDs
  can be absent, and regional names do not always share an ID.
</Update>

<Update label="July 24, 2026" tags={["Improvement"]}>
  ### Creators: Pagination for Name and Content Searches

  Creator searches by name or content description now support pagination. Use the returned
  cursor to get more matching creators after the first page.
</Update>

<Update label="July 16, 2026" tags={["New Feature"]}>
  ### Creators: Find Creators with Similar Content

  The new `POST /v1/creators/similar` endpoint finds creators who make content similar to
  a given creator. Provide a creator ID or social profile URL, then filter by platform,
  category, follower count, or country.

  Use a creator from a past campaign to find candidates for your next one. This endpoint
  is in beta, and its response format can change.
</Update>

<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"]}>
  ### Sponsorships API: Monetization and Disclosure Fields

  `/v1/sponsorships` placement responses now separate the likely deal
  (`monetization_type`: `paid_partnership`, `affiliate`, `gifted`, or `unknown`)
  from the evidence linking the creator and sponsor (`disclosure_tier`:
  `platform_verified`, `creator_disclosed`, `commercial_signal`, or `inferred`);
  the original `sponsor_type` field remains available for existing filters and
  integrations. Either new field can be omitted, and some historical records
  translate both from `sponsor_type`—including the older `promotion`,
  `self_promotion`, and `merch_store` monetization values—so they are not always
  independent evidence.
</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 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"]}>
  ### 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

  * 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 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 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>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.