> ## 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. # Creator Profile by ID > Lookup a creator profile by 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. ## OpenAPI ````yaml /api-reference/openapi.json get /v1/creators/{creator_id} openapi: 3.1.0 info: title: Upriver API description: >- A social insights API for ad generation platforms. It provides structured signals, like psychographics, behavioral insights, trends, and audience language, to help AI models generate relevant, higher-converting ads. version: 1.0.0 servers: - url: https://api.upriver.ai description: Production API server security: [] tags: - name: Brands - name: Products - name: Creators - name: Audience - name: Sponsorships - name: Trends - name: Breakout Topics - name: Taxonomy paths: /v1/creators/{creator_id}: get: tags: - Creators summary: Creator Profile by ID description: >- Lookup a creator profile by 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. operationId: creator_get_by_id parameters: - name: creator_id in: path required: true schema: type: string title: Creator Id - name: include in: query required: false schema: type: array items: type: string description: >- Optional expansions to include in the response. The same include options are available on `GET /v1/creators` (lookup by URL) and `GET /v1/creators/{creator_id}` (lookup by Upriver creator ID). **Include values and what each adds:** - `engagement_metrics`: Recent per-channel engagement performance (average views, likes, comments, engagement rate). Returned as `channels[].engagement_metrics`. - `video_metrics`: Per-channel upload cadence and duration-based inventory signals over a trailing 12-week window (YouTube). Returned as `channels[].video_metrics`. - `relative_metrics`: Per-channel public benchmark summaries compared with similar creators. Returned as `channels[].relative_metrics`. - `bio`: Creator summary and key context. Returned as top-level `bio`. - `audience`: Directional audience demographics (age, gender, geography). Returned as top-level `audience`. - `brand_safety`: Brand safety advisories with citations. Returned as top-level `brand_safety`. - `email`: Public contact email addresses the creator has published for business inquiries, gathered across their linked channels. Returned as top-level `emails`. - `creator_id`: Backward-compatible no-op; `creator_id` is always returned. **Format:** - Repeat params: `?include=engagement_metrics&include=bio` - CSV: `?include=engagement_metrics,bio` default: [] title: Include description: >- Optional expansions to include in the response. The same include options are available on `GET /v1/creators` (lookup by URL) and `GET /v1/creators/{creator_id}` (lookup by Upriver creator ID). **Include values and what each adds:** - `engagement_metrics`: Recent per-channel engagement performance (average views, likes, comments, engagement rate). Returned as `channels[].engagement_metrics`. - `video_metrics`: Per-channel upload cadence and duration-based inventory signals over a trailing 12-week window (YouTube). Returned as `channels[].video_metrics`. - `relative_metrics`: Per-channel public benchmark summaries compared with similar creators. Returned as `channels[].relative_metrics`. - `bio`: Creator summary and key context. Returned as top-level `bio`. - `audience`: Directional audience demographics (age, gender, geography). Returned as top-level `audience`. - `brand_safety`: Brand safety advisories with citations. Returned as top-level `brand_safety`. - `email`: Public contact email addresses the creator has published for business inquiries, gathered across their linked channels. Returned as top-level `emails`. - `creator_id`: Backward-compatible no-op; `creator_id` is always returned. **Format:** - Repeat params: `?include=engagement_metrics&include=bio` - CSV: `?include=engagement_metrics,bio` responses: '200': description: >- Canonical creator payload. When a previously stored creator ID has been merged into another creator, the response still returns HTTP 200 with the canonical creator body, a `redirect` object in the JSON payload, and an `X-Creator-Redirect` response header. content: application/json: schema: $ref: '#/components/schemas/CreatorGetResponse' examples: merged_creator_id: summary: Merged creator ID resolved to canonical creator value: channels: - platform: youtube handle: '@creator' url: https://www.youtube.com/@creator labels: [] tags: [] creator_id: cb4f53f0-c905-4c0a-86df-9a6c7551c408 stable_creator_id: cb4f53f0-c905-4c0a-86df-9a6c7551c408 redirect: requested_creator_id: 97ca4d8c-c1b2-4c73-a4f0-7ac6bb05e0cf canonical_creator_id: cb4f53f0-c905-4c0a-86df-9a6c7551c408 reason: merged headers: X-Creator-Redirect: description: >- Present when the requested creator ID was merged into another creator. Contains the canonical creator ID returned in the body. schema: type: string format: uuid '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' security: - APIKeyHeader: [] components: schemas: CreatorGetResponse: properties: bio: anyOf: - $ref: '#/components/schemas/CreatorBio' - type: 'null' description: >- Biographical summary of the creator. Only present when include=bio is specified. channels: items: $ref: '#/components/schemas/CreatorPlatform' type: array title: Channels description: Social media channels for the creator across supported platforms. associated_creators: items: $ref: '#/components/schemas/CreatorAssociatedCreator' type: array title: Associated Creators description: Distinct associated creator clusters related to this creator. labels: items: $ref: '#/components/schemas/CreatorLabel' type: array title: Labels description: >- Descriptive labels for the creator. Includes stable categories (type='category', use for filtering) and dynamic tags (type='tag'). See /media_categories for the full category taxonomy. tags: items: $ref: '#/components/schemas/CreatorTag' type: array title: Tags description: >- DEPRECATED: Use 'labels' instead. This field will be removed in a future version. deprecated: true creator_id: anyOf: - type: string - type: 'null' title: Creator Id description: >- Upriver creator ID. Present for any successful creator response, including provisional single-platform creators. Store and reuse this ID for consistency across API calls. emails: anyOf: - items: type: string type: array - type: 'null' title: Emails description: >- Public contact email addresses for the creator, if any are available. Returned only when requested via include=email. examples: - - press@creator.com redirect: anyOf: - $ref: '#/components/schemas/CreatorRedirectInfo' - type: 'null' description: >- Present when the requested creator_id has been merged into another creator. Clients should update any stored ID to `redirect.canonical_creator_id`. skipped_enrichments: anyOf: - $ref: '#/components/schemas/CreatorSkippedEnrichments' - type: 'null' description: >- Compact metadata for requested enrichments that were skipped and therefore omitted from their top-level keys. audience: anyOf: - $ref: '#/components/schemas/CreatorAudience' - type: 'null' description: >- Directional audience demographics. Only present when include=audience is specified. `age.min_age`/`max_age` is a directional envelope; `age.segments` contains explicit percentage buckets and may be partial. type: object title: CreatorGetResponse description: Response returned by the creator get endpoint. HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' type: array title: Detail type: object title: HTTPValidationError CreatorBio: properties: status: anyOf: - type: string enum: - full_coverage - limited_coverage - no_coverage - skipped - type: 'null' title: Status description: >- Coverage quality of this enrichment block. `full_coverage` means the research passed the reliability threshold and a clean result can be trusted as a real signal. `limited_coverage` means some evidence was found but below the reliability threshold — treat absent findings as unknown, not negative. `no_coverage` means research could not gather enough evidence to make a call. `skipped` means the account did not meet the minimum bar for this enrichment to return useful results — see `skip_reason` for details. skip_reason: anyOf: - $ref: '#/components/schemas/EnrichmentSkipReason' - type: 'null' description: >- Present only when `status` is `skipped`. Explains why this enrichment was not attempted. summary: anyOf: - type: string - type: 'null' title: Summary description: Short 2-3 sentence summary of the creator's background and focus. examples: - >- MrBeast is a YouTube creator known for expensive stunts and philanthropy. - >- Marques Brownlee is a tech reviewer focused on consumer electronics. type: object title: CreatorBio description: Biographical summary of a creator. CreatorPlatform: properties: platform: type: string title: Platform description: Platform identifier (e.g., youtube, x). handle: type: string title: Handle description: Canonical handle with required prefix. url: type: string minLength: 1 format: uri title: Url description: Primary profile URL for the platform. platform_id: anyOf: - type: string - type: 'null' title: Platform Id description: Native platform identifier (e.g., YouTube channel ID, Instagram pk). examples: - UCBcRF18a7Qf58cCRy5xuWwQ - '1234567890' display_name: anyOf: - type: string - type: 'null' title: Display Name description: The creator's display name or channel title. examples: - MrBeast - Lex Fridman - Colin and Samir channel_relationship: anyOf: - type: string enum: - attached - group - type: 'null' title: Channel Relationship description: >- Only present for non-primary channels. Omitted for channels the creator directly owns. 'attached' = a distinct show, brand, project, or publication surface closely associated with the creator (e.g. @Denki for Austin Evans). 'group' = a shared, joint, or collab surface the creator is part of (e.g. @samandcolby for Sam Golbach). examples: - attached - group profile_pic_url: anyOf: - type: string - type: 'null' title: Profile Pic Url description: Profile picture/avatar URL for the channel. examples: - https://yt3.ggpht.com/... - https://instagram.com/... subscriber_count: anyOf: - type: integer - type: 'null' title: Subscriber Count description: >- Subscriber/follower count for sorting and calculations. Only present for platforms that support subscriber counts. examples: - 4227 - 133017 - 1500000 - 51389232 subscriber_count_text: anyOf: - type: string - type: 'null' title: Subscriber Count Text description: >- Subscriber/follower count formatted for display. Only present for platforms that support subscriber counts. examples: - 4.2K - 133K - 1.5M - 51M follower_bucket: anyOf: - $ref: '#/components/schemas/FollowerBucket' - type: 'null' description: >- Advertiser-facing follower bucket derived from subscriber_count. Only present for platforms that support subscriber counts. engagement_metrics: anyOf: - $ref: '#/components/schemas/EngagementMetrics' - type: 'null' description: >- Engagement metrics from the most recent videos/posts. Includes average views, likes, comments, and engagement rate. video_metrics: anyOf: - $ref: '#/components/schemas/VideoMetrics' - type: 'null' description: >- Video-specific metrics for ad inventory estimation. Includes average duration, upload frequency, and optional lookback coverage metadata. Only present when include=video_metrics is specified. relative_metrics: anyOf: - $ref: '#/components/schemas/RelativeMetrics' - type: 'null' description: >- Public benchmark summaries relative to similar creators. Only present when include=relative_metrics is specified and benchmark data is available. type: object required: - platform - handle - url title: CreatorPlatform description: Primary social profile discovered for a creator. CreatorAssociatedCreator: properties: creator_id: type: string title: Creator Id description: Upriver creator ID for the associated creator cluster. examples: - cb4f53f0-c905-4c0a-86df-9a6c7551c408 creator_role: type: string enum: - surface - primary_creator - group - member - peer title: Creator Role description: >- Role of the associated creator cluster relative to the current creator. 'surface' = a distinct project, brand, or publication surface associated with this creator. 'primary_creator' = the main creator this cluster is a surface for. 'group' = a shared or collab cluster this creator is part of. 'member' = an individual creator who is part of this cluster. 'peer' = a co-equal shared-owner creator cluster. examples: - surface - primary_creator - group - member - peer type: object required: - creator_id - creator_role title: CreatorAssociatedCreator description: Reference to a related but separate creator cluster. CreatorLabel: properties: id: type: string title: Id description: Stable identifier. For categories, matches /media_categories IDs. examples: - beauty - skincare - clean-beauty-expert name: type: string title: Name description: Human-readable display name. examples: - Beauty - Skincare - Clean Beauty Expert type: type: string enum: - category - tag title: Type description: >- Label type: 'category' = stable taxonomy (filterable), 'tag' = dynamic descriptor. level: anyOf: - type: integer - type: 'null' title: Level description: >- Hierarchy level for categories: 1 = broad, 2 = specific. Null for tags. examples: - 1 - 2 parent_id: anyOf: - type: string - type: 'null' title: Parent Id description: Parent category ID for level-2 categories. Null for L1 and tags. examples: - beauty type: object required: - id - name - type title: CreatorLabel description: >- Descriptive label for a creator (category or tag). Labels come in two types: - `category`: Stable classifications from the taxonomy (see /media_categories). Use these for filtering. Categories have `level` (1=broad, 2=specific) and L2 categories include `parent_id` linking to their parent L1. - `tag`: Dynamic descriptors extracted for this creator. More specific but may vary over time. CreatorTag: properties: id: type: string title: Id description: Stable tag ID (taxonomy slug) name: type: string title: Name description: Human-readable display name for the tag type: object required: - id - name title: CreatorTag description: |- User-facing tag object for creator search results. Deprecated: Use CreatorLabel instead for richer metadata. CreatorRedirectInfo: properties: requested_creator_id: type: string title: Requested Creator Id description: The creator ID that was requested by the client. examples: - 97ca4d8c-c1b2-4c73-a4f0-7ac6bb05e0cf canonical_creator_id: type: string title: Canonical Creator Id description: The canonical creator ID clients should store going forward. examples: - cb4f53f0-c905-4c0a-86df-9a6c7551c408 reason: type: string title: Reason description: Why the requested ID resolved to a different canonical creator. default: merged examples: - merged type: object required: - requested_creator_id - canonical_creator_id title: CreatorRedirectInfo description: Metadata about a creator ID redirect/merge. examples: - canonical_creator_id: cb4f53f0-c905-4c0a-86df-9a6c7551c408 reason: merged requested_creator_id: 97ca4d8c-c1b2-4c73-a4f0-7ac6bb05e0cf CreatorSkippedEnrichments: properties: fields: items: type: string enum: - bio - audience - brand_safety type: array title: Fields description: >- Requested enrichment fields that were omitted because enrichment was deterministically skipped. reason: $ref: '#/components/schemas/EnrichmentSkipReason' description: Structured reason those enrichment fields were skipped. type: object required: - fields - reason title: CreatorSkippedEnrichments description: Compact metadata for omitted enrichment blocks. CreatorAudience: properties: status: anyOf: - type: string enum: - full_coverage - limited_coverage - no_coverage - skipped - type: 'null' title: Status description: >- Coverage quality of this enrichment block. `full_coverage` means the research passed the reliability threshold and a clean result can be trusted as a real signal. `limited_coverage` means some evidence was found but below the reliability threshold — treat absent findings as unknown, not negative. `no_coverage` means research could not gather enough evidence to make a call. `skipped` means the account did not meet the minimum bar for this enrichment to return useful results — see `skip_reason` for details. skip_reason: anyOf: - $ref: '#/components/schemas/EnrichmentSkipReason' - type: 'null' description: >- Present only when `status` is `skipped`. Explains why this enrichment was not attempted. description: anyOf: - type: string - type: 'null' title: Description description: Natural language description of the typical audience. examples: - Young female audience interested in comedy and lifestyle content. - Tech-savvy males aged 25-44 interested in gadgets and gaming. gender: anyOf: - $ref: '#/components/schemas/AudienceGender' - type: 'null' description: Gender distribution with confidence level. age: anyOf: - $ref: '#/components/schemas/AudienceAge' - type: 'null' description: Age distribution with optional segment breakdown. geography: anyOf: - $ref: '#/components/schemas/AudienceGeography' - type: 'null' description: Geographic distribution with optional country breakdown. languages: anyOf: - $ref: '#/components/schemas/AudienceLanguages' - type: 'null' description: Language distribution with optional language breakdown. type: object title: CreatorAudience description: >- Audience demographic information for a creator. All fields are **directional signals** — they indicate where the creator has significant audience presence, not exact analytics. Use these to answer "does this creator reach X demographic?" rather than "what is the exact breakdown?" Check the `confidence` field on each sub-object to gauge reliability. Demographic breakdowns (age segments, country percentages, language breakdown) are only included when explicit percentage data is available from analytics or research sources. When data is inferred without specific percentages, only primary directional fields and `confidence` are returned. Age contract: - `age.min_age` / `age.max_age`: directional envelope from all available evidence. - `age.segments`: explicit percentage buckets only. - These can coexist when percentages are partial; segments do not need to cover the full envelope or sum to 100. **With explicit analytics data** (high confidence): ```json { "description": "Young female audience interested in comedy and lifestyle.", "gender": {"value": "female", "percentage": 72, "confidence": "high"}, "age": { "min_age": 18, "max_age": 24, "segments": [ {"min_age": 18, "max_age": 24, "percentage": 45}, {"min_age": 25, "max_age": 34, "percentage": 30} ], "confidence": "high" }, "geography": { "countries": [ {"country": "US", "percentage": 65}, {"country": "GB", "percentage": 15} ], "international": true, "confidence": "high" }, "languages": { "value": "English", "breakdown": [ {"language": "English", "percentage": 85}, {"language": "Spanish", "percentage": 10} ], "confidence": "high" } } ``` **Without explicit data** (inferred, medium/low confidence): ```json { "description": "Young female audience interested in comedy and lifestyle.", "gender": {"value": "female", "confidence": "medium"}, "age": {"min_age": 18, "max_age": 24, "confidence": "medium"}, "geography": {"countries": [{"country": "US"}], "confidence": "medium"}, "languages": {"value": "English", "confidence": "high"} } ``` ValidationError: properties: loc: items: anyOf: - type: string - type: integer type: array title: Location msg: type: string title: Message type: type: string title: Error Type type: object required: - loc - msg - type title: ValidationError EnrichmentSkipReason: properties: code: type: string const: below_minimum_subscribers title: Code description: >- Machine-readable reason code. `below_minimum_subscribers` means the account's follower count is below the minimum where this enrichment reliably returns useful results. minimum_subscribers: type: integer title: Minimum Subscribers description: The minimum subscriber count required to attempt this enrichment. platform: type: string title: Platform description: Platform this threshold was evaluated against. type: object required: - code - minimum_subscribers - platform title: EnrichmentSkipReason description: Structured reason why an enrichment block was deterministically skipped. FollowerBucket: properties: id: type: string title: Id description: Stable follower bucket identifier. examples: - 10k_50k - 100k_300k - over_1m display: type: string title: Display description: Human-readable label for the follower bucket. examples: - 10K-50K followers - 100K-300K followers - 1M+ followers min_followers: type: integer minimum: 0 title: Min Followers description: Inclusive lower bound for the bucket. examples: - 10000 - 100000 - 1000000 max_followers: anyOf: - type: integer minimum: 0 - type: 'null' title: Max Followers description: Inclusive upper bound for the bucket, if finite. examples: - 49999 - 299999 - 999999 type: object required: - id - display - min_followers title: FollowerBucket description: Advertiser-facing follower bucket for a channel. EngagementMetrics: properties: avg_views: anyOf: - type: integer - type: 'null' title: Avg Views description: >- Average view count from recent content. On platforms with multiple upload formats, this blends across the supported formats. examples: - 125000 - 500000 - 2000000 avg_likes: anyOf: - type: integer - type: 'null' title: Avg Likes description: >- Average like count from recent content. On platforms with multiple upload formats, this blends across the supported formats. examples: - 5000 - 25000 - 100000 avg_comments: anyOf: - type: integer - type: 'null' title: Avg Comments description: >- Average comment count from recent content. On platforms with multiple upload formats, this blends across the supported formats. examples: - 500 - 2500 - 10000 avg_engagement_rate: anyOf: - type: number - type: 'null' title: Avg Engagement Rate description: >- Average engagement rate calculated as (likes + comments) / views. Expressed as a decimal (e.g., 0.05 = 5%). examples: - 0.05 - 0.1 - 0.15 type: object title: EngagementMetrics description: Engagement metrics from recent videos/posts. VideoMetrics: properties: avg_duration_seconds: anyOf: - type: integer - type: 'null' title: Avg Duration Seconds description: >- Average video duration in seconds from uploads inside the trailing 12-week long-form inventory window. Omitted from creator responses when no uploads fall inside the window. examples: - 600 - 120 - 45 uploads_per_week: anyOf: - type: number - type: 'null' title: Uploads Per Week description: >- Average number of uploads per week over the trailing 12-week inventory window for long-form uploads. When the creator has less history than the full lookback, the rate is calculated over the observed weeks and accompanied by coverage metadata. examples: - 1.5 - 3 - 7 pct_over_8m: anyOf: - type: number - type: 'null' title: Pct Over 8M description: >- Percentage of in-window videos with duration over 8 minutes (480 seconds). Videos over 8 minutes are eligible for mid-roll ads. Based on long-form uploads only. Omitted from creator responses when no uploads fall inside the window. examples: - 75 - 100 - 0 lookback_weeks: anyOf: - type: integer - type: 'null' title: Lookback Weeks description: >- Trailing lookback window used for advertiser inventory estimation. Currently fixed at 12 weeks in the public creator API. examples: - 12 weeks_observed: anyOf: - type: integer - type: 'null' title: Weeks Observed description: >- Number of weeks of upload history actually observed for the inventory calculation. Can be less than lookback_weeks for newer creators. examples: - 2 - 12 window_complete: anyOf: - type: boolean - type: 'null' title: Window Complete description: >- True when a full lookback window was observed. False when the creator has less than the full lookback of upload history. examples: - true - false type: object title: VideoMetrics description: >- Video-specific metrics for ad inventory estimation. Computed from the creator's trailing 12-week long-form upload window. Includes average duration (useful for estimating mid-roll ad slots), upload frequency, and coverage metadata describing how much recent history was actually observed. examples: - avg_duration_seconds: 615 lookback_weeks: 12 pct_over_8m: 66.7 uploads_per_week: 1.75 weeks_observed: 12 window_complete: true - lookback_weeks: 12 uploads_per_week: 0 weeks_observed: 12 window_complete: true - avg_duration_seconds: 420 lookback_weeks: 12 pct_over_8m: 25 uploads_per_week: 2.5 weeks_observed: 2 window_complete: false RelativeMetrics: properties: engagement: anyOf: - $ref: '#/components/schemas/RelativeEngagementMetrics' - type: 'null' description: >- Relative benchmark output for engagement metrics. Only present when benchmarks were available for the channel and engagement metrics. type: object title: RelativeMetrics description: Public benchmark summaries relative to similar creators. AudienceGender: properties: value: anyOf: - type: string enum: - male - female - balanced - type: 'null' title: Value description: 'Gender skew: male, female, balanced (45-55%), or null.' examples: - female - male - balanced percentage: anyOf: - type: integer - type: 'null' title: Percentage description: >- Percentage of primary gender (0-100). Only present when explicit analytics data is available. examples: - 72 - 65 - 55 confidence: type: string enum: - low - medium - high title: Confidence description: Confidence level based on data source quality. default: medium type: object title: AudienceGender description: >- Gender distribution with confidence. The `percentage` field is only included when explicit numerical data exists. When gender skew is inferred without specific percentages (e.g., "female-leaning"), only `value` and `confidence` are returned. Values: - "male"/"female": audience skews this direction - "balanced": roughly even split (45-55%), backed by evidence - null: unknown / insufficient data Example with explicit data: {"value": "female", "percentage": 72, "confidence": "high"} Example without explicit data: {"value": "female", "confidence": "medium"} AudienceAge: properties: min_age: anyOf: - type: integer - type: 'null' title: Min Age description: >- Primary directional envelope lower bound (inclusive), null if unbounded. May be broader than quantified segments. examples: - 13 - 18 - 25 max_age: anyOf: - type: integer - type: 'null' title: Max Age description: >- Primary directional envelope upper bound (inclusive), null if unbounded. May be broader than quantified segments. examples: - 24 - 34 - 44 segments: anyOf: - items: $ref: '#/components/schemas/AudienceAgeSegment' type: array - type: 'null' title: Segments description: >- Explicit percentage breakdown by age range. May be partial and not exhaustive. confidence: type: string enum: - low - medium - high title: Confidence description: Confidence level based on data source quality. default: medium type: object title: AudienceAge description: >- Age distribution with confidence. The `min_age`/`max_age` range is a directional envelope where the creator has meaningful audience concentration. It is not an exact analytics breakdown. The `segments` field contains only explicit percentage buckets from grounded data. Segments may be partial: they do not need to cover the full `min_age`/`max_age` envelope and do not need to sum to 100. When both are present: - `min_age`/`max_age` gives broad directional context - `segments` gives the quantified subset with explicit percentages When only one data type is available, the other may be omitted. Example with explicit data: { "min_age": 18, "max_age": 24, "segments": [ {"min_age": 18, "max_age": 24, "percentage": 45}, {"min_age": 25, "max_age": 34, "percentage": 30} ], "confidence": "high" } Example without explicit data: {"min_age": 18, "max_age": 24, "confidence": "medium"} Example with partial segments: { "min_age": 18, "max_age": 34, "segments": [ {"min_age": 24, "max_age": 29, "percentage": 40}, {"min_age": 30, "max_age": 34, "percentage": 30} ], "confidence": "medium" } Example unbounded: {"min_age": 55, "confidence": "medium"} (55+) AudienceGeography: properties: countries: anyOf: - items: $ref: '#/components/schemas/AudienceCountrySegment' type: array - type: 'null' title: Countries description: >- Countries where the creator has significant audience presence, as ISO codes. Order is approximate, not a strict ranking. This list may not be exhaustive — absence of a country does not mean the creator has no audience there. Percentage is included only when grounded data is available. international: anyOf: - type: boolean - type: 'null' title: International description: >- True if meaningful audience outside primary country, false if concentrated in one country, null if unknown. confidence: type: string enum: - low - medium - high title: Confidence description: Confidence level based on data source quality. default: medium type: object title: AudienceGeography description: |- Geographic distribution with confidence. The `countries` field lists countries where the creator has significant audience presence — NOT necessarily ranked by dominance. Ordering is approximate and should not be treated as a strict ranking. This list may not be exhaustive; absence of a country does not mean the creator has no audience there. Use this to answer "does this creator reach audiences in X?" rather than "what is their #1 country?" Percentage is included only when grounded analytics data exists. Example with percentages: { "countries": [ {"country": "US", "percentage": 65}, {"country": "GB", "percentage": 15} ], "international": true, "confidence": "high" } Example without percentages (countries still listed): { "countries": [{"country": "US"}, {"country": "GB"}], "international": true, "confidence": "medium" } AudienceLanguages: properties: value: type: string title: Value description: Primary language. examples: - English - Spanish - Portuguese breakdown: anyOf: - items: $ref: '#/components/schemas/AudienceLanguageSegment' type: array - type: 'null' title: Breakdown description: >- Breakdown by language with percentages. Only present when explicit analytics data is available. confidence: type: string enum: - low - medium - high title: Confidence description: Confidence level based on data source quality. default: medium type: object required: - value title: AudienceLanguages description: >- Language distribution with confidence. The `breakdown` field is only included when explicit percentage data exists. When language is inferred without specific breakdowns, only `value` and `confidence` are returned. Example with explicit data: { "value": "English", "breakdown": [ {"language": "English", "percentage": 85}, {"language": "Spanish", "percentage": 10} ], "confidence": "high" } Example without explicit data: {"value": "English", "confidence": "high"} RelativeEngagementMetrics: properties: benchmark_basis: $ref: '#/components/schemas/RelativeMetricBenchmarkBasis' description: Public explanation of the cohort used for engagement metrics. avg_views: anyOf: - $ref: '#/components/schemas/RelativeMetricSignal' - type: 'null' description: Relative benchmark for average views. avg_engagement_rate: anyOf: - $ref: '#/components/schemas/RelativeMetricSignal' - type: 'null' description: Relative benchmark for average engagement rate. type: object required: - benchmark_basis title: RelativeEngagementMetrics description: Relative benchmark output for engagement metrics. AudienceAgeSegment: properties: min_age: anyOf: - type: integer - type: 'null' title: Min Age description: Lower bound (inclusive), null if unbounded below. examples: - 13 - 18 - 25 - 35 - 45 - 55 max_age: anyOf: - type: integer - type: 'null' title: Max Age description: Upper bound (inclusive), null if unbounded above. examples: - 17 - 24 - 34 - 44 - 54 percentage: type: integer maximum: 100 minimum: 0 title: Percentage description: Percentage of audience in this age range. examples: - 45 - 30 - 15 type: object required: - percentage title: AudienceAgeSegment description: Age segment with percentage breakdown. AudienceCountrySegment: properties: country: type: string title: Country description: ISO 3166-1 alpha-2 country code. examples: - US - GB - CA - BR country_name: anyOf: - type: string - type: 'null' title: Country Name description: Human-readable country name derived from ISO code. examples: - United States - United Kingdom percentage: anyOf: - type: integer maximum: 100 minimum: 0 - type: 'null' title: Percentage description: Percentage of audience in this country, if known. examples: - 65 - 15 - 10 type: object required: - country title: AudienceCountrySegment description: Country segment with optional percentage breakdown. AudienceLanguageSegment: properties: language: type: string title: Language description: Language name. examples: - English - Spanish - Portuguese percentage: type: integer maximum: 100 minimum: 0 title: Percentage description: Percentage of audience using this language. examples: - 85 - 10 - 5 type: object required: - language - percentage title: AudienceLanguageSegment description: Language segment with percentage breakdown. RelativeMetricBenchmarkBasis: properties: platform: type: string title: Platform description: Platform used for the benchmark cohort. examples: - youtube - instagram follower_bucket_id: type: string title: Follower Bucket Id description: Follower bucket identifier used for the benchmark cohort. examples: - 50k_100k - 100k_300k specificity: type: string enum: - follower_bucket - follower_bucket_content_category title: Specificity description: How specific the benchmark cohort was. benchmark_date: type: string title: Benchmark Date description: Date the benchmark snapshot was computed. examples: - '2026-03-17' content_category: anyOf: - $ref: '#/components/schemas/RelativeMetricContentCategory' - type: 'null' description: >- Content category used for the benchmark cohort when a category-specific comparison was available. type: object required: - platform - follower_bucket_id - specificity - benchmark_date title: RelativeMetricBenchmarkBasis description: Public explanation of which peer cohort powered a benchmark. RelativeMetricSignal: properties: band: type: string enum: - bottom_25 - mid_50 - top_25 title: Band description: Coarse benchmark band relative to similar creators. type: object required: - band title: RelativeMetricSignal description: Public-facing benchmark summary for a single metric. RelativeMetricContentCategory: properties: id: type: string title: Id description: Category identifier from the creator taxonomy. examples: - sports - nfl - beauty name: type: string title: Name description: Human-readable category name. examples: - Sports - NFL - Beauty type: object required: - id - name title: RelativeMetricContentCategory description: Content category actually used in a public benchmark basis. securitySchemes: APIKeyHeader: type: apiKey in: header name: X-API-Key ````