Skip to content
UpriverUpriverUpriver API Docs

Creator Profile by ID

v1.0.0
OpenAPI 3.1.0

Upriver API

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.

Server:https://api.upriver.ai

Production API server

Client Libraries
Shell Curl

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.

Path Parameters
  • creator_id
    Type: string · Creator Id
    required
Query Parameters
  • include
    Type: array string[] · Include

    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
  • application/json
  • application/json
Request Example for get/v1/creators/{creator_id}
curl 'https://api.upriver.ai/v1/creators/{creator_id}' \
  --header 'X-API-Key: YOUR_SECRET_TOKEN'

{
  "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"
  }
}

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.