InsightSocial APIUnified schema
Author
The unified author and profile object. Every field, its type, and which platforms fill it.
Any endpoint that returns a profile, creator, page or channel returns it in this shape, whichever platform it came from. One parser reads authors from every platform.
Fields
| Field | Type | Nullable | Description |
|---|---|---|---|
id | string | No | The platform's ID for the account, always as a string. Platform prefixes such as Reddit's t2_ are removed. |
username | string | Yes | Handle. |
display_name | string | Yes | Display name or full name. |
avatar_url | string | Yes | Profile picture. |
bio | string | Yes | Bio or description. |
verified | boolean | Yes | Whether the account is verified. |
followers | integer | Yes | Followers or subscribers, as a whole number. Exact on Instagram, and on TikTok when an unrounded figure is available. On YouTube above 1,000 subscribers it is the rounded figure YouTube publishes (three significant digits). Whenever the number is rounded, ext.followers_approximate is true. |
following | integer | Yes | Accounts this account follows. |
posts_count | integer | Yes | Total posts or videos. |
likes_count | integer | Yes | Total likes received across the account's content, where shown. |
url | string | Yes | Link to the profile. |
location | string | Yes | An ISO region code such as US, or free-text location, where shown. |
external_url | string | Yes | Website or bio link, where shown. |
private | boolean | Yes | Whether the account is private. |
joined_at | string | Yes | When the account was created. |
last_post_at | string | Yes | When the account last posted. |
Extension fields (ext)
Platform-specific extras. Each one appears only on platforms that provide it, so treat every ext field as optional.
| Field | Type | Nullable | Description |
|---|---|---|---|
ext.social_context | string | Yes | Social context text the platform shows on the profile. |
ext.account_created | string | Yes | Account creation date as the platform shows it. |
ext.country | string | Yes | Country of the account. |
ext.former_usernames | string[] | Yes | Earlier usernames, where shown. |
ext.public_email | string | Yes | The first email address found in the bio. |
ext.contact_email | string | Yes | Opt in with contact_email=1 on /v1/instagram/profile, /v1/youtube/channel and /v1/youtube/channel/about. When a bio lists two or more addresses, this is the one the creator gives for personal contact, copied exactly. It stays null if the bio has fewer than two addresses, if all of them point to a manager, agency or brand, or if no single personal address stands out. ext.public_email is not affected. |
ext.public_phone | string | Yes | Public phone number on the profile. |
ext.business_category | string | Yes | Business category shown on the profile. |
ext.hd_avatar_url | string | Yes | Higher-resolution profile picture. |
ext.website | string | Yes | Website listed on the profile. |
ext.cover_url | string | Yes | Cover or banner image. |
ext.page_active | boolean | Yes | Whether a Facebook page is active. |
ext.employee_count | integer | Yes | LinkedIn company employee count. |
ext.employee_count_range.start | integer | Yes | Lower bound of the LinkedIn company size range. |
ext.employee_count_range.end | integer | Yes | Upper bound of the LinkedIn company size range. |
ext.founded_year | integer | Yes | Year the company was founded. |
ext.specialities | string[] | Yes | Company specialties listed on LinkedIn. |
ext.industries | string[] | Yes | Company industries. |
ext.headquarters | string | Yes | Company headquarters. |
ext.locations | string[] | Yes | Company office locations. |
ext.hashtags | string[] | Yes | Hashtags the company follows or lists. |
ext.funding | string | Yes | Company funding details. |
ext.address | string | Yes | Address on a Facebook page. |
ext.price_range | string | Yes | Price range on a Facebook page. |
ext.rating | string | Yes | Rating on a Facebook page. |
ext.rating_count | integer | Yes | Number of ratings on a Facebook page. |
ext.talking_about_count | integer | Yes | Facebook "talking about this" count. |
ext.business_hours | string[] | Yes | Opening hours on a Facebook page. |
ext.links | string[] | Yes | Links listed on the profile. |
ext.ad_library_page_id | string | Yes | Page ID to use with the Facebook Ad Library endpoints. |
ext.ad_library_status | string | Yes | Whether the page is running ads. |
ext.urn | string | Yes | LinkedIn URN. |
ext.is_top_voice | boolean | Yes | LinkedIn Top Voice badge. |
ext.is_premium | boolean | Yes | LinkedIn Premium member. |
ext.is_creator | boolean | Yes | LinkedIn creator mode. |
ext.is_influencer | boolean | Yes | LinkedIn influencer flag. |
ext.is_open_to_work | boolean | Yes | LinkedIn Open to Work flag. |
ext.is_hiring | boolean | Yes | LinkedIn Hiring flag. |
ext.member_id | string | Yes | LinkedIn member ID. |
ext.company_id | string | Yes | LinkedIn company ID, for the company/* endpoints. |
ext.reaction_type | string | Yes | The reaction a member left, on reaction lists. |
ext.followers_approximate | boolean | Yes | true when followers is a rounded or published figure rather than an exact count: LinkedIn people-list display figures, TikTok when no exact count is available, and YouTube at 1,000 subscribers or more. null or absent on exact counts. |
ext.keywords | string | Yes | YouTube channel keywords. |
ext.total_views | integer | Yes | Total channel views. |
ext.joined_at_timestamp | string | Yes | Account creation time as a timestamp. |
ext.topicCategories | string[] | Yes | YouTube topic categories. |
ext.bannerExternalUrl | string | Yes | YouTube channel banner. |
ext.madeForKids | boolean | Yes | YouTube made-for-kids flag. |
ext.hiddenSubscriberCount | boolean | Yes | true when the YouTube channel hides its subscriber count. |
ext.related_playlists | string | Yes | YouTube related playlists, such as uploads. |
ext.topic_ids | string[] | Yes | YouTube topic IDs. |
ext.unsubscribed_trailer | string | Yes | YouTube channel trailer shown to non-subscribers. |
ext.join_policy | string | Yes | Who can join a group or community. |
ext.is_nsfw | boolean | Yes | Subreddit or account marked adult. |
ext.rules | string[] | Yes | Subreddit rules. |
ext.weekly_active_users | integer | Yes | Subreddit weekly visitors. |
ext.weekly_contributions | integer | Yes | Subreddit weekly contributions. |
ext.rules_text | string | Yes | Subreddit rules as text. |
ext.language | string | Yes | Language set on the account or community. |
ext.post_karma | integer | Yes | Reddit post karma. |
ext.comment_karma | integer | Yes | Reddit comment karma. |
ext.awardee_karma | integer | Yes | Reddit awardee karma. |
ext.trophy_count | integer | Yes | Reddit trophies. |
ext.banner_url | string | Yes | Profile banner image. |
ext.social_links | string[] | Yes | Social links listed on the profile. |
ext.bio_link | string | Yes | Link in the bio. |
ext.group | string | Yes | Group details, on group responses. |
Which platforms fill which fields
Eight of the 9 platforms return this shape, and id is never null. yes means the platform can fill the field (it may still be null on a given row); a blank means it never does.
| Platform | following | verified | joined_at | posts_count | likes_count | private | url | followers | avatar_url | bio | location | external_url |
|---|---|---|---|---|---|---|---|---|---|---|---|---|
| yes | yes | yes | yes | yes | yes | yes | yes | yes | ||||
| yes | yes | yes | yes | yes | yes | yes | yes | yes | ||||
| yes | yes | yes | yes | yes | yes | yes | ||||||
| yes | yes | yes | yes | yes | yes | yes | yes | yes | ||||
| Threads | yes | yes | yes | yes | yes | yes | ||||||
| TikTok | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes | ||
| Twitter/X | yes | yes | yes | yes | yes | yes | yes | yes | yes | |||
| YouTube | yes | yes | yes | yes | yes | yes |
For fields that are always null on a platform, see Metric substitutions.
Returned by
Endpoints that return a profile or a list of profiles use this shape on:
Facebook · Instagram · LinkedIn · Reddit · Threads · TikTok · Twitter/X · YouTube
To see which native platform field feeds each unified field, read Field equivalence.