SocialCrawl
Unified schema

Author schema

The unified SocialCrawl author or creator profile schema. Every field, its type, per-platform availability, and a machine-readable JSON Schema, generated from the canonical Zod source.

Every SocialCrawl endpoint that returns a author or creator profile gives you this exact shape, whatever the source platform. Write your parser once and the same code reads author data from every platform below. That is the unified schema: one contract instead of a dozen raw upstream formats.

Field reference

FieldTypeNullableDescription
idstringNoPlatform-specific user ID (always a string; platform-specific prefixes like did:, spotify:artist:, t2_ are stripped)
usernamestringYesUser handle or username
display_namestringYesDisplay name or full name
avatar_urlstringYesURL to profile picture
biostringYesProfile biography or description
verifiedbooleanYesWhether the account is verified
followersnumberYesFollower or subscriber count as an integer. Exact on Instagram and on TikTok when the source exposes an unrounded figure. YouTube above 1,000 subscribers is YouTube's published three-significant-figure figure. When the integer is a published/rounded value, author.ext.followers_approximate is true.
followingnumberYesNumber of accounts followed
posts_countnumberYesTotal number of posts / videos / tracks / episodes
likes_countnumberYesTotal likes received across the author's content (when surfaced)
urlstringYesDirect URL to the profile page
locationstringYesISO region code (e.g. US) or freeform location string when surfaced
external_urlstringYesBio link / external website URL when surfaced by the platform
privatebooleanYesWhether the account is private.
joined_atstringYesWhen the account was created, as an ISO 8601 date (YYYY-MM-DD).
last_post_atstringYesPublish time of the newest post returned with the profile, as an ISO 8601 instant. Null when the source returned no posts.

Extension fields (ext)

Platform-specific passthrough. Each field is present only on the platforms that expose it and is absent everywhere else, so treat every ext.* field as optional. These carry the richer, per-platform signals the unified leaves cannot hold, and the join keys that chain endpoints together.

FieldTypeNullableDescription
ext.social_contextstringYesSocial proof line shown in lists, for example 'Followed by alice + 3 more'. Instagram only.
ext.account_based_instringYes
ext.signup_sourcestringYes
ext.username_changesnumberYes
ext.username_last_changed_atstringYes
ext.location_accuratebooleanYes
ext.created_country_accuratebooleanYes
ext.affiliate_usernamestringYes
ext.media_countnumberYes
ext.likes_givennumberYes
ext.creator_subscriptions_countnumberYes
ext.verified_bluebooleanYes
ext.verified_legacybooleanYes
ext.identity_verifiedbooleanYes
ext.verification_reasonstringYes
ext.instagram_followersnumberYes
ext.instagram_verifiedbooleanYes
ext.page_verificationstringYes
ext.page_categorystringYes
ext.entity_typestringYes
ext.is_political_pagebooleanYes
ext.page_is_restrictedbooleanYes
ext.verified_namestringYes
ext.verified_country_codestringYes
ext.advertiser_namestringYes
ext.registered_locationstringYes
ext.advertiser_sponsorstringYes
ext.follower_count_textstringYes
ext.countries_shownstring[]Yes
ext.ad_countnumberYes
ext.genderstringYes
ext.birthdaystringYes
ext.verified_reasonstringYes
ext.ip_locationstringYes
ext.verified_typenumberYes
ext.hometownstringYes
ext.employerstringYes
ext.credit_levelstringYes
ext.activity_summarystringYes
ext.account_createdstringYesWhen the account was created, as a readable label such as 'August 2013'.
ext.countrystringYesAccount country as an ISO 3166-1 alpha-2 code, or null when the profile does not name a single country.
ext.country_namestringYesEnglish name of country, for example 'South Korea' for KR.
ext.collects_receivednumberYesHow many times the account's notes were collected. Xiaohongshu only, separate from likes_count.
ext.former_usernamesstring[]YesUsernames the account used before.
ext.former_usernames_countintegerYesInstagram profile/about: how many former usernames Instagram's "About this account" panel lists for the account. 0 when the panel lists none, null when the panel could not be read on this call (the response then carries a note saying so). A count above 0 means the handle was renamed at least once; the names themselves are not published.
ext.verified_atstringYesInstagram profile/about, opt-in (include=verified_at): the month Instagram verified the account, as the panel shows it ("April 2024"). A month, not a date. Null when the account is not verified or the panel shows no verification date. Absent unless requested.
ext.is_memorializedbooleanYesLinkedIn members only: whether LinkedIn has memorialised this member's account.
ext.public_emailstringYesThe public contact address the account publishes, or null. On instagram/profile/about it is the address on the account's contact panel, and the first address in the bio only when the panel has none. On instagram/profile it is the first address in the bio.
ext.contactsobject[]Yes
ext.contact_emailstringYesOpt-in (contact_email=1 on instagram/profile, youtube/channel and youtube/channel/about). When the bio lists two or more email addresses, the one the creator gives for contacting them personally, copied verbatim. Null when there is one address or none, when every address belongs to a manager, agency or brand, or when the choice was not confident. It is decided by the same role rules as include=contacts, so it is always an address include=contacts serves as the creator's own on the same text. author.ext.public_email (the first address in the bio) is unchanged.
ext.public_phonestringYesBusiness phone number the account publishes, when it exposes one.
ext.similar_sourcestringYesWhich list suggested this account: instagram when it was matched from Instagram's similar accounts, or tiktok_graph when it came from another creator's roster.
ext.instagram_usernamestringYesThe Instagram account this suggestion was matched from, on TikTok similar accounts.
ext.similar_viastringYesThe handle whose roster listed this creator, when similar_source is tiktok_graph.
ext.business_categorystringYesProfessional or page category label, for example 'Live Music Venue'. Instagram and Facebook.
ext.bio_linksobject[]YesEvery link the account lists on its profile, in order. On Instagram these are the bio links and author.external_url holds the first; on LinkedIn they are the contact links the member lists, with LinkedIn's category for each (the creator website is author.ext.website).
ext.is_businessbooleanYesWhether the Instagram account is a business account.
ext.is_professionalbooleanYesTrue for a business or creator account, false for a personal one. Null when the source says neither.
ext.address_latitudenumberYes
ext.address_longitudenumberYes
ext.pronounsstring[]Yes
ext.has_highlightsbooleanYes
ext.threads_usernamestringYes
ext.latest_story_atstringYes
ext.creator_marketplacebooleanYesWhether the account is listed in TikTok's creator marketplace. Null when the profile carries no commerce block.
ext.verification_labelstringYesLabel shown beside the name on TikTok, for example 'verified account'. Null when none.
ext.fbidstringYesThe account's Facebook side id, as an exact digit string. Links an Instagram account to its Facebook page.
ext.hd_avatar_urlstringYesURL of the full resolution avatar.
ext.websitestringYesThe company, page or member's own website, not the profile permalink.
ext.cover_urlstringYesURL of the page banner or cover image.
ext.page_activebooleanYesWhether the page is active, as the page reports it.
ext.employee_countnumberYesExact headcount shown on the company page.
ext.employee_count_range.startnumberYesLower bound of the headcount bucket.
ext.employee_count_range.endnumberYesUpper bound of the headcount bucket, or null when it is open ended.
ext.founded_yearnumberYesYear the company was founded.
ext.company_typestringYesCompany type from the About tab, for example 'Public Company' or 'Privately Held'.
ext.taglinestringYesThe page tagline.
ext.specialitiesstring[]YesSpecialities the company lists.
ext.industriesstring[]YesIndustries the company lists.
ext.headquarters.countrystringYesCountry code.
ext.headquarters.citystringYesCity.
ext.headquarters.geographic_areastringYesState, region or county.
ext.headquarters.line1stringYesFirst line of the street address.
ext.headquarters.postal_codestringYesPostal code.
ext.headquarters.labelstringYesThe name LinkedIn gives the headquarters office, for example HQ. Null when it gives none.
ext.locationsobject[]YesThe company's offices and other locations.
ext.hashtagsobject[]YesHashtags the company page follows, or on a LinkedIn member the hashtags the member says they talk about. An empty list when a company page follows none; null on a member who lists none.
ext.funding.last_funding_round.money_raisedanyNoThe source does not send the amount, so this is an empty object.
ext.funding.last_funding_round.announced_onanyNoThe source does not send the date, so this is an empty object.
ext.founded_on.yearnumberYesThe year the company was founded.
ext.founded_on.monthnumberYesThe month the company was founded, 1 to 12, or null.
ext.founded_on.daynumberYesThe day of the month the company was founded, or null.
ext.company_type_codestringYesLinkedIn's stable code for the company type, for example PUBLIC_COMPANY. Match on this rather than on the label.
ext.page_typestringYesWhich kind of LinkedIn page this is: company, school or showcase.
ext.domainstringYesThe host of the company's website as LinkedIn records it, for example stripe.com.
ext.is_claimablebooleanYesWhether the company page is unclaimed and can still be claimed by the company.
ext.is_archivedbooleanYesWhether LinkedIn has archived the company page.
ext.is_auto_generatedbooleanYesWhether LinkedIn created the page itself rather than the company.
ext.verification_updated_atstringYesWhen LinkedIn last changed the page's verification record, as an ISO 8601 timestamp. It is not the date the page was verified.
ext.call_to_action_urlstringYesWhere the page's main button leads.
ext.industry_hierarchystringYesThe company's industry with its parent categories, for example 'Manufacturing > Paper and Forest Product Manufacturing'.
ext.public_phone_extensionstringYesThe extension of the page's phone number, or null.
ext.crunchbase_urlstringYesThe company's Crunchbase profile, when the page links one.
ext.open_job_countnumberYesHow many jobs the company has open on LinkedIn.
ext.productsanyNoThe products the company page lists, as the source sends them. Null when it lists none.
ext.addressstringYesStreet address the business page lists. Facebook only.
ext.price_rangestringYesPrice range the business page lists, for example '$$'. Facebook only.
ext.ratingstringYesRecommendation text the page shows, for example '80% recommend (794 Reviews)'. A display string, not a number.
ext.rating_countnumberYesNumber of reviews behind the rating text. Facebook only.
ext.talking_about_countnumberYesNumber of people Facebook counts as talking about the page.
ext.business_hoursanyNoThe page's opening hours as the source reports them. The source's format is not normalised and the field is null on every sampled page.
ext.linksany[]YesLinks the profile lists. On linktree/page each is { id, type, title, url }. On X profiles each is one of the destination URLs written in the bio, in order. On facebook/profile they are the outbound links the page lists in its About tab.
ext.ad_library_page_idstringYesThe page's id in the Facebook Ad Library, which differs from the profile id. Pass it as the company id to the Ad Library ads endpoint.
ext.ad_library_statusstringYesWhether the page is running ads, as the Ad Library reports it.
ext.urnstringYesOpaque LinkedIn urn for the member or company. The /user endpoints take it as their join key.
ext.is_top_voicebooleanYesWhether the member carries LinkedIn's Top Voice badge.
ext.is_premiumbooleanYesWhether the member has a LinkedIn Premium subscription, or on a company page whether it is a paid Premium page.
ext.is_creatorbooleanYesWhether the member is in LinkedIn's creator programme.
ext.is_influencerbooleanYesWhether the member is flagged as a LinkedIn influencer.
ext.is_open_to_workbooleanYesWhether the member shows the open to work badge.
ext.is_hiringbooleanYesWhether the member shows a hiring badge.
ext.member_idstringYesNumeric LinkedIn member id. author.id is the vanity slug, and post lanes publish this id as post.ext.author_id.
ext.joined_at_precisionstringYesmonth when author.joined_at is the first day of the month the member joined, because the answering source gives the month and year only. Null when author.joined_at is the exact day. LinkedIn only.
ext.first_namestringYesThe member's first name. LinkedIn members only.
ext.last_namestringYesThe member's last name, or its initial when LinkedIn shows only that. LinkedIn members only.
ext.pronounstringYesThe pronouns the member shows, for example she/her. Null when none.
ext.primary_localestringYesThe member's main profile language and region as a locale tag, for example en_US.
ext.supported_localesstring[]YesEvery language the member's profile is written in, as locale tags.
ext.aboutstringYesThe member's About text, as written on the profile. LinkedIn members only.
ext.about_localizedobjectYesThe About text in the member's other profile languages, keyed by locale (for example de_DE). The primary locale is left out because it repeats author.ext.about. Null when the profile has one language.
ext.headline_localizedobjectYesThe headline in the member's other profile languages, keyed by locale. The primary locale is left out because it repeats author.bio. Null when the profile has one language.
ext.current_position.titlestringYesThe job title.
ext.current_position.companystringYesThe employer's name.
ext.current_position.company_idstringYesThe employer's numeric LinkedIn company id, the id the company endpoints take. Null when the source does not give it.
ext.current_position.company_usernamestringYesThe employer's LinkedIn handle, as in its page URL.
ext.current_position.company_urlstringYesThe employer's LinkedIn page.
ext.current_school.namestringYesThe school's name.
ext.current_school.school_idstringYesLinkedIn's school id. Null when the source does not give it.
ext.current_school.company_idstringYesThe numeric id of the school's LinkedIn page. Null when the source does not give it.
ext.current_school.usernamestringYesThe school page's LinkedIn handle, as in its URL. Null when the URL carries an id instead.
ext.current_school.urlstringYesThe school's LinkedIn page.
ext.industrystringYesThe member's industry label. The wording can vary between answers for the same industry, so match on author.ext.industry_id.
ext.industry_idstringYesLinkedIn's numeric industry id, as a string. The stable key for the member's or company's industry.
ext.verificationsobject[]YesThe verifications LinkedIn lists on the profile, such as an identity check or a work email. Null when the answer did not include the list.
ext.geo_idstringYesLinkedIn's id for the member's location, the id /v1/linkedin/search/location returns.
ext.is_open_profilebooleanYesWhether the member accepts messages from anyone (LinkedIn's Open Profile).
ext.last_name_is_initialbooleanYesTrue when LinkedIn shows only the initial of the member's last name. Null otherwise.
ext.volunteer_causesstring[]YesThe causes the member says they care about, as LinkedIn labels them.
ext.top_skillsstring[]YesThe skills LinkedIn shows first on the profile.
ext.profile_actionsobject[]YesThe buttons in the member's profile header, such as 'Visit my website'. Not the contact links, which are author.ext.bio_links. Null when the answer gives none.
ext.section_totalsobjectYesThe source's own count for each profile section. It can exceed the length of a section list, so trust this for a count.
ext.company_idstringYesNumeric company id, which is what the LinkedIn company endpoints take. author.id on these rows is the vanity slug.
ext.reaction_typestringYesHow this member reacted to the post, on the reactions lane: LIKE, PRAISE, EMPATHY, APPRECIATION, INTEREST or ENTERTAINMENT.
ext.public_identifierstringYes
ext.account_typestringYesWhether the reactor is a member (user) or a page (company). LinkedIn reactor lists only.
ext.followers_approximatebooleanYesTrue when author.followers is a published or rounded figure rather than an unrounded census: LinkedIn people-list display buckets, TikTok stats.followerCount when the exact sibling is absent, and YouTube subscriber counts at or above 1,000. Null or absent on exact counts.
ext.counts_sourcestringYesTikTok profile only. Which of TikTok's two live counter sets author.followers, author.following, author.likes_count and author.posts_count carry: app (TikTok's app counters, the default) or web (the website's statsV2, returned with counts=web). The two sets can differ by a few percent in either direction.
ext.posting_regionstringYes
ext.keywordsstringYesChannel keywords as one space separated string. YouTube only.
ext.total_viewsnumberYesLifetime view count of the channel. YouTube only.
ext.joined_at_timestampstringYesFull ISO 8601 creation time of the channel or account. author.joined_at holds its date part. YouTube, and TikTok with include=account.
ext.topicCategoriesstring[]YesWikipedia URLs for the channel's topics. YouTube only.
ext.bannerExternalUrlstringYesURL of the channel banner image. YouTube only.
ext.madeForKidsbooleanYesWhether the channel is marked as made for kids. YouTube only.
ext.hiddenSubscriberCountbooleanYesWhether the channel hides its subscriber count. YouTube only.
ext.related_playlists.uploadsstringNoId of the playlist holding every upload.
ext.related_playlists.likesstringNoId of the liked-videos playlist. Empty when it is private.
ext.topic_idsstring[]YesFreebase topic ids for the channel. YouTube only.
ext.unsubscribed_trailerstringYesVideo id of the channel trailer shown to people who have not subscribed. YouTube only.
ext.localizationsobjectYesTranslated channel titles and descriptions, keyed by language code. Present with include_localizations.
ext.monthly_listenersnumberYesMonthly listeners, a reach figure and not a post count. Spotify artists only.
ext.total_ratingsnumberYesSpotify podcasts only: how many listeners have rated the show. Cumulative over the show's whole run, so it reflects longevity as well as size, and it is NOT an audience count (Spotify publishes no play, download, subscriber or follower count for a podcast)
ext.average_ratingnumberYesSpotify podcasts only: mean listener rating from 0 to 5. Fractional (e.g. 4.66) despite the integer type this schema emits for every numeric leaf
ext.creator_usernamestringYesHandle of the person who created the community. X communities only.
ext.join_policystringYesHow people join the community, as the platform labels it. X communities only.
ext.is_nsfwbooleanYesWhether the community is marked as adult. X communities only.
ext.rulesobject[]YesThe community's rules.
ext.weekly_active_usersnumberYesPeople active in the community in a week, as Reddit shows it. Not the subscriber count.
ext.weekly_contributionsnumberYesPosts and comments made in the community in a week, as Reddit shows it.
ext.rules_textstringYesThe community rules as one newline separated text block. Reddit only.
ext.languagestringYesThe community's primary language tag, for example en. Reddit only.
ext.post_karmanumberYesKarma earned from posts. Reddit accounts only.
ext.comment_karmanumberYesKarma earned from comments. Reddit accounts only.
ext.awardee_karmanumberYesKarma earned from awards received. Reddit accounts only.
ext.trophy_countnumberYesNumber of trophies on the Reddit profile.
ext.banner_urlstringYesURL of the profile banner image. Reddit only.
ext.profile_titlestringYesProfile title the account set, independent of its username. Reddit only.
ext.social_linksobject[]YesSocial profiles linked from the account.
ext.bio_linkstringYesThe website set in the Threads bio.
ext.embed_htmlstringYesInstagram's embed snippet for the profile, ready to paste into a page.
ext.embed_urlstringYesThe iframe source the embed snippet loads.
ext.group.privacy_labelstringNoPrivacy setting, such as Public.
ext.group.privacy_descriptionstringNoWhat the privacy setting means.
ext.group.visibility_labelstringNoVisibility setting, such as Visible.
ext.group.visibility_descriptionstringNoWhat the visibility setting means.
ext.group.member_count_textstringNoThe member count as the platform words it.
ext.group.administrator_countnumberNoHow many administrators the group has.
ext.group.moderator_countnumberNoHow many moderators the group has.
ext.group.history_summarystringNoWhen the group was created, as text.
ext.group.categoriesstring[]NoCategories the group lists.
ext.group.rulesany[]NoThe group's rules.
ext.group.administratorsobject[]NoThe group's administrators.
ext.group.moderatorsobject[]NoThe group's moderators.
ext.group.activity.posts_last_daynumberNoPosts in the last 24 hours.
ext.group.activity.posts_last_monthnumberNoPosts in the last 30 days.
ext.group.activity.new_members_textstringNoNew members this week, as text.
ext.group.about_infoobject[]NoThe entries of the group's About section.
ext.search_hit.matchstringYesWhat was hit: group_page, post_in_group, channel_page or post_in_channel.
ext.search_hit.titlestringYesThe hit title as the search index showed it. It is not the account's own name.
ext.search_hit.snippetstringYesThe hit text as the search index showed it. It is not the account's own description.
ext.search_hit.evidence_urlstringYesThe exact URL the search hit.
ext.search_hit.matched_urlsstring[]YesEvery distinct URL the search matched for this channel, in order. Telegram only.
ext.blog_namestringYesThe blog's own name. The display name is the owner's nickname. Naver only.
ext.blog_nostringYesNaver's blog number for the blog.
ext.visitors_todaynumberYesVisitors the blog counted today. Naver only.
ext.visitors_totalnumberYesVisitors the blog counted in total. Naver only.
ext.topicstringYesThe topic the blog is filed under. Naver only.
ext.power_blogbooleanYesWhether the blog carries Naver's power blog flag.
ext.official_blogbooleanYesWhether the blog carries Naver's official blog flag.

Platform availability

33 platforms return the Author shape. id are never null on any platform. The fields below vary: yes means the platform populates it (the value may still be null); a blank means the platform never provides it, so it is always null.

Platformfollowingjoined_atverifiedposts_countlikes_countprivatefollowersurllocationbioexternal_urlavatar_url
Apple Musicyesyes
Blueskyyesyesyesyesyesyes
Douyinyesyesyesyesyesyesyesyes
Facebookyesyesyesyesyesyesyesyesyes
G2yesyesyesyes
Gabyesyesyesyesyesyesyesyesyes
GitHubyesyesyesyesyesyesyesyesyesyes
Goodreadsyesyesyesyesyesyesyes
Googleyesyes
Hacker Newsyesyesyes
Instagramyesyesyesyesyesyesyesyesyes
Komiyesyesyes
Kwaiyesyesyesyesyesyesyesyesyes
LinkBioyes
LinkedInyesyesyesyesyesyesyesyes
LinkMeyesyesyesyesyes
Linktreeyesyes
Naveryesyesyesyes
Pillaryesyesyesyes
Quorayesyesyesyes
Reddityesyesyesyesyesyesyesyesyesyes
Snapchatyesyesyesyesyesyesyesyes
Spotifyyesyesyes
Telegramyesyesyesyesyes
Threadsyesyesyesyesyesyesyesyesyesyes
TikTokyesyesyesyesyesyesyesyesyesyes
Trustpilotyesyes
Truth Socialyesyesyesyesyesyesyesyesyesyes
Twitchyesyesyesyesyesyesyesyesyesyes
Twitter/Xyesyesyesyesyesyesyesyesyes
Weiboyesyesyesyesyesyesyesyesyesyes
Xiaohongshuyesyesyesyesyesyesyesyes
YouTubeyesyesyesyesyesyesyes

Machine-readable schema

Validate responses programmatically against the JSON Schema (2020-12):

/schemas/author.json

Point a validator (Ajv, jsonschema, or your framework's) at that URL, or hand it to an agent so it can check the shape without a live call.

Returned by

Endpoints with the Author / AuthorList archetype return this shape:

Apple Music · Bluesky · Douyin · Facebook · G2 · Gab · GitHub · Goodreads · Google · Hacker News · Instagram · Komi · Kwai · LinkBio · LinkedIn · LinkMe · Linktree · Naver · Pillar · Quora · Reddit · Snapchat · Spotify · Telegram · Threads · TikTok · Trustpilot · Truth Social · Twitch · Twitter/X · Weibo · Xiaohongshu · YouTube

See how the same fields map to each platform's raw upstream names in the cross-platform field equivalence table.

On this page