> ## 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. # Batch Creator Details > 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. ## OpenAPI ````yaml /api-reference/openapi.json post /v1/creators/batch 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/batch: post: tags: - Creators summary: Batch Creator Details description: >- 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. operationId: creator_batch requestBody: content: application/json: schema: $ref: '#/components/schemas/CreatorBatchInput' required: true responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/CreatorBatchResponse' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' security: - APIKeyHeader: [] components: schemas: CreatorBatchInput: properties: urls: items: type: string type: array maxItems: 10 minItems: 1 title: Urls description: >- Known social media profile URLs for the creators. Example: https://youtube.com/@handle examples: - - https://youtube.com/@MrBeast - https://youtube.com/@MKBHD - https://youtube.com/@CelineDept type: object required: - urls title: CreatorBatchInput description: Input payload for batch creator lookup. CreatorBatchResponse: properties: results: items: $ref: '#/components/schemas/CreatorBatchItemResult' type: array title: Results description: Results for each URL in the same order as the input. successful_count: type: integer title: Successful Count description: Number of URLs successfully resolved. failed_count: type: integer title: Failed Count description: Number of URLs that failed to resolve. type: object required: - results - successful_count - failed_count title: CreatorBatchResponse description: Response for batch creator lookup. HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' type: array title: Detail type: object title: HTTPValidationError CreatorBatchItemResult: properties: url: type: string title: Url description: The input URL for this result. channels: anyOf: - items: $ref: '#/components/schemas/CreatorPlatform' type: array - type: 'null' title: Channels description: >- Social media channels for the creator across supported platforms. Present on success. associated_creators: anyOf: - items: $ref: '#/components/schemas/CreatorAssociatedCreator' type: array - type: 'null' title: Associated Creators description: >- Distinct associated creator clusters related to this creator. Present on success. labels: anyOf: - items: $ref: '#/components/schemas/CreatorLabel' type: array - type: 'null' title: Labels description: >- Descriptive labels for the creator. Includes stable categories (type='category') and dynamic tags (type='tag'). Present on success. tags: anyOf: - items: $ref: '#/components/schemas/CreatorTag' type: array - type: 'null' 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 on successful results, including provisional single-platform creators. error: anyOf: - type: string - type: 'null' title: Error description: Error message. Present on failure. type: object required: - url title: CreatorBatchItemResult description: |- Result for a single URL in the batch response. On success: contains url, channels, labels, tags (no error field). On failure: contains url, error (no channels/labels/tags fields). 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 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. 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. 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. 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 ````