# llms.txt
Source: https://docs.upriver.ai/ai/llmstxt

Documentation index for LLMs and AI tools

The [llms.txt file](https://llmstxt.org) is an industry standard that helps LLMs index content more efficiently, similar to how a sitemap helps search engines. AI tools can use this file to understand the Upriver documentation structure and find content relevant to user queries.

Upriver hosts an `llms.txt` file at the root of the documentation site that lists all available pages. This file is always up to date and requires no maintenance.

View the Upriver llms.txt at: [docs.upriver.ai/llms.txt](https://docs.upriver.ai/llms.txt)

## llms.txt structure

An `llms.txt` file is a plain Markdown file that contains:

* **Site title** as an H1 heading.
* **Structured content sections** with links and a description of each page in the documentation.

```md Example llms.txt theme={null}
# Upriver API Docs

## API Reference

- [Brands](https://docs.upriver.ai/api-reference/brands): Search and retrieve brand data
- [Creators](https://docs.upriver.ai/api-reference/creators): Look up creator profiles
- [Audiences](https://docs.upriver.ai/api-reference/audiences): Analyze audience insights
```

This structured approach allows LLMs to efficiently process the documentation at a high level and locate relevant content for user queries.

## llms-full.txt

The `llms-full.txt` file combines the entire Upriver documentation site into a single file as context for AI tools.

View the Upriver llms-full.txt at: [docs.upriver.ai/llms-full.txt](https://docs.upriver.ai/llms-full.txt)


# skill.md
Source: https://docs.upriver.ai/ai/skillmd

Give your AI agent the Upriver API reference

The [`skill.md`](https://docs.upriver.ai/skill.md) file is a structured, machine-readable API reference that tells AI agents what they can do with the Upriver API. It follows the [skill.md specification](https://agentskills.io/specification) and includes endpoint descriptions, required parameters, and usage guidance in a format LLMs can reliably work with.

View the Upriver skill.md at: [docs.upriver.ai/skill.md](https://docs.upriver.ai/skill.md)

<Tip>
  Both `skill.md` and `llms.txt` help agents work with the Upriver API, but they serve different purposes.

  * `skill.md` is a **capability summary**. It tells agents what actions are available, what inputs they need, and what constraints apply.
  * `llms.txt` is a **documentation index**. It lists available pages with descriptions so agents know where to find information.

  Use `skill.md` when you want agents to call the API directly. Use `llms.txt` when you want agents to browse the docs.
</Tip>

## Use skill.md with agents

### Skills CLI

Agents can process the skill.md with the [skills CLI](https://www.npmjs.com/package/skills).

```bash theme={null}
npx skills add https://docs.upriver.ai
```

### Claude Code / OpenClaw

Add the URL to your project context or reference it in a prompt:

```bash theme={null}
curl -s https://docs.upriver.ai/skill.md >> AGENTS.md
```

```
Use the Upriver API as described in https://docs.upriver.ai/skill.md
```

### Cursor / Windsurf

Add it as a doc in your project settings:

1. Go to **Settings → Docs**
2. Add `https://docs.upriver.ai/skill.md`

### ChatGPT / Claude.ai

Paste the URL or file contents into your conversation:

```
Here's the API reference: https://docs.upriver.ai/skill.md
Use it to help me call the Upriver API.
```

### Any agent or framework

Fetch it at build time or runtime:

```bash theme={null}
curl -s https://docs.upriver.ai/skill.md
```

The file is plain Markdown. Works anywhere that accepts text context.

## What's in the file

The skill.md includes:

* **Metadata**: API name, description, and base URL.
* **Authentication**: How to authenticate requests.
* **Endpoints**: Available actions organized by resource (brands, creators, audiences, trends, etc).
* **Parameters**: Required and optional inputs for each endpoint.
* **Usage guidance**: Tips on how to chain endpoints and handle responses.


# Get Usage
Source: https://docs.upriver.ai/api-reference/account/get-usage

/api-reference/openapi.json get /v1/usage
Get usage for the provided API key



# Dimensions
Source: https://docs.upriver.ai/api-reference/audience/dimensions

/api-reference/openapi.json post /v1/audience_dimensions
Extract atomic audience dimensions for a brand.
Dimensions are the building blocks of personas.

Returns granular behavioral, motivational, and lifestyle dimensions about
relevant audiences for a specified brand.
Each fact can be used for matching with user profiles.

**Verbosity** controls fact phrasing (applies only to the `fact` field):
- `verbose`: Full sentences with subject (e.g., 'This audience seeks healthy recipes')
- `standard` (default): Phrases without subject (e.g., 'seeks healthy recipes')
- `compact`: Keywords only (e.g., 'healthy recipes')

**Response includes:**
- Audience dimensions with classification and confidence scores
- Supporting evidence snippets (optional)



# Personas
Source: https://docs.upriver.ai/api-reference/audience/personas

/api-reference/openapi.json post /v2/audience_insights
Get detailed audience personas with psychographics, behaviors, motivators, and barriers. Ideal for creative strategy, targeting, and understanding your audience at a psychological level.

**Input:** Provide brand info, products, and industry context. Can chain output from Brand Research endpoint.

**Output:** 3-5 distinct personas with personality traits, behavioral patterns, motivations, and barriers.

**Citations Mode:**
- `async` (recommended): Fast response, fetch citations separately via continuation token
- `sync`: Include citations in response (slower)
- `none`: No citations (fastest)



# Personas - Citations
Source: https://docs.upriver.ai/api-reference/audience/personas--citations

/api-reference/openapi.json get /v2/audience_insights/{continuation_token}/citations
Retrieve citations and behavioral evidence for audience personas. Use the continuation token from the `v2/audience_insights` response.

**Recommended Usage:** Set `citations_mode=async` in the audience insights request, then call this endpoint to retrieve citations separately. This keeps the initial response fast while allowing deep citation analysis.



# Personas (v3)
Source: https://docs.upriver.ai/api-reference/audience/personas-v3

/api-reference/openapi.json post /v3/audience_insights
Get detailed audience personas for a brand.

**Input:** Brand URL, optional query and effort level.

**Output:** Personas with purchase triggers, barriers, behaviors, language patterns, and optional real world citations.



# Brand Research
Source: https://docs.upriver.ai/api-reference/brands/brand-research

/api-reference/openapi.json post /v1/brand/research
Provides details for a brand including identity, target audience, and brand language. Returns structured data optimized for chaining into the Audience Insights endpoint.

**Input Options:**
- Provide `brand_name` and/or `brand_url`



# Find Similar Topics
Source: https://docs.upriver.ai/api-reference/breakout-topics/find-similar-topics

/api-reference/openapi.json post /v1/topics/breakout/similar
Find topics similar to a given topic by embedding similarity.



# Get Breakout Topic
Source: https://docs.upriver.ai/api-reference/breakout-topics/get-breakout-topic

/api-reference/openapi.json get /v1/topics/breakout/{topic_id}
Get a single breakout topic by ID.



# Get Breakout Topics Metadata
Source: https://docs.upriver.ai/api-reference/breakout-topics/get-breakout-topics-metadata

/api-reference/openapi.json get /v1/topics/breakout/metadata
Get metadata about available verticals and categories for filtering.

Returns the taxonomy of verticals and their associated categories,
with human-readable display names for building filter UIs.



# Get Narrative
Source: https://docs.upriver.ai/api-reference/breakout-topics/get-narrative

/api-reference/openapi.json get /v1/topics/breakout/narratives/{narrative_id}
Get a narrative by ID with member topics.



# Get Topic Cluster View
Source: https://docs.upriver.ai/api-reference/breakout-topics/get-topic-cluster-view

/api-reference/openapi.json get /v1/topics/breakout/{topic_id}/cluster
Get a derived cluster view around a seed breakout topic.



# Get Topic Story View
Source: https://docs.upriver.ai/api-reference/breakout-topics/get-topic-story-view

/api-reference/openapi.json get /v1/topics/breakout/{topic_id}/story
Get the best available derived story surface around a seed topic.



# Get Topic Timeline View
Source: https://docs.upriver.ai/api-reference/breakout-topics/get-topic-timeline-view

/api-reference/openapi.json get /v1/topics/breakout/{topic_id}/timeline
Get a derived timeline view around a seed breakout topic.



# List Breakout Topics
Source: https://docs.upriver.ai/api-reference/breakout-topics/list-breakout-topics

/api-reference/openapi.json get /v1/topics/breakout
List breakout topics with optional filters.

Returns topics sorted by the specified sort order:
- 'relevance' (default): Dynamic score with time decay, momentum, and confidence
- 'importance': Static base importance score (no temporal factors)



# List Narratives
Source: https://docs.upriver.ai/api-reference/breakout-topics/list-narratives

/api-reference/openapi.json get /v1/topics/breakout/narratives
List narrative arcs, ordered by most recently updated.



# Search Breakout Topics
Source: https://docs.upriver.ai/api-reference/breakout-topics/search-breakout-topics

/api-reference/openapi.json post /v1/topics/breakout/search
Search breakout topics using hybrid vector + keyword search.

Supports three search modes:
- vector: Semantic similarity search using embeddings
- keyword: Full-text search using PostgreSQL tsvector
- hybrid: Combined vector and keyword search (default)



# Batch Creator Details
Source: https://docs.upriver.ai/api-reference/creators/batch-creator-details

/api-reference/openapi.json post /v1/creators/batch
Provides creator profile information for multiple creators in a single request. Returns associated channels and labels for each URL.

**Input:** Provide 1-10 social media profile URLs (e.g., https://youtube.com/@handle)

**Note:** Engagement metrics are not available for batch requests.



# Creator Profile by ID
Source: https://docs.upriver.ai/api-reference/creators/creator-profile-by-id

/api-reference/openapi.json get /v1/creators/{creator_id}
Lookup a creator profile by stable Upriver creator ID.

Returns the same payload shape as `GET /v1/creators` (URL lookup). The only difference is the lookup key (`creator_id` vs `url`).

If the ID has been merged into another creator, the response includes a `redirect` object in the JSON body and the `X-Creator-Redirect` header. Clients should update any stored creator ID to `redirect.canonical_creator_id`.

Use `include` for optional expansions.



# Creator Profile by URL
Source: https://docs.upriver.ai/api-reference/creators/creator-profile-by-url

/api-reference/openapi.json get /v1/creators
Lookup a creator profile by known social profile URL.

Returns the same payload shape as `GET /v1/creators/{creator_id}`. The only difference is the lookup key (`url` vs `creator_id`).

Use this endpoint when you have a channel/profile URL and do not yet have a stored `creator_id`. Use `include` for optional expansions.



# Product Details
Source: https://docs.upriver.ai/api-reference/products/product-details

/api-reference/openapi.json post /v1/brand/product
Provides details for a specific product including description, features, and pricing. Provide as much information as you have — more context improves accuracy.

**Input:**
- **product_name**: Required.
- **product_url**, **brand_url**, **brand_name**: Optional. At least one required to identify the brand.

**Effort Levels:**
- **low**: fast extraction from the product page.
- **high**: includes competitive research (alternatives).



# Products List
Source: https://docs.upriver.ai/api-reference/products/products-list

/api-reference/openapi.json post /v1/brand/products
Returns a list of products associated with a brand. Requires **brand_url** on every request, including pagination requests that send **cursor**. When **cursor** is provided, **brand_url** must match the brand encoded in that cursor.

Response format:
- **json**: Returns structured data with product list (default)
- **text**: Returns natural language report

The service prioritizes prominent and popular products from the brand's website.



# Sponsors
Source: https://docs.upriver.ai/api-reference/sponsorships/sponsors

/api-reference/openapi.json get /v1/sponsors
Search for brands that recently sponsored media channels/publications.

Provide exactly one scope filter: `categories` or `publication_url`.

- `categories`: Find sponsors active in those content verticals.
- `publication_url`: Find sponsors for a specific creator/publication.

Use `platforms`, date range, and confidence parameters to refine results.



# Sponsorships
Source: https://docs.upriver.ai/api-reference/sponsorships/sponsorships

/api-reference/openapi.json get /v1/sponsorships
Return individual sponsored placements (content-level rows).

Provide at least one of `sponsor_name`, `brand_id`, `publication_url`, or `categories`. These can be combined, except `publication_url` and `categories` cannot be used together.



# Media Categories
Source: https://docs.upriver.ai/api-reference/taxonomy/media-categories

/api-reference/openapi.json get /v1/media_categories
Returns the media categories split into L1 (top-level) and L2 (second-level) lists. These categories can be used as a filter for sponsors, sponsorships. and other endpoints which support filtering by categories.



# Media Categories Search
Source: https://docs.upriver.ai/api-reference/taxonomy/media-categories-search

/api-reference/openapi.json post /v1/categories/search
Find the most relevant categories from the taxonomy for a given freeform text. Useful for discovering the best category for brand industries, target audiences, etc. Returns ordered matches with confidence scores.



# Audio Playback
Source: https://docs.upriver.ai/api-reference/trends/audio-playback

/api-reference/openapi.json get /v2/trends/{trend_id}/playback
Return a playback URL for a trend's audio media



# Media Samples
Source: https://docs.upriver.ai/api-reference/trends/media-samples

/api-reference/openapi.json get /v2/trends/{trend_id}/media
Returns video and audio url samples for a trend



# Similar Trends
Source: https://docs.upriver.ai/api-reference/trends/similar-trends

/api-reference/openapi.json get /v2/trends/{trend_id}/similar
Find trends similar to a given trend via embedding similarity



# Traction Graph
Source: https://docs.upriver.ai/api-reference/trends/traction-graph

/api-reference/openapi.json get /v2/trends/{trend_id}/traction
Pre-computed traction graph points for a trend. Returns both 'all' and 'recent' windows with estimated curves plus separate blended activity curves.



# Trend Details
Source: https://docs.upriver.ai/api-reference/trends/trend-details

/api-reference/openapi.json get /v2/trends/{trend_id}
Get a specific trend by its id. Use the /trends/{id}/playback endpoint to get a refreshed audio playback URL.



# Trends List
Source: https://docs.upriver.ai/api-reference/trends/trends-list

/api-reference/openapi.json post /v2/trends/broad
Get the latest trending formats.



# Changelog
Source: https://docs.upriver.ai/changelog

Recent updates to the Upriver API

# Changelog

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

***

## April 2026

<Update label="April 15, 2026">
  ### 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">
  ### 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">
  ### 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">
  ### 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">
  ### Creator API: Engagement Metrics Reliability

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

<Update label="April 11, 2026">
  ### 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">
  ### 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">
  ### 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">
  ### 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">
  ### 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">
  ### 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">
  ### 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">
  ### 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">
  ### 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">
  ### 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">
  ### 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">
  ### 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">
  ### 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">
  ### Audience Insights: v2 Endpoint Deprecated

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

<Update label="March 22, 2026">
  ### 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">
  ### 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">
  ### 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">
  ### 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">
  ### 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">
  ### 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">
  ### 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">
  ### 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">
  ### 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">
  ### 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">
  ### 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">
  ### 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">
  ### 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">
  ### 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">
  ### 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">
  ### 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">
  ### 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">
  ### 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">
  ### 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">
  ### 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">
  ### 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">
  ### 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">
  ### Trends API: Content Filtering

  Improved content filtering for trend recommendations.
</Update>

<Update label="February 26, 2026">
  ### Audience Insights: Search and Citation Quality

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

<Update label="February 26, 2026">
  ### Creator API: Audience Demographics Accuracy

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

<Update label="February 26, 2026">
  ### Brand Research: Brand Color Extraction

  Improved accuracy of brand color extraction.
</Update>

<Update label="February 25, 2026">
  ### 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">
  ### 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">
  ### 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">
  ### 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">
  ### 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">
  ### Creator API: Brand Safety

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

<Update label="February 18, 2026">
  ### Creator API: Terminated Account Filtering

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

<Update label="February 16, 2026">
  ### Creator API: Engagement Metrics Latency

  Engagement metrics now return significantly faster.
</Update>

<Update label="February 14, 2026">
  ### Trends API: Sound Duration Fields

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

<Update label="February 13, 2026">
  ### 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">
  ### 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">
  ### 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">
  ### 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">
  ### 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">
  ### 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">
  ### 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">
  ### Creator API: Twitch Metadata

  Improved Twitch metadata in API responses.
</Update>

<Update label="February 9, 2026">
  ### 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">
  ### 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">
  ### 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">
  ### 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">
  ### 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">
  ### 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">
  ### 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">
  ### Breakout Topics: Citation Quality

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

<Update label="February 4, 2026">
  ### 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">
  ### 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">
  ### 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">
  ### 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">
  ### 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">
  ### TikTok Trends: Improved Video Relevance

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

<Update label="January 30, 2026">
  ### 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">
  ### 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">
  ### 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">
  ### 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">
  ### 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">
  ### 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">
  ### 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">
  ### 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">
  ### 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">
  ### 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">
  ### Brand Research API

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

<Update label="January 18, 2026">
  ### Creator API: Performance

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

<Update label="January 15, 2026">
  ### Breakout Topics API

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

<Update label="January 10, 2026">
  ### Audience Dimensions API

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

<Update label="January 8, 2026">
  ### Creator Batch Endpoint

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

<Update label="January 5, 2026">
  ### Creator API: GET Endpoint

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

<Update label="January 4, 2026">
  ### 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">
  ### Creator API: Categories

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

***

## December 2025

<Update label="December 10, 2025">
  ### Trends Search API

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

<Update label="December 9, 2025">
  ### 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">
  ### Per-Result Pricing

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

<Update label="December 3, 2025">
  ### Trends: Audio Playback

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

***

## November 2025

<Update label="November 20, 2025">
  ### Product Research API

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

<Update label="November 19, 2025">
  ### Products API: Enhanced Search

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

<Update label="November 9, 2025">
  ### Products API: Pagination

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

<Update label="November 6, 2025">
  ### Categories Search API

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

<Update label="November 5, 2025">
  ### Trends Matching API

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

<Update label="November 4, 2025">
  ### 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">
  ### 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">
  ### 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">
  ### Sponsors API: Enhanced Data

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

<Update label="October 15, 2025">
  ### Sponsors API: Categories

  Filter sponsorships by media categories.
</Update>

<Update label="October 8, 2025">
  ### Categories API

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

<Update label="October 7, 2025">
  ### Sponsors API: Performance

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

<Update label="October 2, 2025">
  ### TikTok Trends: Scoring

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

***

## September 2025

<Update label="September 26, 2025">
  ### Products API

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

<Update label="September 19, 2025">
  ### 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">
  ### 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">
  ### Audience Insights: Citations

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

<Update label="September 1, 2025">
  ### Audience Insights: Schema Improvements

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


# Introduction
Source: https://docs.upriver.ai/index

API for real-time context on creators, audiences, brands, trends, and sponsorships

## What is Upriver?

[Upriver](https://upriver.ai/?ref=docs) provides an API that turns what's happening online into real-time, reliable context for AI applications.

## Core Features

Upriver specializes in evidence-backed analysis on norms, influences, and aesthetics that come from online communities.

* <b>Brands</b>: brands and how they're being discussed
* <b>Products</b>: product mentions and use cases
* <b>Creators</b>: relevant creators and profiles
* <b>Audiences</b>: personas, interests, language, and humor
* <b>Trends</b>: topics and formats gaining attention
* <b>Sponsorships</b>: Brand-creator relationships and placements

## Popular Use Cases

Developers blend Upriver's external data with internal data for uses cases like:

<Columns>
  <Card title="Content Generation" icon="sparkles">
    Ground AI outputs in what people actually care about
  </Card>

  <Card title="Search and Match" icon="magnifying-glass">
    Power discovery and recommendations using relevance signals
  </Card>

  <Card title="Targeting" icon="crosshairs">
    Identify relevant brands, creators, or audiences
  </Card>

  <Card title="Enrichment" icon="pencil-line">
    Surface our insights directly to end users
  </Card>
</Columns>

## For Agents + LLMs

Building with agents or coding assistants? Give them the skill.md and they can use the API directly.

<CardGroup>
  <Card title="skill.md" icon="lobster" href="/ai/skillmd">
    Structured capabilities file for agents
  </Card>

  <Card title="llms.txt" icon="robot" href="/ai/llmstxt">
    Documentation index for LLMs
  </Card>
</CardGroup>

## Get Started

To get an API key, schedule an intro call:

<Card title="Schedule 1:1 Call" icon="video" href="https://cal.com/lulu-zhang/upriver-intro">
  20-minute intro call to discuss your use case and learn how Upriver can help.
</Card>


# Metrics
Source: https://docs.upriver.ai/metrics

How engagement metrics and video metrics are calculated, which platforms they cover, and how to interpret them

The Creators API returns two optional metric objects per channel: **engagement metrics** and **video metrics**. Both are requested via the `include` query parameter and returned per-channel in the response.

```bash theme={null}
# Request both metric types
curl "https://api.upriver.ai/v1/creators/profile-by-url?\
url=https://youtube.com/@example&\
include=engagement_metrics,video_metrics" \
  -H "X-API-Key: YOUR_KEY"
```

***

## Engagement Metrics

Engagement metrics summarize a creator's recent content performance — average views, likes, comments, and an overall engagement rate.

### Fields

| Field                 | Type              | Description                                                            |
| --------------------- | ----------------- | ---------------------------------------------------------------------- |
| `avg_views`           | `integer \| null` | Average view count across recent content                               |
| `avg_likes`           | `integer \| null` | Average like count across recent content                               |
| `avg_comments`        | `integer \| null` | Average comment count across recent content                            |
| `avg_engagement_rate` | `float \| null`   | `(likes + comments) / views`, expressed as a decimal (e.g., 0.05 = 5%) |

### Platform Coverage

Engagement metrics are available on these platforms:

| Platform    | Content Types Sampled | Metrics Available              |
| ----------- | --------------------- | ------------------------------ |
| YouTube     | Videos, Shorts        | Views, Likes, Comments         |
| Instagram   | Posts, Reels          | Views (reels), Likes, Comments |
| TikTok      | Videos                | Views, Likes, Comments         |
| X (Twitter) | Posts                 | Views, Likes, Comments         |
| Twitch      | Videos, Clips         | Views only                     |

<Info>
  Platforms not listed above (Substack, Spotify, Podcast) return channel metadata but do not include engagement metrics.
</Info>

### How Calculation Works

Engagement metrics are computed from a creator's **recent posts per content type** on each platform.

<Steps>
  <Step title="Fetch recent content">
    Recent items are collected per content type — for example, YouTube Videos and Shorts are sampled separately.
  </Step>

  <Step title="Average per content type">
    Within each content type, metrics are averaged independently — average views, average likes, and average comments for that type alone.
  </Step>

  <Step title="Weighted average across content types">
    When a creator has multiple content types (e.g., both Videos and Shorts), the per-type averages are combined using a **sample-size-weighted average**.

    ```
    avg_views = (videos_avg_views * videos_sample_size + shorts_avg_views * shorts_sample_size)
                / (videos_sample_size + shorts_sample_size)
    ```

    This keeps content types with more samples proportionally weighted.
  </Step>

  <Step title="Derive engagement rate">
    Once the weighted averages are computed:

    ```
    avg_engagement_rate = (avg_likes + avg_comments) / avg_views
    ```

    This is only calculated when `avg_views > 0` and at least one of `avg_likes` or `avg_comments` is available.
  </Step>
</Steps>

### Example

A YouTube creator who publishes both long-form videos and Shorts:

| Content Type | Sample Size | Avg Views | Avg Likes |
| ------------ | ----------- | --------- | --------- |
| Videos       | 10          | 100,000   | 4,000     |
| Shorts       | 15          | 50,000    | 2,500     |

**Weighted avg\_views** = `(100,000 * 10 + 50,000 * 15) / (10 + 15)` = **70,000**

**Weighted avg\_likes** = `(4,000 * 10 + 2,500 * 15) / (10 + 15)` = **3,100**

The Shorts pull the averages down because there are more of them — which reflects that this creator's audience engages with Shorts differently than long-form videos.

### Response Example

```json theme={null}
{
  "channels": [
    {
      "platform": "youtube",
      "handle": "@example",
      "engagement_metrics": {
        "avg_views": 70000,
        "avg_likes": 3100,
        "avg_comments": 850,
        "avg_engagement_rate": 0.056
      }
    }
  ]
}
```

***

## Video Metrics

Video metrics describe a creator's **upload cadence and video duration profile** over a trailing window. These are designed for ad inventory estimation — understanding how frequently a creator uploads, how long their videos are, and what percentage are eligible for mid-roll ads.

<Note>
  Video metrics are currently available for **YouTube only**.
</Note>

### Fields

| Field                  | Type              | Description                                                     |
| ---------------------- | ----------------- | --------------------------------------------------------------- |
| `avg_duration_seconds` | `integer \| null` | Average video duration in seconds within the lookback window    |
| `uploads_per_week`     | `float \| null`   | Average uploads per week over the lookback window               |
| `pct_over_8m`          | `float \| null`   | Percentage of videos over 8 minutes (eligible for mid-roll ads) |
| `lookback_weeks`       | `integer \| null` | Lookback window length (currently fixed at 12 weeks)            |
| `weeks_observed`       | `integer \| null` | How many weeks of history were actually observed                |
| `window_complete`      | `boolean \| null` | `true` when a full lookback window was observed                 |

### Lookback Window

Video metrics use a **trailing 12-week window** from the current date. All uploads published within this window are included in the calculation.

```
|<------------ 12 weeks ------------>|
|                                     now
|  uploads in this range are counted  |
```

### Coverage Metadata

The `weeks_observed` and `window_complete` fields tell you how much history was available:

| Scenario                      | `weeks_observed` | `window_complete` | Interpretation                |
| ----------------------------- | ---------------- | ----------------- | ----------------------------- |
| Established creator           | 12               | `true`            | Full 12-week window observed  |
| New creator (2 weeks old)     | 2                | `false`           | Only 2 weeks of history exist |
| Inactive creator (no uploads) | 12               | `true`            | Full window, but 0 uploads    |

<Info>
  When `window_complete` is `false`, treat `uploads_per_week` as a preliminary estimate based on limited history. The creator may not have been active long enough for the metric to stabilize.
</Info>

### Mid-Roll Eligibility

`pct_over_8m` represents the percentage of videos in the window that are longer than 8 minutes (480 seconds). YouTube allows mid-roll ad breaks on videos over 8 minutes, making this a useful signal for ad inventory planning.

### Response Examples

<AccordionGroup>
  <Accordion title="Established creator with consistent uploads">
    ```json theme={null}
    {
      "video_metrics": {
        "avg_duration_seconds": 615,
        "uploads_per_week": 1.75,
        "pct_over_8m": 66.7,
        "lookback_weeks": 12,
        "weeks_observed": 12,
        "window_complete": true
      }
    }
    ```

    Full 12 weeks observed. About 1.75 uploads/week, averaging \~10 minutes, with two-thirds of videos eligible for mid-roll ads.
  </Accordion>

  <Accordion title="New creator with limited history">
    ```json theme={null}
    {
      "video_metrics": {
        "avg_duration_seconds": 420,
        "uploads_per_week": 2.5,
        "pct_over_8m": 25.0,
        "lookback_weeks": 12,
        "weeks_observed": 2,
        "window_complete": false
      }
    }
    ```

    Only 2 weeks of upload history exist. Metrics are calculated over those 2 weeks — the upload rate may not be representative of long-term behavior.
  </Accordion>

  <Accordion title="Inactive creator (no uploads in window)">
    ```json theme={null}
    {
      "video_metrics": {
        "uploads_per_week": 0.0,
        "lookback_weeks": 12,
        "weeks_observed": 12,
        "window_complete": true
      }
    }
    ```

    Full window was observed, but no uploads fell within it. Duration and mid-roll fields are omitted.
  </Accordion>
</AccordionGroup>

***

## Engagement vs. Video Metrics

These two metric types answer different questions:

|                       | Engagement Metrics                                              | Video Metrics                                             |
| --------------------- | --------------------------------------------------------------- | --------------------------------------------------------- |
| **Question answered** | How does this creator's content perform?                        | How often and how long does this creator publish?         |
| **Platforms**         | YouTube, Instagram, TikTok, X, Twitch                           | YouTube only                                              |
| **Sample basis**      | Recent items per content type                                   | All uploads in trailing 12-week window                    |
| **Key fields**        | `avg_views`, `avg_likes`, `avg_comments`, `avg_engagement_rate` | `avg_duration_seconds`, `uploads_per_week`, `pct_over_8m` |
| **Use case**          | Creator quality and audience responsiveness                     | Ad inventory estimation and upload consistency            |

***

## Edge Cases

### Null Fields

Any metric field can be `null`. Common causes:

| Scenario                                                      | Result                                               |
| ------------------------------------------------------------- | ---------------------------------------------------- |
| Platform doesn't support a metric (e.g., Twitch has no likes) | `avg_likes: null`                                    |
| No content available for calculation                          | Entire metric object is omitted                      |
| Comments disabled on all sampled videos                       | `avg_comments: null` (excluded from engagement rate) |
| No uploads in the video metrics window                        | `avg_duration_seconds: null`, `pct_over_8m: null`    |

### Engagement Rate Calculation

`avg_engagement_rate` requires:

* `avg_views > 0`
* At least one of `avg_likes` or `avg_comments` is non-null

If either condition isn't met, `avg_engagement_rate` is `null`. When only one of likes/comments is available (e.g., Twitch), the missing value is treated as 0 in the numerator.

### Data Freshness

Metrics are cached and refreshed periodically. If you need guaranteed fresh data for a specific creator, contact support.