{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/upriver-ai/json-schema/upriver-ai-creator-get-response-schema.json",
  "title": "CreatorGetResponse",
  "description": "Response returned by the creator get endpoint.",
  "x-generated": "2026-10-31",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/upriver-ai-openapi.json#/components/schemas/CreatorGetResponse",
  "properties": {
    "bio": {
      "anyOf": [
        {
          "$ref": "#/$defs/CreatorBio"
        },
        {
          "type": "null"
        }
      ],
      "description": "Biographical summary of the creator. Only present when include=bio is specified."
    },
    "channels": {
      "items": {
        "$ref": "#/$defs/CreatorPlatform"
      },
      "type": "array",
      "title": "Channels",
      "description": "Social media channels for the creator across supported platforms."
    },
    "associated_creators": {
      "items": {
        "$ref": "#/$defs/CreatorAssociatedCreator"
      },
      "type": "array",
      "title": "Associated Creators",
      "description": "Distinct associated creator clusters related to this creator."
    },
    "labels": {
      "items": {
        "$ref": "#/$defs/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": "#/$defs/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."
    },
    "location": {
      "anyOf": [
        {
          "$ref": "#/$defs/CreatorLocation"
        },
        {
          "type": "null"
        }
      ],
      "description": "Only returned for exact lookups with include=location. Reconciles current location separately from origin. Birthplace or nationality alone can provide a low-confidence fallback, never a confirmed residence. This expansion does not change country-filter matching."
    },
    "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."
    },
    "redirect": {
      "anyOf": [
        {
          "$ref": "#/$defs/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": "#/$defs/CreatorSkippedEnrichments"
        },
        {
          "type": "null"
        }
      ],
      "description": "Compact metadata for requested enrichments that were skipped and therefore omitted from their top-level keys."
    },
    "audience": {
      "anyOf": [
        {
          "$ref": "#/$defs/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",
  "$defs": {
    "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."
        },
        "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."
        },
        "segments": {
          "anyOf": [
            {
              "items": {
                "$ref": "#/$defs/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.\n\nThe `min_age`/`max_age` range is a directional envelope where the creator\nhas meaningful audience concentration. It is not an exact analytics\nbreakdown.\n\nThe `segments` field contains only explicit percentage buckets from grounded\ndata. Segments may be partial: they do not need to cover the full\n`min_age`/`max_age` envelope and do not need to sum to 100.\n\nWhen both are present:\n- `min_age`/`max_age` gives broad directional context\n- `segments` gives the quantified subset with explicit percentages\n\nWhen only one data type is available, the other may be omitted.\n\nExample with explicit data:\n    {\n      \"min_age\": 18, \"max_age\": 24,\n      \"segments\": [\n        {\"min_age\": 18, \"max_age\": 24, \"percentage\": 45},\n        {\"min_age\": 25, \"max_age\": 34, \"percentage\": 30}\n      ],\n      \"confidence\": \"high\"\n    }\n\nExample without explicit data:\n    {\"min_age\": 18, \"max_age\": 24, \"confidence\": \"medium\"}\n\nExample with partial segments:\n    {\n      \"min_age\": 18, \"max_age\": 34,\n      \"segments\": [\n        {\"min_age\": 24, \"max_age\": 29, \"percentage\": 40},\n        {\"min_age\": 30, \"max_age\": 34, \"percentage\": 30}\n      ],\n      \"confidence\": \"medium\"\n    }\n\nExample unbounded:\n    {\"min_age\": 55, \"confidence\": \"medium\"}  (55+)"
    },
    "AudienceAgeSegment": {
      "properties": {
        "min_age": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "title": "Min Age",
          "description": "Lower bound (inclusive), null if unbounded below."
        },
        "max_age": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "title": "Max Age",
          "description": "Upper bound (inclusive), null if unbounded above."
        },
        "percentage": {
          "type": "integer",
          "maximum": 100.0,
          "minimum": 0.0,
          "title": "Percentage",
          "description": "Percentage of audience in this age range."
        }
      },
      "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."
        },
        "country_name": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Country Name",
          "description": "Human-readable country name derived from ISO code."
        },
        "percentage": {
          "anyOf": [
            {
              "type": "integer",
              "maximum": 100.0,
              "minimum": 0.0
            },
            {
              "type": "null"
            }
          ],
          "title": "Percentage",
          "description": "Percentage of audience in this country, if known."
        }
      },
      "type": "object",
      "required": [
        "country"
      ],
      "title": "AudienceCountrySegment",
      "description": "Country segment with optional percentage breakdown."
    },
    "AudienceGender": {
      "properties": {
        "value": {
          "anyOf": [
            {
              "type": "string",
              "enum": [
                "male",
                "female",
                "balanced"
              ]
            },
            {
              "type": "null"
            }
          ],
          "title": "Value",
          "description": "Gender skew: male, female, balanced (45-55%), or null."
        },
        "percentage": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "title": "Percentage",
          "description": "Percentage of primary gender (0-100). 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",
      "title": "AudienceGender",
      "description": "Gender distribution with confidence.\n\nThe `percentage` field is only included when explicit numerical data exists.\nWhen gender skew is inferred without specific percentages (e.g., \"female-leaning\"),\nonly `value` and `confidence` are returned.\n\nValues:\n  - \"male\"/\"female\": audience skews this direction\n  - \"balanced\": roughly even split (45-55%), backed by evidence\n  - null: unknown / insufficient data\n\nExample with explicit data:\n    {\"value\": \"female\", \"percentage\": 72, \"confidence\": \"high\"}\n\nExample without explicit data:\n    {\"value\": \"female\", \"confidence\": \"medium\"}"
    },
    "AudienceGeography": {
      "properties": {
        "countries": {
          "anyOf": [
            {
              "items": {
                "$ref": "#/$defs/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.\n\nThe `countries` field lists countries where the creator has significant\naudience presence — NOT necessarily ranked by dominance. Ordering is\napproximate and should not be treated as a strict ranking. This list\nmay not be exhaustive; absence of a country does not mean the creator\nhas no audience there. Use this to answer \"does this creator reach\naudiences in X?\" rather than \"what is their #1 country?\"\n\nPercentage is included only when grounded analytics data exists.\n\nExample with percentages:\n    {\n      \"countries\": [\n        {\"country\": \"US\", \"percentage\": 65},\n        {\"country\": \"GB\", \"percentage\": 15}\n      ],\n      \"international\": true,\n      \"confidence\": \"high\"\n    }\n\nExample without percentages (countries still listed):\n    {\n      \"countries\": [{\"country\": \"US\"}, {\"country\": \"GB\"}],\n      \"international\": true,\n      \"confidence\": \"medium\"\n    }"
    },
    "AudienceLanguageSegment": {
      "properties": {
        "language": {
          "type": "string",
          "title": "Language",
          "description": "Language name."
        },
        "percentage": {
          "type": "integer",
          "maximum": 100.0,
          "minimum": 0.0,
          "title": "Percentage",
          "description": "Percentage of audience using this language."
        }
      },
      "type": "object",
      "required": [
        "language",
        "percentage"
      ],
      "title": "AudienceLanguageSegment",
      "description": "Language segment with percentage breakdown."
    },
    "AudienceLanguages": {
      "properties": {
        "value": {
          "type": "string",
          "title": "Value",
          "description": "Primary language."
        },
        "breakdown": {
          "anyOf": [
            {
              "items": {
                "$ref": "#/$defs/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.\n\nThe `breakdown` field is only included when explicit percentage data exists.\nWhen language is inferred without specific breakdowns, only `value` and\n`confidence` are returned.\n\nExample with explicit data:\n    {\n      \"value\": \"English\",\n      \"breakdown\": [\n        {\"language\": \"English\", \"percentage\": 85},\n        {\"language\": \"Spanish\", \"percentage\": 10}\n      ],\n      \"confidence\": \"high\"\n    }\n\nExample without explicit data:\n    {\"value\": \"English\", \"confidence\": \"high\"}"
    },
    "CreatorAssociatedCreator": {
      "properties": {
        "creator_id": {
          "type": "string",
          "title": "Creator Id",
          "description": "Upriver creator ID for the associated creator cluster."
        },
        "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."
        }
      },
      "type": "object",
      "required": [
        "creator_id",
        "creator_role"
      ],
      "title": "CreatorAssociatedCreator",
      "description": "Reference to a related but separate creator cluster."
    },
    "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": "#/$defs/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."
        },
        "gender": {
          "anyOf": [
            {
              "$ref": "#/$defs/AudienceGender"
            },
            {
              "type": "null"
            }
          ],
          "description": "Gender distribution with confidence level."
        },
        "age": {
          "anyOf": [
            {
              "$ref": "#/$defs/AudienceAge"
            },
            {
              "type": "null"
            }
          ],
          "description": "Age distribution with optional segment breakdown."
        },
        "geography": {
          "anyOf": [
            {
              "$ref": "#/$defs/AudienceGeography"
            },
            {
              "type": "null"
            }
          ],
          "description": "Geographic distribution with optional country breakdown."
        },
        "languages": {
          "anyOf": [
            {
              "$ref": "#/$defs/AudienceLanguages"
            },
            {
              "type": "null"
            }
          ],
          "description": "Language distribution with optional language breakdown."
        }
      },
      "type": "object",
      "title": "CreatorAudience",
      "description": "Audience demographic information for a creator.\n\nAll fields are **directional signals** — they indicate where the creator\nhas significant audience presence, not exact analytics. Use these to answer\n\"does this creator reach X demographic?\" rather than \"what is the exact\nbreakdown?\" Check the `confidence` field on each sub-object to gauge\nreliability.\n\nDemographic breakdowns (age segments, country percentages, language\nbreakdown) are only included when explicit percentage data is available from\nanalytics or research sources. When data is inferred without specific\npercentages, only primary directional fields and `confidence` are returned.\n\nAge contract:\n- `age.min_age` / `age.max_age`: directional envelope from all available\n  evidence.\n- `age.segments`: explicit percentage buckets only.\n- These can coexist when percentages are partial; segments do not need to\n  cover the full envelope or sum to 100.\n\n**With explicit analytics data** (high confidence):\n```json\n{\n  \"description\": \"Young female audience interested in comedy and lifestyle.\",\n  \"gender\": {\"value\": \"female\", \"percentage\": 72, \"confidence\": \"high\"},\n  \"age\": {\n    \"min_age\": 18, \"max_age\": 24,\n    \"segments\": [\n      {\"min_age\": 18, \"max_age\": 24, \"percentage\": 45},\n      {\"min_age\": 25, \"max_age\": 34, \"percentage\": 30}\n    ],\n    \"confidence\": \"high\"\n  },\n  \"geography\": {\n    \"countries\": [\n      {\"country\": \"US\", \"percentage\": 65},\n      {\"country\": \"GB\", \"percentage\": 15}\n    ],\n    \"international\": true,\n    \"confidence\": \"high\"\n  },\n  \"languages\": {\n    \"value\": \"English\",\n    \"breakdown\": [\n      {\"language\": \"English\", \"percentage\": 85},\n      {\"language\": \"Spanish\", \"percentage\": 10}\n    ],\n    \"confidence\": \"high\"\n  }\n}\n```\n\n**Without explicit data** (inferred, medium/low confidence):\n```json\n{\n  \"description\": \"Young female audience interested in comedy and lifestyle.\",\n  \"gender\": {\"value\": \"female\", \"confidence\": \"medium\"},\n  \"age\": {\"min_age\": 18, \"max_age\": 24, \"confidence\": \"medium\"},\n  \"geography\": {\"countries\": [{\"country\": \"US\"}], \"confidence\": \"medium\"},\n  \"languages\": {\"value\": \"English\", \"confidence\": \"high\"}\n}\n```"
    },
    "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": "#/$defs/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."
        }
      },
      "type": "object",
      "title": "CreatorBio",
      "description": "Biographical summary of a creator."
    },
    "CreatorLabel": {
      "properties": {
        "id": {
          "type": "string",
          "title": "Id",
          "description": "Stable identifier. For categories, matches /media_categories IDs."
        },
        "name": {
          "type": "string",
          "title": "Name",
          "description": "Human-readable display name."
        },
        "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."
        },
        "parent_id": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Parent Id",
          "description": "Parent category ID for level-2 categories. Null for L1 and tags."
        }
      },
      "type": "object",
      "required": [
        "id",
        "name",
        "type"
      ],
      "title": "CreatorLabel",
      "description": "Descriptive label for a creator (category or tag).\n\nLabels come in two types:\n- `category`: Stable classifications from the taxonomy (see /media_categories).\n  Use these for filtering. Categories have `level` (1=broad, 2=specific) and\n  L2 categories include `parent_id` linking to their parent L1.\n- `tag`: Dynamic descriptors extracted for this creator. More specific but\n  may vary over time."
    },
    "CreatorLocation": {
      "properties": {
        "current_location": {
          "anyOf": [
            {
              "$ref": "#/$defs/CreatorLocationCandidate"
            },
            {
              "type": "null"
            }
          ]
        },
        "origins": {
          "items": {
            "$ref": "#/$defs/CreatorOriginEvidence"
          },
          "type": "array",
          "title": "Origins"
        },
        "status": {
          "type": "string",
          "enum": [
            "resolved",
            "unknown",
            "conflicting"
          ],
          "title": "Status",
          "description": "Whether one current-location candidate could be selected. Conflicting evidence leaves current_location empty. Resolved does not imply certainty."
        }
      },
      "type": "object",
      "required": [
        "status"
      ],
      "title": "CreatorLocation"
    },
    "CreatorLocationCandidate": {
      "properties": {
        "country": {
          "type": "string",
          "title": "Country",
          "description": "ISO 3166-1 alpha-2 country code."
        },
        "confidence": {
          "type": "string",
          "enum": [
            "high",
            "medium",
            "low"
          ],
          "title": "Confidence"
        },
        "source": {
          "type": "string",
          "enum": [
            "current_evidence",
            "origin_fallback"
          ],
          "title": "Source",
          "description": "Whether the result uses current-location evidence or a weak origin-based inference. An origin fallback does not establish current residence."
        }
      },
      "type": "object",
      "required": [
        "country",
        "confidence",
        "source"
      ],
      "title": "CreatorLocationCandidate"
    },
    "CreatorOriginEvidence": {
      "properties": {
        "country": {
          "type": "string",
          "title": "Country",
          "description": "ISO 3166-1 alpha-2 country code."
        },
        "basis": {
          "type": "string",
          "enum": [
            "birthplace",
            "nationality",
            "heritage",
            "departed",
            "unknown"
          ],
          "title": "Basis"
        }
      },
      "type": "object",
      "required": [
        "country",
        "basis"
      ],
      "title": "CreatorOriginEvidence"
    },
    "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)."
        },
        "display_name": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Display Name",
          "description": "The creator's display name or channel title."
        },
        "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)."
        },
        "profile_pic_url": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Profile Pic Url",
          "description": "Short-lived URL for the channel's profile picture. Fetch a new creator result after the URL expires; previously downloaded image bytes may be cached by the client."
        },
        "subscriber_count": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "title": "Subscriber Count",
          "description": "Most recently observed subscriber/follower count for sorting and calculations. Only present for platforms that support subscriber counts."
        },
        "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."
        },
        "follower_bucket": {
          "anyOf": [
            {
              "$ref": "#/$defs/FollowerBucket"
            },
            {
              "type": "null"
            }
          ],
          "description": "Advertiser-facing follower bucket derived from subscriber_count. Only present for platforms that support subscriber counts."
        },
        "engagement_metrics": {
          "anyOf": [
            {
              "$ref": "#/$defs/EngagementMetrics"
            },
            {
              "type": "null"
            }
          ],
          "description": "Engagement metrics from the most recent videos/posts. Includes average views, likes, comments, and engagement rate."
        },
        "video_metrics": {
          "anyOf": [
            {
              "$ref": "#/$defs/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": "#/$defs/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."
    },
    "CreatorRedirectInfo": {
      "properties": {
        "requested_creator_id": {
          "type": "string",
          "title": "Requested Creator Id",
          "description": "The creator ID that was requested by the client."
        },
        "canonical_creator_id": {
          "type": "string",
          "title": "Canonical Creator Id",
          "description": "The canonical creator ID clients should store going forward."
        },
        "reason": {
          "type": "string",
          "title": "Reason",
          "description": "Why the requested ID resolved to a different canonical creator.",
          "default": "merged"
        }
      },
      "type": "object",
      "required": [
        "requested_creator_id",
        "canonical_creator_id"
      ],
      "title": "CreatorRedirectInfo",
      "description": "Metadata about a creator ID redirect/merge."
    },
    "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": "#/$defs/EnrichmentSkipReason",
          "description": "Structured reason those enrichment fields were skipped."
        }
      },
      "type": "object",
      "required": [
        "fields",
        "reason"
      ],
      "title": "CreatorSkippedEnrichments",
      "description": "Compact metadata for omitted enrichment blocks."
    },
    "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.\n\nDeprecated: Use CreatorLabel instead for richer metadata."
    },
    "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."
        },
        "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."
        },
        "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."
        },
        "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%)."
        }
      },
      "type": "object",
      "title": "EngagementMetrics",
      "description": "Engagement metrics from recent videos/posts."
    },
    "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."
        },
        "display": {
          "type": "string",
          "title": "Display",
          "description": "Human-readable label for the follower bucket."
        },
        "min_followers": {
          "type": "integer",
          "minimum": 0.0,
          "title": "Min Followers",
          "description": "Inclusive lower bound for the bucket."
        },
        "max_followers": {
          "anyOf": [
            {
              "type": "integer",
              "minimum": 0.0
            },
            {
              "type": "null"
            }
          ],
          "title": "Max Followers",
          "description": "Inclusive upper bound for the bucket, if finite."
        }
      },
      "type": "object",
      "required": [
        "id",
        "display",
        "min_followers"
      ],
      "title": "FollowerBucket",
      "description": "Advertiser-facing follower bucket for a channel."
    },
    "RelativeEngagementMetrics": {
      "properties": {
        "benchmark_basis": {
          "$ref": "#/$defs/RelativeMetricBenchmarkBasis",
          "description": "Public explanation of the cohort used for engagement metrics."
        },
        "avg_views": {
          "anyOf": [
            {
              "$ref": "#/$defs/RelativeMetricSignal"
            },
            {
              "type": "null"
            }
          ],
          "description": "Relative benchmark for average views."
        },
        "avg_engagement_rate": {
          "anyOf": [
            {
              "$ref": "#/$defs/RelativeMetricSignal"
            },
            {
              "type": "null"
            }
          ],
          "description": "Relative benchmark for average engagement rate."
        }
      },
      "type": "object",
      "required": [
        "benchmark_basis"
      ],
      "title": "RelativeEngagementMetrics",
      "description": "Relative benchmark output for engagement metrics."
    },
    "RelativeMetricBenchmarkBasis": {
      "properties": {
        "platform": {
          "type": "string",
          "title": "Platform",
          "description": "Platform used for the benchmark cohort."
        },
        "follower_bucket_id": {
          "type": "string",
          "title": "Follower Bucket Id",
          "description": "Follower bucket identifier used for the benchmark cohort."
        },
        "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."
        },
        "content_category": {
          "anyOf": [
            {
              "$ref": "#/$defs/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."
    },
    "RelativeMetricContentCategory": {
      "properties": {
        "id": {
          "type": "string",
          "title": "Id",
          "description": "Category identifier from the creator taxonomy."
        },
        "name": {
          "type": "string",
          "title": "Name",
          "description": "Human-readable category name."
        }
      },
      "type": "object",
      "required": [
        "id",
        "name"
      ],
      "title": "RelativeMetricContentCategory",
      "description": "Content category actually used in a public benchmark basis."
    },
    "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."
    },
    "RelativeMetrics": {
      "properties": {
        "engagement": {
          "anyOf": [
            {
              "$ref": "#/$defs/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."
    },
    "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."
        },
        "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."
        },
        "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."
        },
        "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."
        },
        "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."
        },
        "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."
        }
      },
      "type": "object",
      "title": "VideoMetrics",
      "description": "Video-specific metrics for ad inventory estimation.\n\nComputed from the creator's trailing 12-week long-form upload window. Includes\naverage duration (useful for estimating mid-roll ad slots), upload\nfrequency, and coverage metadata describing how much recent history\nwas actually observed."
    }
  }
}