Schema preview Draft
Profile schema (draft)
A public account (creator, channel, page, company or community) with its bio, links and follower metrics.
Draft: not yet available. No endpoint returns profiles yet. This schema may change before the first endpoint ships; don't build against it.
Draft schema
When profile endpoints ship, they will return objects shaped like this as data, next to the standard meta, the same on every platform.
| Field | Type | Description |
|---|---|---|
platform | string | Platform ID (tiktok, youtube, …). |
id | string | Platform-native account ID (string; YouTube UC…, Reddit without t2_). |
username | string or null | Handle without the @; null when the account has none. |
display_name | string or null | Display name, channel title or page name. |
url | string (uri) | Canonical profile URL. |
type | string | Coarse account kind. New values may be added; treat unknown values as unknown. One of person, organization, community, unknown |
bio | string or null | Profile bio, channel description or page about text. |
avatar_url | string (uri) or null | Profile picture URL (largest available). Platform CDN URLs can expire within hours. |
banner_url | string (uri) or null | Header or cover image URL. |
is_verified | boolean or null | Platform verification badge; null where the platform has no badge. |
is_private | boolean or null | True when the account's posts are not public. |
category | string or null | Platform category label (e.g. Musician), as shown; not normalized. |
external_links | object[] | Links in the bio or channel links; [] if none. |
external_links[].url | string (uri) | Link target. |
external_links[].title | string or null | Link label shown by the platform. |
location | string or null | Self-declared location text. |
country_code | string or null | ISO 3166-1 alpha-2 country the platform states for the account. |
created_at | string (date-time) or null | Account creation or join date, RFC 3339 UTC (often date-only: see approximate_fields). |
metrics | object | Counts at fetch time; null = hidden or not exposed, 0 = zero. |
metrics.follower_count | integer or null | Followers or subscribers. |
metrics.following_count | integer or null | Accounts this profile follows. |
metrics.post_count | integer or null | Public posts or videos. |
metrics.total_like_count | integer or null | Likes received across all of the profile's posts (not likes given). |
metrics.total_view_count | integer or null | Lifetime views across all of the profile's posts. |
approximate_fields | string[] | JSON paths of values rounded by the platform or parsed from display text (e.g. metrics.follower_count); [] when all exact. |
Item errors
Planned item-level errors, besides the request-level errors:
| Code | HTTP | Retry | Meaning | What to do |
|---|---|---|---|---|
not_found | 404 | No | The item does not exist or was deleted. | Check the URL or ID; do not retry. |
private_or_unavailable | 403 | No | The item exists but is private, age- or region-gated, or requires a login to view. | Only public items can be fetched; do not retry. |