{"openapi":"3.1.0","info":{"title":"SocialDataKit API","version":"1.8.0","description":"Public social data across Instagram, TikTok, YouTube and Meta Ads with one API key. Preview resources require evaluation before customer use. Development keys return free sample data. Production keys return public source data or an error, never samples. Workspace rate limit: 60 requests per minute."},"servers":[{"url":"https://api.socialdatakit.com","description":"Production API"}],"tags":[{"name":"instagram","description":"Normalized Instagram resources"},{"name":"tiktok","description":"Normalized TikTok resources"},{"name":"youtube","description":"Normalized YouTube resources"},{"name":"facebook","description":"Meta Ad Library company ads (preview)"},{"name":"twitter","description":"Planned Twitter/X resources; four operator-only collectors await live validation. Public requests return 501 without charging."},{"name":"account","description":"Workspace credit balance"},{"name":"workflows","description":"Spreadsheet-ready profiles and campaign reports"}],"paths":{"/v1/instagram/profile":{"get":{"operationId":"instagram_profile","summary":"Instagram profile","description":"Get a public profile’s bio, follower count, profile picture, links and verification status. Core resource for supplied public handles or content IDs.","tags":["instagram"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"handle","in":"query","required":false,"schema":{"type":"string","pattern":"^@?[A-Za-z0-9._]{1,30}$","example":"natgeo"},"description":"Required instagram handle. Supply exactly one of: handle, url."},{"name":"cache_max_age","in":"query","required":false,"schema":{"type":"string","enum":["1d","3d","7d","14d","30d"]},"description":"Maximum acceptable cache age. Valid cache hits cost zero credits."},{"name":"fields","in":"query","required":false,"schema":{"type":"string","example":"profile.username,profile.followers"},"description":"Comma-separated fields or dot paths, including inside arrays such as items.id. Response identity and pagination are retained."},{"name":"trim","in":"query","required":false,"schema":{"type":"boolean","default":false},"description":"Remove null and empty values. Meaningful empty YouTube region-restriction lists are retained."},{"name":"url","in":"query","required":false,"schema":{"type":"string","format":"uri"},"description":"Alternative to handle. Supply exactly one identifier. URLs must belong to instagram."}],"responses":{"200":{"description":"Normalized resource","headers":{"x-request-id":{"schema":{"type":"string"}},"x-data-mode":{"schema":{"type":"string","enum":["live","sandbox"]}},"x-cache":{"schema":{"type":"string","enum":["HIT","MISS"]}},"x-credits-charged":{"schema":{"type":"integer"}},"x-credits-remaining":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"data":{"type":"object","properties":{"profile":{"type":"object","additionalProperties":true,"properties":{"id":{"type":["string","null"],"description":"Stable platform account ID when supplied; never an inferred username ID."},"username":{"type":["string","null"],"description":"Current account handle."},"display_name":{"type":["string","null"],"description":"Public display name."},"bio":{"type":["string","null"],"description":"Public biography."},"profile_url":{"type":["string","null"],"description":"Public profile URL."},"followers":{"type":["number","null"],"description":"Observed audience count; page summaries may be rounded."},"following":{"type":["number","null"],"description":"Observed following count."},"posts":{"type":["number","null"],"description":"Observed content count."},"verified":{"type":["boolean","null"],"description":"True or false only when explicitly returned; null means unknown."},"private":{"type":["boolean","null"],"description":"Observed privacy state; null means unknown."},"avatar_url":{"type":["string","null"],"description":"Source avatar URL, which can expire or restrict hotlinking."},"avatar_variants":{"type":["array","null"],"description":"Returned avatar image variants.","items":{"type":["object","null"],"description":"One source media variant; URLs may expire.","properties":{"url":{"type":["string","null"],"description":"Source URL."},"width":{"type":["number","null"],"description":"Width in pixels."},"height":{"type":["number","null"],"description":"Height in pixels."},"asset_type":{"type":["string","null"],"description":"image, video, thumbnail or avatar."},"variant":{"type":["string","null"],"description":"Source variant when known."},"expires_at":{"type":["string","null"],"description":"Expiry timestamp when known."}}}},"external_url":{"type":["string","null"],"description":"Public external website."},"account_type":{"type":["string","null"],"description":"Business/professional type only when explicitly observable."},"category":{"type":["string","null"],"description":"Public profile category."},"follower_count_is_rounded":{"type":["boolean","null"],"description":"True for abbreviated follower counts parsed from page summaries."},"bio_links":{"type":["array","null"],"description":"Links published in the biography.","items":{"type":["object","null"],"description":"Public link.","properties":{"url":{"type":["string","null"],"description":"Destination URL."},"title":{"type":["string","null"],"description":"Link title when returned."}}}}}}}}}}]}}}},"400":{"$ref":"#/components/responses/InvalidInput"},"401":{"$ref":"#/components/responses/InvalidApiKey"},"402":{"$ref":"#/components/responses/InsufficientCredits"},"403":{"$ref":"#/components/responses/SourceRestricted"},"404":{"$ref":"#/components/responses/ResourceNotFound"},"408":{"$ref":"#/components/responses/SourceTimeout"},"422":{"$ref":"#/components/responses/SourceResponseChanged"},"429":{"$ref":"#/components/responses/TemporaryCapacity"},"501":{"$ref":"#/components/responses/SourceNotImplemented"},"503":{"$ref":"#/components/responses/SourceUnavailable"}},"x-availability":"available","x-identifier-one-of":["handle","url"],"x-credits":1,"x-source-access":"public_page","x-preview":false,"x-codeSamples":[{"lang":"curl","source":"curl 'https://api.socialdatakit.com/v1/instagram/profile?handle=natgeo' \\\n  -H 'x-api-key: YOUR_API_KEY'"},{"lang":"javascript","source":"const response = await fetch(\"https://api.socialdatakit.com/v1/instagram/profile?handle=natgeo\", {\n  headers: { \"x-api-key\": process.env.SOCIALDATAKIT_API_KEY }\n});\nif (!response.ok) throw new Error(await response.text());\nconst result = await response.json();"},{"lang":"python","source":"import os\nimport requests\n\nresponse = requests.get(\n    \"https://api.socialdatakit.com/v1/instagram/profile?handle=natgeo\",\n    headers={\"x-api-key\": os.environ[\"SOCIALDATAKIT_API_KEY\"]},\n    timeout=30,\n)\nresponse.raise_for_status()\nresult = response.json()"}],"x-response-fields":{"id":{"type":"string","description":"Stable platform account ID when supplied; never an inferred username ID."},"username":{"type":"string","description":"Current account handle."},"display_name":{"type":"string","description":"Public display name."},"bio":{"type":"string","description":"Public biography."},"profile_url":{"type":"string","description":"Public profile URL."},"followers":{"type":"number","description":"Observed audience count; page summaries may be rounded."},"following":{"type":"number","description":"Observed following count."},"posts":{"type":"number","description":"Observed content count."},"verified":{"type":"boolean","description":"True or false only when explicitly returned; null means unknown."},"private":{"type":"boolean","description":"Observed privacy state; null means unknown."},"avatar_url":{"type":"string","description":"Source avatar URL, which can expire or restrict hotlinking."},"avatar_variants":{"type":"array","description":"Returned avatar image variants.","items":{"type":"object","description":"One source media variant; URLs may expire.","properties":{"url":{"type":"string","description":"Source URL."},"width":{"type":"number","description":"Width in pixels."},"height":{"type":"number","description":"Height in pixels."},"asset_type":{"type":"string","description":"image, video, thumbnail or avatar."},"variant":{"type":"string","description":"Source variant when known."},"expires_at":{"type":"string","description":"Expiry timestamp when known."}}}},"external_url":{"type":"string","description":"Public external website."},"account_type":{"type":"string","description":"Business/professional type only when explicitly observable."},"category":{"type":"string","description":"Public profile category."},"follower_count_is_rounded":{"type":"boolean","description":"True for abbreviated follower counts parsed from page summaries."},"bio_links":{"type":"array","description":"Links published in the biography.","items":{"type":"object","description":"Public link.","properties":{"url":{"type":"string","description":"Destination URL."},"title":{"type":"string","description":"Link title when returned."}}}}}}},"/v1/instagram/posts":{"get":{"operationId":"instagram_posts","summary":"Instagram posts","description":"Get recent public posts, captions, images, videos, likes and comments when available. Core resource for supplied public handles or content IDs.","tags":["instagram"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"handle","in":"query","required":true,"schema":{"type":"string","pattern":"^@?[A-Za-z0-9._]{1,30}$","example":"natgeo"},"description":"Required instagram handle."},{"name":"cache_max_age","in":"query","required":false,"schema":{"type":"string","enum":["1d","3d","7d","14d","30d"]},"description":"Maximum acceptable cache age. Valid cache hits cost zero credits."},{"name":"fields","in":"query","required":false,"schema":{"type":"string","example":"items"},"description":"Comma-separated fields or dot paths, including inside arrays such as items.id. Response identity and pagination are retained."},{"name":"trim","in":"query","required":false,"schema":{"type":"boolean","default":false},"description":"Remove null and empty values. Meaningful empty YouTube region-restriction lists are retained."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":20,"default":3},"description":"Number of items to return."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"},"description":"Opaque pagination value returned as data.pagination.next_cursor. Keep the identifier, filters and limit unchanged."}],"responses":{"200":{"description":"Normalized resource","headers":{"x-request-id":{"schema":{"type":"string"}},"x-data-mode":{"schema":{"type":"string","enum":["live","sandbox"]}},"x-cache":{"schema":{"type":"string","enum":["HIT","MISS"]}},"x-credits-charged":{"schema":{"type":"integer"}},"x-credits-remaining":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"data":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","additionalProperties":true,"properties":{"id":{"type":["string","null"],"description":"Resource identifier used by this endpoint."},"author":{"type":["string","null"],"description":"Public creator name or handle."},"published_at":{"type":["string","null"],"description":"Source publication date or timestamp; null when absent."},"views":{"type":["number","null"],"description":"Observed views, where exposed by this source."},"likes":{"type":["number","null"],"description":"Observed likes."},"comments":{"type":["number","null"],"description":"Observed comment count, not comment rows."},"media_url":{"type":["string","null"],"description":"Preview image URL; not a guaranteed downloadable video."},"permalink":{"type":["string","null"],"description":"Public content URL."},"duration_seconds":{"type":["number","null"],"description":"Duration in seconds when returned."},"hashtags":{"type":["array","null"],"description":"Hashtags with platform or derived_text provenance.","items":{"type":["object","null"],"description":"Entity observed at source or derived from text.","properties":{"name":{"type":["string","null"],"description":"Hashtag or account name."},"id":{"type":["string","null"],"description":"Platform ID when supplied."},"source":{"type":["string","null"],"description":"platform or derived_text."}}}},"mentions":{"type":["array","null"],"description":"Mentions with platform or derived_text provenance; text is not proof of an account relationship.","items":{"type":["object","null"],"description":"Entity observed at source or derived from text.","properties":{"name":{"type":["string","null"],"description":"Hashtag or account name."},"id":{"type":["string","null"],"description":"Platform ID when supplied."},"source":{"type":["string","null"],"description":"platform or derived_text."}}}},"author_id":{"type":["string","null"],"description":"Stable creator ID when returned."},"author_display_name":{"type":["string","null"],"description":"Public display name."},"author_verified":{"type":["boolean","null"],"description":"Explicit creator verification state."},"author_avatar_url":{"type":["string","null"],"description":"Public creator avatar URL."},"platform_content_id":{"type":["string","null"],"description":"Platform media ID, separate from the shortcode."},"caption":{"type":["string","null"],"description":"Public caption."},"media_type":{"type":["string","null"],"description":"image, video, carousel, or null when unknown."},"media_product_type":{"type":["string","null"],"description":"Source product type, kept separate from media type."},"width":{"type":["number","null"],"description":"Media width in pixels."},"height":{"type":["number","null"],"description":"Media height in pixels."},"video_url":{"type":["string","null"],"description":"Source video URL where returned; may expire."},"comments_enabled":{"type":["boolean","null"],"description":"Observed comments setting."},"paid_partnership":{"type":["boolean","null"],"description":"Explicit source partnership flag; null when unavailable."},"accessibility_caption":{"type":["string","null"],"description":"Source alt text or accessibility description."},"location":{"type":["object","null"],"description":"Publicly attached location label.","properties":{"id":{"type":["string","null"],"description":"Location ID."},"name":{"type":["string","null"],"description":"Location name."},"slug":{"type":["string","null"],"description":"Location slug."}}},"tagged_users":{"type":["array","null"],"description":"Accounts explicitly tagged in the media.","items":{"type":["object","null"],"description":"Tagged account.","properties":{"id":{"type":["string","null"],"description":"Platform account ID."},"username":{"type":["string","null"],"description":"Handle."},"display_name":{"type":["string","null"],"description":"Display name."}}}},"media_assets":{"type":["array","null"],"description":"Returned image/video variants with dimensions.","items":{"type":["object","null"],"description":"One source media variant; URLs may expire.","properties":{"url":{"type":["string","null"],"description":"Source URL."},"width":{"type":["number","null"],"description":"Width in pixels."},"height":{"type":["number","null"],"description":"Height in pixels."},"asset_type":{"type":["string","null"],"description":"image, video, thumbnail or avatar."},"variant":{"type":["string","null"],"description":"Source variant when known."},"expires_at":{"type":["string","null"],"description":"Expiry timestamp when known."}}}},"children":{"type":["array","null"],"description":"Ordered carousel children when returned; null for non-carousels.","items":{"type":["object","null"],"description":"One carousel child.","properties":{"id":{"type":["string","null"],"description":"Media ID."},"position":{"type":["number","null"],"description":"Zero-based position."},"media_type":{"type":["string","null"],"description":"image, video or null."},"media_url":{"type":["string","null"],"description":"Preview image URL."},"video_url":{"type":["string","null"],"description":"Source video URL when available."},"width":{"type":["number","null"],"description":"Width in pixels."},"height":{"type":["number","null"],"description":"Height in pixels."}}}}}}}}}}}]}}}},"400":{"$ref":"#/components/responses/InvalidInput"},"401":{"$ref":"#/components/responses/InvalidApiKey"},"402":{"$ref":"#/components/responses/InsufficientCredits"},"403":{"$ref":"#/components/responses/SourceRestricted"},"404":{"$ref":"#/components/responses/ResourceNotFound"},"408":{"$ref":"#/components/responses/SourceTimeout"},"422":{"$ref":"#/components/responses/SourceResponseChanged"},"429":{"$ref":"#/components/responses/TemporaryCapacity"},"501":{"$ref":"#/components/responses/SourceNotImplemented"},"503":{"$ref":"#/components/responses/SourceUnavailable"}},"x-availability":"available","x-identifier-one-of":["handle"],"x-credits":2,"x-source-access":"public_page","x-preview":false,"x-codeSamples":[{"lang":"curl","source":"curl 'https://api.socialdatakit.com/v1/instagram/posts?handle=natgeo' \\\n  -H 'x-api-key: YOUR_API_KEY'"},{"lang":"javascript","source":"const response = await fetch(\"https://api.socialdatakit.com/v1/instagram/posts?handle=natgeo\", {\n  headers: { \"x-api-key\": process.env.SOCIALDATAKIT_API_KEY }\n});\nif (!response.ok) throw new Error(await response.text());\nconst result = await response.json();"},{"lang":"python","source":"import os\nimport requests\n\nresponse = requests.get(\n    \"https://api.socialdatakit.com/v1/instagram/posts?handle=natgeo\",\n    headers={\"x-api-key\": os.environ[\"SOCIALDATAKIT_API_KEY\"]},\n    timeout=30,\n)\nresponse.raise_for_status()\nresult = response.json()"}],"x-response-fields":{"id":{"type":"string","description":"Resource identifier used by this endpoint."},"author":{"type":"string","description":"Public creator name or handle."},"published_at":{"type":"string","description":"Source publication date or timestamp; null when absent."},"views":{"type":"number","description":"Observed views, where exposed by this source."},"likes":{"type":"number","description":"Observed likes."},"comments":{"type":"number","description":"Observed comment count, not comment rows."},"media_url":{"type":"string","description":"Preview image URL; not a guaranteed downloadable video."},"permalink":{"type":"string","description":"Public content URL."},"duration_seconds":{"type":"number","description":"Duration in seconds when returned."},"hashtags":{"type":"array","description":"Hashtags with platform or derived_text provenance.","items":{"type":"object","description":"Entity observed at source or derived from text.","properties":{"name":{"type":"string","description":"Hashtag or account name."},"id":{"type":"string","description":"Platform ID when supplied."},"source":{"type":"string","description":"platform or derived_text."}}}},"mentions":{"type":"array","description":"Mentions with platform or derived_text provenance; text is not proof of an account relationship.","items":{"type":"object","description":"Entity observed at source or derived from text.","properties":{"name":{"type":"string","description":"Hashtag or account name."},"id":{"type":"string","description":"Platform ID when supplied."},"source":{"type":"string","description":"platform or derived_text."}}}},"author_id":{"type":"string","description":"Stable creator ID when returned."},"author_display_name":{"type":"string","description":"Public display name."},"author_verified":{"type":"boolean","description":"Explicit creator verification state."},"author_avatar_url":{"type":"string","description":"Public creator avatar URL."},"platform_content_id":{"type":"string","description":"Platform media ID, separate from the shortcode."},"caption":{"type":"string","description":"Public caption."},"media_type":{"type":"string","description":"image, video, carousel, or null when unknown."},"media_product_type":{"type":"string","description":"Source product type, kept separate from media type."},"width":{"type":"number","description":"Media width in pixels."},"height":{"type":"number","description":"Media height in pixels."},"video_url":{"type":"string","description":"Source video URL where returned; may expire."},"comments_enabled":{"type":"boolean","description":"Observed comments setting."},"paid_partnership":{"type":"boolean","description":"Explicit source partnership flag; null when unavailable."},"accessibility_caption":{"type":"string","description":"Source alt text or accessibility description."},"location":{"type":"object","description":"Publicly attached location label.","properties":{"id":{"type":"string","description":"Location ID."},"name":{"type":"string","description":"Location name."},"slug":{"type":"string","description":"Location slug."}}},"tagged_users":{"type":"array","description":"Accounts explicitly tagged in the media.","items":{"type":"object","description":"Tagged account.","properties":{"id":{"type":"string","description":"Platform account ID."},"username":{"type":"string","description":"Handle."},"display_name":{"type":"string","description":"Display name."}}}},"media_assets":{"type":"array","description":"Returned image/video variants with dimensions.","items":{"type":"object","description":"One source media variant; URLs may expire.","properties":{"url":{"type":"string","description":"Source URL."},"width":{"type":"number","description":"Width in pixels."},"height":{"type":"number","description":"Height in pixels."},"asset_type":{"type":"string","description":"image, video, thumbnail or avatar."},"variant":{"type":"string","description":"Source variant when known."},"expires_at":{"type":"string","description":"Expiry timestamp when known."}}}},"children":{"type":"array","description":"Ordered carousel children when returned; null for non-carousels.","items":{"type":"object","description":"One carousel child.","properties":{"id":{"type":"string","description":"Media ID."},"position":{"type":"number","description":"Zero-based position."},"media_type":{"type":"string","description":"image, video or null."},"media_url":{"type":"string","description":"Preview image URL."},"video_url":{"type":"string","description":"Source video URL when available."},"width":{"type":"number","description":"Width in pixels."},"height":{"type":"number","description":"Height in pixels."}}}}}}},"/v1/instagram/post":{"get":{"operationId":"instagram_post","summary":"Instagram post","description":"Get a public post or reel, its caption, media and available engagement counts. Core resource for supplied public handles or content IDs.","tags":["instagram"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"id","in":"query","required":false,"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{5,32}$","example":"CxDemo123"},"description":"Required instagram id. Supply exactly one of: id, url."},{"name":"cache_max_age","in":"query","required":false,"schema":{"type":"string","enum":["1d","3d","7d","14d","30d"]},"description":"Maximum acceptable cache age. Valid cache hits cost zero credits."},{"name":"fields","in":"query","required":false,"schema":{"type":"string","example":"item"},"description":"Comma-separated fields or dot paths, including inside arrays such as items.id. Response identity and pagination are retained."},{"name":"trim","in":"query","required":false,"schema":{"type":"boolean","default":false},"description":"Remove null and empty values. Meaningful empty YouTube region-restriction lists are retained."},{"name":"url","in":"query","required":false,"schema":{"type":"string","format":"uri"},"description":"Alternative to id. Supply exactly one identifier. URLs must belong to instagram."}],"responses":{"200":{"description":"Normalized resource","headers":{"x-request-id":{"schema":{"type":"string"}},"x-data-mode":{"schema":{"type":"string","enum":["live","sandbox"]}},"x-cache":{"schema":{"type":"string","enum":["HIT","MISS"]}},"x-credits-charged":{"schema":{"type":"integer"}},"x-credits-remaining":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"data":{"type":"object","properties":{"item":{"type":"object","additionalProperties":true,"properties":{"id":{"type":["string","null"],"description":"Resource identifier used by this endpoint."},"author":{"type":["string","null"],"description":"Public creator name or handle."},"published_at":{"type":["string","null"],"description":"Source publication date or timestamp; null when absent."},"views":{"type":["number","null"],"description":"Observed views, where exposed by this source."},"likes":{"type":["number","null"],"description":"Observed likes."},"comments":{"type":["number","null"],"description":"Observed comment count, not comment rows."},"media_url":{"type":["string","null"],"description":"Preview image URL; not a guaranteed downloadable video."},"permalink":{"type":["string","null"],"description":"Public content URL."},"duration_seconds":{"type":["number","null"],"description":"Duration in seconds when returned."},"hashtags":{"type":["array","null"],"description":"Hashtags with platform or derived_text provenance.","items":{"type":["object","null"],"description":"Entity observed at source or derived from text.","properties":{"name":{"type":["string","null"],"description":"Hashtag or account name."},"id":{"type":["string","null"],"description":"Platform ID when supplied."},"source":{"type":["string","null"],"description":"platform or derived_text."}}}},"mentions":{"type":["array","null"],"description":"Mentions with platform or derived_text provenance; text is not proof of an account relationship.","items":{"type":["object","null"],"description":"Entity observed at source or derived from text.","properties":{"name":{"type":["string","null"],"description":"Hashtag or account name."},"id":{"type":["string","null"],"description":"Platform ID when supplied."},"source":{"type":["string","null"],"description":"platform or derived_text."}}}},"author_id":{"type":["string","null"],"description":"Stable creator ID when returned."},"author_display_name":{"type":["string","null"],"description":"Public display name."},"author_verified":{"type":["boolean","null"],"description":"Explicit creator verification state."},"author_avatar_url":{"type":["string","null"],"description":"Public creator avatar URL."},"platform_content_id":{"type":["string","null"],"description":"Platform media ID, separate from the shortcode."},"caption":{"type":["string","null"],"description":"Public caption."},"media_type":{"type":["string","null"],"description":"image, video, carousel, or null when unknown."},"media_product_type":{"type":["string","null"],"description":"Source product type, kept separate from media type."},"width":{"type":["number","null"],"description":"Media width in pixels."},"height":{"type":["number","null"],"description":"Media height in pixels."},"video_url":{"type":["string","null"],"description":"Source video URL where returned; may expire."},"comments_enabled":{"type":["boolean","null"],"description":"Observed comments setting."},"paid_partnership":{"type":["boolean","null"],"description":"Explicit source partnership flag; null when unavailable."},"accessibility_caption":{"type":["string","null"],"description":"Source alt text or accessibility description."},"location":{"type":["object","null"],"description":"Publicly attached location label.","properties":{"id":{"type":["string","null"],"description":"Location ID."},"name":{"type":["string","null"],"description":"Location name."},"slug":{"type":["string","null"],"description":"Location slug."}}},"tagged_users":{"type":["array","null"],"description":"Accounts explicitly tagged in the media.","items":{"type":["object","null"],"description":"Tagged account.","properties":{"id":{"type":["string","null"],"description":"Platform account ID."},"username":{"type":["string","null"],"description":"Handle."},"display_name":{"type":["string","null"],"description":"Display name."}}}},"media_assets":{"type":["array","null"],"description":"Returned image/video variants with dimensions.","items":{"type":["object","null"],"description":"One source media variant; URLs may expire.","properties":{"url":{"type":["string","null"],"description":"Source URL."},"width":{"type":["number","null"],"description":"Width in pixels."},"height":{"type":["number","null"],"description":"Height in pixels."},"asset_type":{"type":["string","null"],"description":"image, video, thumbnail or avatar."},"variant":{"type":["string","null"],"description":"Source variant when known."},"expires_at":{"type":["string","null"],"description":"Expiry timestamp when known."}}}},"children":{"type":["array","null"],"description":"Ordered carousel children when returned; null for non-carousels.","items":{"type":["object","null"],"description":"One carousel child.","properties":{"id":{"type":["string","null"],"description":"Media ID."},"position":{"type":["number","null"],"description":"Zero-based position."},"media_type":{"type":["string","null"],"description":"image, video or null."},"media_url":{"type":["string","null"],"description":"Preview image URL."},"video_url":{"type":["string","null"],"description":"Source video URL when available."},"width":{"type":["number","null"],"description":"Width in pixels."},"height":{"type":["number","null"],"description":"Height in pixels."}}}}}}}}}}]}}}},"400":{"$ref":"#/components/responses/InvalidInput"},"401":{"$ref":"#/components/responses/InvalidApiKey"},"402":{"$ref":"#/components/responses/InsufficientCredits"},"403":{"$ref":"#/components/responses/SourceRestricted"},"404":{"$ref":"#/components/responses/ResourceNotFound"},"408":{"$ref":"#/components/responses/SourceTimeout"},"422":{"$ref":"#/components/responses/SourceResponseChanged"},"429":{"$ref":"#/components/responses/TemporaryCapacity"},"501":{"$ref":"#/components/responses/SourceNotImplemented"},"503":{"$ref":"#/components/responses/SourceUnavailable"}},"x-availability":"available","x-identifier-one-of":["id","url"],"x-credits":1,"x-source-access":"public_page","x-preview":false,"x-codeSamples":[{"lang":"curl","source":"curl 'https://api.socialdatakit.com/v1/instagram/post?id=CxDemo123' \\\n  -H 'x-api-key: YOUR_API_KEY'"},{"lang":"javascript","source":"const response = await fetch(\"https://api.socialdatakit.com/v1/instagram/post?id=CxDemo123\", {\n  headers: { \"x-api-key\": process.env.SOCIALDATAKIT_API_KEY }\n});\nif (!response.ok) throw new Error(await response.text());\nconst result = await response.json();"},{"lang":"python","source":"import os\nimport requests\n\nresponse = requests.get(\n    \"https://api.socialdatakit.com/v1/instagram/post?id=CxDemo123\",\n    headers={\"x-api-key\": os.environ[\"SOCIALDATAKIT_API_KEY\"]},\n    timeout=30,\n)\nresponse.raise_for_status()\nresult = response.json()"}],"x-response-fields":{"id":{"type":"string","description":"Resource identifier used by this endpoint."},"author":{"type":"string","description":"Public creator name or handle."},"published_at":{"type":"string","description":"Source publication date or timestamp; null when absent."},"views":{"type":"number","description":"Observed views, where exposed by this source."},"likes":{"type":"number","description":"Observed likes."},"comments":{"type":"number","description":"Observed comment count, not comment rows."},"media_url":{"type":"string","description":"Preview image URL; not a guaranteed downloadable video."},"permalink":{"type":"string","description":"Public content URL."},"duration_seconds":{"type":"number","description":"Duration in seconds when returned."},"hashtags":{"type":"array","description":"Hashtags with platform or derived_text provenance.","items":{"type":"object","description":"Entity observed at source or derived from text.","properties":{"name":{"type":"string","description":"Hashtag or account name."},"id":{"type":"string","description":"Platform ID when supplied."},"source":{"type":"string","description":"platform or derived_text."}}}},"mentions":{"type":"array","description":"Mentions with platform or derived_text provenance; text is not proof of an account relationship.","items":{"type":"object","description":"Entity observed at source or derived from text.","properties":{"name":{"type":"string","description":"Hashtag or account name."},"id":{"type":"string","description":"Platform ID when supplied."},"source":{"type":"string","description":"platform or derived_text."}}}},"author_id":{"type":"string","description":"Stable creator ID when returned."},"author_display_name":{"type":"string","description":"Public display name."},"author_verified":{"type":"boolean","description":"Explicit creator verification state."},"author_avatar_url":{"type":"string","description":"Public creator avatar URL."},"platform_content_id":{"type":"string","description":"Platform media ID, separate from the shortcode."},"caption":{"type":"string","description":"Public caption."},"media_type":{"type":"string","description":"image, video, carousel, or null when unknown."},"media_product_type":{"type":"string","description":"Source product type, kept separate from media type."},"width":{"type":"number","description":"Media width in pixels."},"height":{"type":"number","description":"Media height in pixels."},"video_url":{"type":"string","description":"Source video URL where returned; may expire."},"comments_enabled":{"type":"boolean","description":"Observed comments setting."},"paid_partnership":{"type":"boolean","description":"Explicit source partnership flag; null when unavailable."},"accessibility_caption":{"type":"string","description":"Source alt text or accessibility description."},"location":{"type":"object","description":"Publicly attached location label.","properties":{"id":{"type":"string","description":"Location ID."},"name":{"type":"string","description":"Location name."},"slug":{"type":"string","description":"Location slug."}}},"tagged_users":{"type":"array","description":"Accounts explicitly tagged in the media.","items":{"type":"object","description":"Tagged account.","properties":{"id":{"type":"string","description":"Platform account ID."},"username":{"type":"string","description":"Handle."},"display_name":{"type":"string","description":"Display name."}}}},"media_assets":{"type":"array","description":"Returned image/video variants with dimensions.","items":{"type":"object","description":"One source media variant; URLs may expire.","properties":{"url":{"type":"string","description":"Source URL."},"width":{"type":"number","description":"Width in pixels."},"height":{"type":"number","description":"Height in pixels."},"asset_type":{"type":"string","description":"image, video, thumbnail or avatar."},"variant":{"type":"string","description":"Source variant when known."},"expires_at":{"type":"string","description":"Expiry timestamp when known."}}}},"children":{"type":"array","description":"Ordered carousel children when returned; null for non-carousels.","items":{"type":"object","description":"One carousel child.","properties":{"id":{"type":"string","description":"Media ID."},"position":{"type":"number","description":"Zero-based position."},"media_type":{"type":"string","description":"image, video or null."},"media_url":{"type":"string","description":"Preview image URL."},"video_url":{"type":"string","description":"Source video URL when available."},"width":{"type":"number","description":"Width in pixels."},"height":{"type":"number","description":"Height in pixels."}}}}}}},"/v1/tiktok/profile":{"get":{"operationId":"tiktok_profile","summary":"TikTok profile","description":"Get a public profile’s bio, follower count, total likes, video count and profile picture. Core resource for supplied public handles or content IDs.","tags":["tiktok"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"handle","in":"query","required":false,"schema":{"type":"string","pattern":"^@?[A-Za-z0-9._]{2,24}$","example":"tiktok"},"description":"Required tiktok handle. Supply exactly one of: handle, url."},{"name":"cache_max_age","in":"query","required":false,"schema":{"type":"string","enum":["1d","3d","7d","14d","30d"]},"description":"Maximum acceptable cache age. Valid cache hits cost zero credits."},{"name":"fields","in":"query","required":false,"schema":{"type":"string","example":"profile.username,profile.followers"},"description":"Comma-separated fields or dot paths, including inside arrays such as items.id. Response identity and pagination are retained."},{"name":"trim","in":"query","required":false,"schema":{"type":"boolean","default":false},"description":"Remove null and empty values. Meaningful empty YouTube region-restriction lists are retained."},{"name":"url","in":"query","required":false,"schema":{"type":"string","format":"uri"},"description":"Alternative to handle. Supply exactly one identifier. URLs must belong to tiktok."},{"name":"format","in":"query","required":false,"schema":{"type":"string","enum":["full","compact"],"default":"full"},"description":"compact returns only user and stats. Request ID, live/sample mode, cache and credit details are in response headers. Do not combine with fields or trim."},{"name":"region","in":"query","required":false,"description":"Country code","schema":{"type":"string","pattern":"^[A-Z]{2}$","example":"GB"}}],"responses":{"200":{"description":"Normalized resource","headers":{"x-request-id":{"schema":{"type":"string"}},"x-data-mode":{"schema":{"type":"string","enum":["live","sandbox"]}},"x-cache":{"schema":{"type":"string","enum":["HIT","MISS"]}},"x-credits-charged":{"schema":{"type":"integer"}},"x-credits-remaining":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"oneOf":[{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"data":{"type":"object","properties":{"profile":{"type":"object","additionalProperties":true,"properties":{"id":{"type":["string","null"],"description":"Stable platform account ID when supplied; never an inferred username ID."},"username":{"type":["string","null"],"description":"Current account handle."},"display_name":{"type":["string","null"],"description":"Public display name."},"bio":{"type":["string","null"],"description":"Public biography."},"profile_url":{"type":["string","null"],"description":"Public profile URL."},"followers":{"type":["number","null"],"description":"Observed audience count; page summaries may be rounded."},"following":{"type":["number","null"],"description":"Observed following count."},"posts":{"type":["number","null"],"description":"Observed content count."},"verified":{"type":["boolean","null"],"description":"True or false only when explicitly returned; null means unknown."},"private":{"type":["boolean","null"],"description":"Observed privacy state; null means unknown."},"avatar_url":{"type":["string","null"],"description":"Source avatar URL, which can expire or restrict hotlinking."},"avatar_variants":{"type":["array","null"],"description":"Returned avatar image variants.","items":{"type":["object","null"],"description":"One source media variant; URLs may expire.","properties":{"url":{"type":["string","null"],"description":"Source URL."},"width":{"type":["number","null"],"description":"Width in pixels."},"height":{"type":["number","null"],"description":"Height in pixels."},"asset_type":{"type":["string","null"],"description":"image, video, thumbnail or avatar."},"variant":{"type":["string","null"],"description":"Source variant when known."},"expires_at":{"type":["string","null"],"description":"Expiry timestamp when known."}}}},"external_url":{"type":["string","null"],"description":"Public external website."},"likes":{"type":["number","null"],"description":"Total accumulated account likes."},"region":{"type":["string","null"],"description":"Profile region only when explicitly supplied by TikTok; not inferred from the request location."},"language":{"type":["string","null"],"description":"Profile language only when explicitly supplied by TikTok."}}}}}}}]},{"type":"object","additionalProperties":false,"required":["user","stats"],"properties":{"user":{"type":"object","additionalProperties":false,"required":["id","uniqueId","nickname","verified","region","language"],"properties":{"id":{"type":["string","null"]},"uniqueId":{"type":["string","null"]},"nickname":{"type":["string","null"]},"region":{"type":["string","null"]},"language":{"type":["string","null"]},"verified":{"type":["boolean","null"]}}},"stats":{"type":"object","additionalProperties":false,"required":["followerCount","followingCount","heartCount","videoCount"],"properties":{"followerCount":{"type":["number","null"]},"followingCount":{"type":["number","null"]},"heartCount":{"type":["number","null"]},"videoCount":{"type":["number","null"]}}}}}]}}}},"400":{"$ref":"#/components/responses/InvalidInput"},"401":{"$ref":"#/components/responses/InvalidApiKey"},"402":{"$ref":"#/components/responses/InsufficientCredits"},"403":{"$ref":"#/components/responses/SourceRestricted"},"404":{"$ref":"#/components/responses/ResourceNotFound"},"408":{"$ref":"#/components/responses/SourceTimeout"},"422":{"$ref":"#/components/responses/SourceResponseChanged"},"429":{"$ref":"#/components/responses/TemporaryCapacity"},"501":{"$ref":"#/components/responses/SourceNotImplemented"},"503":{"$ref":"#/components/responses/SourceUnavailable"}},"x-availability":"available","x-identifier-one-of":["handle","url"],"x-credits":1,"x-source-access":"public_page","x-preview":false,"x-codeSamples":[{"lang":"curl","source":"curl 'https://api.socialdatakit.com/v1/tiktok/profile?handle=tiktok' \\\n  -H 'x-api-key: YOUR_API_KEY'"},{"lang":"javascript","source":"const response = await fetch(\"https://api.socialdatakit.com/v1/tiktok/profile?handle=tiktok\", {\n  headers: { \"x-api-key\": process.env.SOCIALDATAKIT_API_KEY }\n});\nif (!response.ok) throw new Error(await response.text());\nconst result = await response.json();"},{"lang":"python","source":"import os\nimport requests\n\nresponse = requests.get(\n    \"https://api.socialdatakit.com/v1/tiktok/profile?handle=tiktok\",\n    headers={\"x-api-key\": os.environ[\"SOCIALDATAKIT_API_KEY\"]},\n    timeout=30,\n)\nresponse.raise_for_status()\nresult = response.json()"}],"x-response-fields":{"id":{"type":"string","description":"Stable platform account ID when supplied; never an inferred username ID."},"username":{"type":"string","description":"Current account handle."},"display_name":{"type":"string","description":"Public display name."},"bio":{"type":"string","description":"Public biography."},"profile_url":{"type":"string","description":"Public profile URL."},"followers":{"type":"number","description":"Observed audience count; page summaries may be rounded."},"following":{"type":"number","description":"Observed following count."},"posts":{"type":"number","description":"Observed content count."},"verified":{"type":"boolean","description":"True or false only when explicitly returned; null means unknown."},"private":{"type":"boolean","description":"Observed privacy state; null means unknown."},"avatar_url":{"type":"string","description":"Source avatar URL, which can expire or restrict hotlinking."},"avatar_variants":{"type":"array","description":"Returned avatar image variants.","items":{"type":"object","description":"One source media variant; URLs may expire.","properties":{"url":{"type":"string","description":"Source URL."},"width":{"type":"number","description":"Width in pixels."},"height":{"type":"number","description":"Height in pixels."},"asset_type":{"type":"string","description":"image, video, thumbnail or avatar."},"variant":{"type":"string","description":"Source variant when known."},"expires_at":{"type":"string","description":"Expiry timestamp when known."}}}},"external_url":{"type":"string","description":"Public external website."},"likes":{"type":"number","description":"Total accumulated account likes."},"region":{"type":"string","description":"Profile region only when explicitly supplied by TikTok; not inferred from the request location."},"language":{"type":"string","description":"Profile language only when explicitly supplied by TikTok."}}}},"/v1/tiktok/videos":{"get":{"operationId":"tiktok_videos","summary":"TikTok videos","description":"Get videos from a public profile with captions, covers and available view counts. Some sources return only the latest ten videos. Core resource for supplied public handles or content IDs.","tags":["tiktok"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"handle","in":"query","required":true,"schema":{"type":"string","pattern":"^@?[A-Za-z0-9._]{2,24}$","example":"tiktok"},"description":"Required tiktok handle."},{"name":"cache_max_age","in":"query","required":false,"schema":{"type":"string","enum":["1d","3d","7d","14d","30d"]},"description":"Maximum acceptable cache age. Valid cache hits cost zero credits."},{"name":"fields","in":"query","required":false,"schema":{"type":"string","example":"items"},"description":"Comma-separated fields or dot paths, including inside arrays such as items.id. Response identity and pagination are retained."},{"name":"trim","in":"query","required":false,"schema":{"type":"boolean","default":false},"description":"Remove null and empty values. Meaningful empty YouTube region-restriction lists are retained."},{"name":"region","in":"query","required":false,"description":"Country code","schema":{"type":"string","pattern":"^[A-Z]{2}$","example":"GB"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":20,"default":3},"description":"Number of items to return."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"},"description":"Opaque pagination value returned as data.pagination.next_cursor. Keep the identifier, filters and limit unchanged."}],"responses":{"200":{"description":"Normalized resource","headers":{"x-request-id":{"schema":{"type":"string"}},"x-data-mode":{"schema":{"type":"string","enum":["live","sandbox"]}},"x-cache":{"schema":{"type":"string","enum":["HIT","MISS"]}},"x-credits-charged":{"schema":{"type":"integer"}},"x-credits-remaining":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"data":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","additionalProperties":true,"properties":{"id":{"type":["string","null"],"description":"Resource identifier used by this endpoint."},"author":{"type":["string","null"],"description":"Public creator name or handle."},"published_at":{"type":["string","null"],"description":"Source publication date or timestamp; null when absent."},"views":{"type":["number","null"],"description":"Observed views, where exposed by this source."},"likes":{"type":["number","null"],"description":"Observed likes."},"comments":{"type":["number","null"],"description":"Observed comment count, not comment rows."},"media_url":{"type":["string","null"],"description":"Preview image URL; not a guaranteed downloadable video."},"permalink":{"type":["string","null"],"description":"Public content URL."},"duration_seconds":{"type":["number","null"],"description":"Duration in seconds when returned."},"hashtags":{"type":["array","null"],"description":"Hashtags with platform or derived_text provenance.","items":{"type":["object","null"],"description":"Entity observed at source or derived from text.","properties":{"name":{"type":["string","null"],"description":"Hashtag or account name."},"id":{"type":["string","null"],"description":"Platform ID when supplied."},"source":{"type":["string","null"],"description":"platform or derived_text."}}}},"mentions":{"type":["array","null"],"description":"Mentions with platform or derived_text provenance; text is not proof of an account relationship.","items":{"type":["object","null"],"description":"Entity observed at source or derived from text.","properties":{"name":{"type":["string","null"],"description":"Hashtag or account name."},"id":{"type":["string","null"],"description":"Platform ID when supplied."},"source":{"type":["string","null"],"description":"platform or derived_text."}}}},"caption":{"type":["string","null"],"description":"Public video description."},"shares":{"type":["number","null"],"description":"Observed shares."},"favorites":{"type":["number","null"],"description":"Observed collect count; null when absent."},"width":{"type":["number","null"],"description":"Video width in pixels."},"height":{"type":["number","null"],"description":"Video height in pixels."},"author_id":{"type":["string","null"],"description":"Stable creator ID when returned."},"author_display_name":{"type":["string","null"],"description":"Public display name."},"author_verified":{"type":["boolean","null"],"description":"Explicit creator verification state."},"author_avatar_url":{"type":["string","null"],"description":"Public creator avatar URL."},"region_code":{"type":["string","null"],"description":"Source content region code when exposed; not proof of creator residence."},"video_url":{"type":["string","null"],"description":"Public playback URL when supplied; may expire or require source request headers."},"subtitle_tracks":{"type":["array","null"],"description":"Subtitle links exposed by the public video; does not run transcription.","items":{"type":["object","null"],"description":"Subtitle track.","properties":{"language":{"type":["string","null"],"description":"Source language code."},"language_id":{"type":["string","null"],"description":"Source language identifier."},"url":{"type":["string","null"],"description":"Source subtitle URL."},"format":{"type":["string","null"],"description":"Subtitle format."}}}},"effects":{"type":["array","null"],"description":"Effect metadata exposed by the public page.","items":{"type":["object","null"],"description":"Effect.","properties":{"id":{"type":["string","null"],"description":"Effect ID."},"name":{"type":["string","null"],"description":"Effect name."}}}},"stickers":{"type":["array","null"],"description":"Sticker metadata exposed by the public page.","items":{"type":["object","null"],"description":"Sticker.","properties":{"type":{"type":["number","null"],"description":"Source sticker type."},"texts":{"type":["array","null"],"description":"Returned sticker text.","items":{"type":["string","null"],"description":"Text."}}}}},"music":{"type":["object","null"],"description":"Sound metadata from the public video.","properties":{"id":{"type":["string","null"],"description":"Sound ID."},"title":{"type":["string","null"],"description":"Sound title."},"author":{"type":["string","null"],"description":"Sound author."},"original":{"type":["boolean","null"],"description":"Source original-sound flag."},"duration_seconds":{"type":["number","null"],"description":"Sound duration."},"cover_url":{"type":["string","null"],"description":"Sound cover URL."},"play_url":{"type":["string","null"],"description":"Sound preview URL."}}},"playlist_id":{"type":["string","null"],"description":"Source playlist ID when returned."},"pinned":{"type":["boolean","null"],"description":"Explicit pinned-item state when returned."},"media_assets":{"type":["array","null"],"description":"Returned cover variants.","items":{"type":["object","null"],"description":"One source media variant; URLs may expire.","properties":{"url":{"type":["string","null"],"description":"Source URL."},"width":{"type":["number","null"],"description":"Width in pixels."},"height":{"type":["number","null"],"description":"Height in pixels."},"asset_type":{"type":["string","null"],"description":"image, video, thumbnail or avatar."},"variant":{"type":["string","null"],"description":"Source variant when known."},"expires_at":{"type":["string","null"],"description":"Expiry timestamp when known."}}}}}}}}}}}]}}}},"400":{"$ref":"#/components/responses/InvalidInput"},"401":{"$ref":"#/components/responses/InvalidApiKey"},"402":{"$ref":"#/components/responses/InsufficientCredits"},"403":{"$ref":"#/components/responses/SourceRestricted"},"404":{"$ref":"#/components/responses/ResourceNotFound"},"408":{"$ref":"#/components/responses/SourceTimeout"},"422":{"$ref":"#/components/responses/SourceResponseChanged"},"429":{"$ref":"#/components/responses/TemporaryCapacity"},"501":{"$ref":"#/components/responses/SourceNotImplemented"},"503":{"$ref":"#/components/responses/SourceUnavailable"}},"x-availability":"available","x-identifier-one-of":["handle"],"x-credits":2,"x-source-access":"public_page","x-preview":false,"x-codeSamples":[{"lang":"curl","source":"curl 'https://api.socialdatakit.com/v1/tiktok/videos?handle=tiktok' \\\n  -H 'x-api-key: YOUR_API_KEY'"},{"lang":"javascript","source":"const response = await fetch(\"https://api.socialdatakit.com/v1/tiktok/videos?handle=tiktok\", {\n  headers: { \"x-api-key\": process.env.SOCIALDATAKIT_API_KEY }\n});\nif (!response.ok) throw new Error(await response.text());\nconst result = await response.json();"},{"lang":"python","source":"import os\nimport requests\n\nresponse = requests.get(\n    \"https://api.socialdatakit.com/v1/tiktok/videos?handle=tiktok\",\n    headers={\"x-api-key\": os.environ[\"SOCIALDATAKIT_API_KEY\"]},\n    timeout=30,\n)\nresponse.raise_for_status()\nresult = response.json()"}],"x-response-fields":{"id":{"type":"string","description":"Resource identifier used by this endpoint."},"author":{"type":"string","description":"Public creator name or handle."},"published_at":{"type":"string","description":"Source publication date or timestamp; null when absent."},"views":{"type":"number","description":"Observed views, where exposed by this source."},"likes":{"type":"number","description":"Observed likes."},"comments":{"type":"number","description":"Observed comment count, not comment rows."},"media_url":{"type":"string","description":"Preview image URL; not a guaranteed downloadable video."},"permalink":{"type":"string","description":"Public content URL."},"duration_seconds":{"type":"number","description":"Duration in seconds when returned."},"hashtags":{"type":"array","description":"Hashtags with platform or derived_text provenance.","items":{"type":"object","description":"Entity observed at source or derived from text.","properties":{"name":{"type":"string","description":"Hashtag or account name."},"id":{"type":"string","description":"Platform ID when supplied."},"source":{"type":"string","description":"platform or derived_text."}}}},"mentions":{"type":"array","description":"Mentions with platform or derived_text provenance; text is not proof of an account relationship.","items":{"type":"object","description":"Entity observed at source or derived from text.","properties":{"name":{"type":"string","description":"Hashtag or account name."},"id":{"type":"string","description":"Platform ID when supplied."},"source":{"type":"string","description":"platform or derived_text."}}}},"caption":{"type":"string","description":"Public video description."},"shares":{"type":"number","description":"Observed shares."},"favorites":{"type":"number","description":"Observed collect count; null when absent."},"width":{"type":"number","description":"Video width in pixels."},"height":{"type":"number","description":"Video height in pixels."},"author_id":{"type":"string","description":"Stable creator ID when returned."},"author_display_name":{"type":"string","description":"Public display name."},"author_verified":{"type":"boolean","description":"Explicit creator verification state."},"author_avatar_url":{"type":"string","description":"Public creator avatar URL."},"region_code":{"type":"string","description":"Source content region code when exposed; not proof of creator residence."},"video_url":{"type":"string","description":"Public playback URL when supplied; may expire or require source request headers."},"subtitle_tracks":{"type":"array","description":"Subtitle links exposed by the public video; does not run transcription.","items":{"type":"object","description":"Subtitle track.","properties":{"language":{"type":"string","description":"Source language code."},"language_id":{"type":"string","description":"Source language identifier."},"url":{"type":"string","description":"Source subtitle URL."},"format":{"type":"string","description":"Subtitle format."}}}},"effects":{"type":"array","description":"Effect metadata exposed by the public page.","items":{"type":"object","description":"Effect.","properties":{"id":{"type":"string","description":"Effect ID."},"name":{"type":"string","description":"Effect name."}}}},"stickers":{"type":"array","description":"Sticker metadata exposed by the public page.","items":{"type":"object","description":"Sticker.","properties":{"type":{"type":"number","description":"Source sticker type."},"texts":{"type":"array","description":"Returned sticker text.","items":{"type":"string","description":"Text."}}}}},"music":{"type":"object","description":"Sound metadata from the public video.","properties":{"id":{"type":"string","description":"Sound ID."},"title":{"type":"string","description":"Sound title."},"author":{"type":"string","description":"Sound author."},"original":{"type":"boolean","description":"Source original-sound flag."},"duration_seconds":{"type":"number","description":"Sound duration."},"cover_url":{"type":"string","description":"Sound cover URL."},"play_url":{"type":"string","description":"Sound preview URL."}}},"playlist_id":{"type":"string","description":"Source playlist ID when returned."},"pinned":{"type":"boolean","description":"Explicit pinned-item state when returned."},"media_assets":{"type":"array","description":"Returned cover variants.","items":{"type":"object","description":"One source media variant; URLs may expire.","properties":{"url":{"type":"string","description":"Source URL."},"width":{"type":"number","description":"Width in pixels."},"height":{"type":"number","description":"Height in pixels."},"asset_type":{"type":"string","description":"image, video, thumbnail or avatar."},"variant":{"type":"string","description":"Source variant when known."},"expires_at":{"type":"string","description":"Expiry timestamp when known."}}}}}}},"/v1/tiktok/video":{"get":{"operationId":"tiktok_video","summary":"TikTok video","description":"Get a public video’s caption, creator, cover and available metrics. Some videos return fewer details. Core resource for supplied public handles or content IDs.","tags":["tiktok"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"id","in":"query","required":true,"schema":{"type":"string","pattern":"^[0-9]{10,24}$","example":"7350000000000000000"},"description":"Required tiktok id."},{"name":"cache_max_age","in":"query","required":false,"schema":{"type":"string","enum":["1d","3d","7d","14d","30d"]},"description":"Maximum acceptable cache age. Valid cache hits cost zero credits."},{"name":"fields","in":"query","required":false,"schema":{"type":"string","example":"item"},"description":"Comma-separated fields or dot paths, including inside arrays such as items.id. Response identity and pagination are retained."},{"name":"trim","in":"query","required":false,"schema":{"type":"boolean","default":false},"description":"Remove null and empty values. Meaningful empty YouTube region-restriction lists are retained."},{"name":"region","in":"query","required":false,"description":"Country code","schema":{"type":"string","pattern":"^[A-Z]{2}$","example":"GB"}}],"responses":{"200":{"description":"Normalized resource","headers":{"x-request-id":{"schema":{"type":"string"}},"x-data-mode":{"schema":{"type":"string","enum":["live","sandbox"]}},"x-cache":{"schema":{"type":"string","enum":["HIT","MISS"]}},"x-credits-charged":{"schema":{"type":"integer"}},"x-credits-remaining":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"data":{"type":"object","properties":{"item":{"type":"object","additionalProperties":true,"properties":{"id":{"type":["string","null"],"description":"Resource identifier used by this endpoint."},"author":{"type":["string","null"],"description":"Public creator name or handle."},"published_at":{"type":["string","null"],"description":"Source publication date or timestamp; null when absent."},"views":{"type":["number","null"],"description":"Observed views, where exposed by this source."},"likes":{"type":["number","null"],"description":"Observed likes."},"comments":{"type":["number","null"],"description":"Observed comment count, not comment rows."},"media_url":{"type":["string","null"],"description":"Preview image URL; not a guaranteed downloadable video."},"permalink":{"type":["string","null"],"description":"Public content URL."},"duration_seconds":{"type":["number","null"],"description":"Duration in seconds when returned."},"hashtags":{"type":["array","null"],"description":"Hashtags with platform or derived_text provenance.","items":{"type":["object","null"],"description":"Entity observed at source or derived from text.","properties":{"name":{"type":["string","null"],"description":"Hashtag or account name."},"id":{"type":["string","null"],"description":"Platform ID when supplied."},"source":{"type":["string","null"],"description":"platform or derived_text."}}}},"mentions":{"type":["array","null"],"description":"Mentions with platform or derived_text provenance; text is not proof of an account relationship.","items":{"type":["object","null"],"description":"Entity observed at source or derived from text.","properties":{"name":{"type":["string","null"],"description":"Hashtag or account name."},"id":{"type":["string","null"],"description":"Platform ID when supplied."},"source":{"type":["string","null"],"description":"platform or derived_text."}}}},"caption":{"type":["string","null"],"description":"Public video description."},"shares":{"type":["number","null"],"description":"Observed shares."},"favorites":{"type":["number","null"],"description":"Observed collect count; null when absent."},"width":{"type":["number","null"],"description":"Video width in pixels."},"height":{"type":["number","null"],"description":"Video height in pixels."},"author_id":{"type":["string","null"],"description":"Stable creator ID when returned."},"author_display_name":{"type":["string","null"],"description":"Public display name."},"author_verified":{"type":["boolean","null"],"description":"Explicit creator verification state."},"author_avatar_url":{"type":["string","null"],"description":"Public creator avatar URL."},"region_code":{"type":["string","null"],"description":"Source content region code when exposed; not proof of creator residence."},"video_url":{"type":["string","null"],"description":"Public playback URL when supplied; may expire or require source request headers."},"subtitle_tracks":{"type":["array","null"],"description":"Subtitle links exposed by the public video; does not run transcription.","items":{"type":["object","null"],"description":"Subtitle track.","properties":{"language":{"type":["string","null"],"description":"Source language code."},"language_id":{"type":["string","null"],"description":"Source language identifier."},"url":{"type":["string","null"],"description":"Source subtitle URL."},"format":{"type":["string","null"],"description":"Subtitle format."}}}},"effects":{"type":["array","null"],"description":"Effect metadata exposed by the public page.","items":{"type":["object","null"],"description":"Effect.","properties":{"id":{"type":["string","null"],"description":"Effect ID."},"name":{"type":["string","null"],"description":"Effect name."}}}},"stickers":{"type":["array","null"],"description":"Sticker metadata exposed by the public page.","items":{"type":["object","null"],"description":"Sticker.","properties":{"type":{"type":["number","null"],"description":"Source sticker type."},"texts":{"type":["array","null"],"description":"Returned sticker text.","items":{"type":["string","null"],"description":"Text."}}}}},"music":{"type":["object","null"],"description":"Sound metadata from the public video.","properties":{"id":{"type":["string","null"],"description":"Sound ID."},"title":{"type":["string","null"],"description":"Sound title."},"author":{"type":["string","null"],"description":"Sound author."},"original":{"type":["boolean","null"],"description":"Source original-sound flag."},"duration_seconds":{"type":["number","null"],"description":"Sound duration."},"cover_url":{"type":["string","null"],"description":"Sound cover URL."},"play_url":{"type":["string","null"],"description":"Sound preview URL."}}},"playlist_id":{"type":["string","null"],"description":"Source playlist ID when returned."},"pinned":{"type":["boolean","null"],"description":"Explicit pinned-item state when returned."},"media_assets":{"type":["array","null"],"description":"Returned cover variants.","items":{"type":["object","null"],"description":"One source media variant; URLs may expire.","properties":{"url":{"type":["string","null"],"description":"Source URL."},"width":{"type":["number","null"],"description":"Width in pixels."},"height":{"type":["number","null"],"description":"Height in pixels."},"asset_type":{"type":["string","null"],"description":"image, video, thumbnail or avatar."},"variant":{"type":["string","null"],"description":"Source variant when known."},"expires_at":{"type":["string","null"],"description":"Expiry timestamp when known."}}}}}}}}}}]}}}},"400":{"$ref":"#/components/responses/InvalidInput"},"401":{"$ref":"#/components/responses/InvalidApiKey"},"402":{"$ref":"#/components/responses/InsufficientCredits"},"403":{"$ref":"#/components/responses/SourceRestricted"},"404":{"$ref":"#/components/responses/ResourceNotFound"},"408":{"$ref":"#/components/responses/SourceTimeout"},"422":{"$ref":"#/components/responses/SourceResponseChanged"},"429":{"$ref":"#/components/responses/TemporaryCapacity"},"501":{"$ref":"#/components/responses/SourceNotImplemented"},"503":{"$ref":"#/components/responses/SourceUnavailable"}},"x-availability":"available","x-identifier-one-of":["id"],"x-credits":1,"x-source-access":"public_page","x-preview":false,"x-codeSamples":[{"lang":"curl","source":"curl 'https://api.socialdatakit.com/v1/tiktok/video?id=7350000000000000000' \\\n  -H 'x-api-key: YOUR_API_KEY'"},{"lang":"javascript","source":"const response = await fetch(\"https://api.socialdatakit.com/v1/tiktok/video?id=7350000000000000000\", {\n  headers: { \"x-api-key\": process.env.SOCIALDATAKIT_API_KEY }\n});\nif (!response.ok) throw new Error(await response.text());\nconst result = await response.json();"},{"lang":"python","source":"import os\nimport requests\n\nresponse = requests.get(\n    \"https://api.socialdatakit.com/v1/tiktok/video?id=7350000000000000000\",\n    headers={\"x-api-key\": os.environ[\"SOCIALDATAKIT_API_KEY\"]},\n    timeout=30,\n)\nresponse.raise_for_status()\nresult = response.json()"}],"x-response-fields":{"id":{"type":"string","description":"Resource identifier used by this endpoint."},"author":{"type":"string","description":"Public creator name or handle."},"published_at":{"type":"string","description":"Source publication date or timestamp; null when absent."},"views":{"type":"number","description":"Observed views, where exposed by this source."},"likes":{"type":"number","description":"Observed likes."},"comments":{"type":"number","description":"Observed comment count, not comment rows."},"media_url":{"type":"string","description":"Preview image URL; not a guaranteed downloadable video."},"permalink":{"type":"string","description":"Public content URL."},"duration_seconds":{"type":"number","description":"Duration in seconds when returned."},"hashtags":{"type":"array","description":"Hashtags with platform or derived_text provenance.","items":{"type":"object","description":"Entity observed at source or derived from text.","properties":{"name":{"type":"string","description":"Hashtag or account name."},"id":{"type":"string","description":"Platform ID when supplied."},"source":{"type":"string","description":"platform or derived_text."}}}},"mentions":{"type":"array","description":"Mentions with platform or derived_text provenance; text is not proof of an account relationship.","items":{"type":"object","description":"Entity observed at source or derived from text.","properties":{"name":{"type":"string","description":"Hashtag or account name."},"id":{"type":"string","description":"Platform ID when supplied."},"source":{"type":"string","description":"platform or derived_text."}}}},"caption":{"type":"string","description":"Public video description."},"shares":{"type":"number","description":"Observed shares."},"favorites":{"type":"number","description":"Observed collect count; null when absent."},"width":{"type":"number","description":"Video width in pixels."},"height":{"type":"number","description":"Video height in pixels."},"author_id":{"type":"string","description":"Stable creator ID when returned."},"author_display_name":{"type":"string","description":"Public display name."},"author_verified":{"type":"boolean","description":"Explicit creator verification state."},"author_avatar_url":{"type":"string","description":"Public creator avatar URL."},"region_code":{"type":"string","description":"Source content region code when exposed; not proof of creator residence."},"video_url":{"type":"string","description":"Public playback URL when supplied; may expire or require source request headers."},"subtitle_tracks":{"type":"array","description":"Subtitle links exposed by the public video; does not run transcription.","items":{"type":"object","description":"Subtitle track.","properties":{"language":{"type":"string","description":"Source language code."},"language_id":{"type":"string","description":"Source language identifier."},"url":{"type":"string","description":"Source subtitle URL."},"format":{"type":"string","description":"Subtitle format."}}}},"effects":{"type":"array","description":"Effect metadata exposed by the public page.","items":{"type":"object","description":"Effect.","properties":{"id":{"type":"string","description":"Effect ID."},"name":{"type":"string","description":"Effect name."}}}},"stickers":{"type":"array","description":"Sticker metadata exposed by the public page.","items":{"type":"object","description":"Sticker.","properties":{"type":{"type":"number","description":"Source sticker type."},"texts":{"type":"array","description":"Returned sticker text.","items":{"type":"string","description":"Text."}}}}},"music":{"type":"object","description":"Sound metadata from the public video.","properties":{"id":{"type":"string","description":"Sound ID."},"title":{"type":"string","description":"Sound title."},"author":{"type":"string","description":"Sound author."},"original":{"type":"boolean","description":"Source original-sound flag."},"duration_seconds":{"type":"number","description":"Sound duration."},"cover_url":{"type":"string","description":"Sound cover URL."},"play_url":{"type":"string","description":"Sound preview URL."}}},"playlist_id":{"type":"string","description":"Source playlist ID when returned."},"pinned":{"type":"boolean","description":"Explicit pinned-item state when returned."},"media_assets":{"type":"array","description":"Returned cover variants.","items":{"type":"object","description":"One source media variant; URLs may expire.","properties":{"url":{"type":"string","description":"Source URL."},"width":{"type":"number","description":"Width in pixels."},"height":{"type":"number","description":"Height in pixels."},"asset_type":{"type":"string","description":"image, video, thumbnail or avatar."},"variant":{"type":"string","description":"Source variant when known."},"expires_at":{"type":"string","description":"Expiry timestamp when known."}}}}}}},"/v1/youtube/video":{"get":{"operationId":"youtube_video","summary":"YouTube video","description":"Get a video’s title, channel, description, duration, thumbnails and available view counts. Core resource for supplied public handles or content IDs.","tags":["youtube"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"id","in":"query","required":false,"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{11}$","example":"dQw4w9WgXcQ"},"description":"Required youtube id. Supply exactly one of: id, url."},{"name":"cache_max_age","in":"query","required":false,"schema":{"type":"string","enum":["1d","3d","7d","14d","30d"]},"description":"Maximum acceptable cache age. Valid cache hits cost zero credits."},{"name":"fields","in":"query","required":false,"schema":{"type":"string","example":"item"},"description":"Comma-separated fields or dot paths, including inside arrays such as items.id. Response identity and pagination are retained."},{"name":"trim","in":"query","required":false,"schema":{"type":"boolean","default":false},"description":"Remove null and empty values. Meaningful empty YouTube region-restriction lists are retained."},{"name":"url","in":"query","required":false,"schema":{"type":"string","format":"uri"},"description":"Alternative to id. Supply exactly one identifier. URLs must belong to youtube."}],"responses":{"200":{"description":"Normalized resource","headers":{"x-request-id":{"schema":{"type":"string"}},"x-data-mode":{"schema":{"type":"string","enum":["live","sandbox"]}},"x-cache":{"schema":{"type":"string","enum":["HIT","MISS"]}},"x-credits-charged":{"schema":{"type":"integer"}},"x-credits-remaining":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"data":{"type":"object","properties":{"item":{"type":"object","additionalProperties":true,"properties":{"id":{"type":["string","null"],"description":"Resource identifier used by this endpoint."},"author":{"type":["string","null"],"description":"Public creator name or handle."},"published_at":{"type":["string","null"],"description":"Source publication date or timestamp; null when absent."},"views":{"type":["number","null"],"description":"Observed views, where exposed by this source."},"likes":{"type":["number","null"],"description":"Observed likes."},"comments":{"type":["number","null"],"description":"Observed comment count, not comment rows."},"media_url":{"type":["string","null"],"description":"Preview image URL; not a guaranteed downloadable video."},"permalink":{"type":["string","null"],"description":"Public content URL."},"duration_seconds":{"type":["number","null"],"description":"Duration in seconds when returned."},"hashtags":{"type":["array","null"],"description":"Hashtags with platform or derived_text provenance.","items":{"type":["object","null"],"description":"Entity observed at source or derived from text.","properties":{"name":{"type":["string","null"],"description":"Hashtag or account name."},"id":{"type":["string","null"],"description":"Platform ID when supplied."},"source":{"type":["string","null"],"description":"platform or derived_text."}}}},"mentions":{"type":["array","null"],"description":"Mentions with platform or derived_text provenance; text is not proof of an account relationship.","items":{"type":["object","null"],"description":"Entity observed at source or derived from text.","properties":{"name":{"type":["string","null"],"description":"Hashtag or account name."},"id":{"type":["string","null"],"description":"Platform ID when supplied."},"source":{"type":["string","null"],"description":"platform or derived_text."}}}},"category_id":{"type":["string","null"],"description":"YouTube category ID."},"language":{"type":["string","null"],"description":"Default metadata language."},"audio_language":{"type":["string","null"],"description":"Default audio language."},"localized":{"type":["object","null"],"description":"Selected localized text.","properties":{"title":{"type":["string","null"],"description":"Title."},"description":{"type":["string","null"],"description":"Description."}}},"localizations":{"type":["object","null"],"description":"Returned language-to-title/description map."},"duration_iso8601":{"type":["string","null"],"description":"Source ISO 8601 duration."},"dimension":{"type":["string","null"],"description":"2d or 3d."},"definition":{"type":["string","null"],"description":"hd or sd."},"licensed_content":{"type":["boolean","null"],"description":"Source licensed-content flag."},"region_restriction":{"type":["object","null"],"description":"An omitted list differs from an empty list. An empty allowed list blocks everywhere; an empty blocked list blocks nowhere.","properties":{"allowed":{"type":["array","null"],"description":"Countries where viewing is permitted.","items":{"type":["string","null"],"description":"Source value."}},"blocked":{"type":["array","null"],"description":"Countries where viewing is blocked.","items":{"type":["string","null"],"description":"Source value."}}}},"content_rating":{"type":["object","null"],"description":"Country/authority rating map retained without enumerating columns."},"projection":{"type":["string","null"],"description":"Projection format."},"privacy_status":{"type":["string","null"],"description":"Source public/unlisted status when returned without account authorization."},"license":{"type":["string","null"],"description":"Source license."},"public_stats_viewable":{"type":["boolean","null"],"description":"Source public-statistics setting."},"made_for_kids":{"type":["boolean","null"],"description":"Current source designation when publicly returned; not the owner-only self-declared setting."},"contains_synthetic_media":{"type":["boolean","null"],"description":"Source altered/synthetic-media disclosure when publicly returned; not an AI prediction."},"paid_partnership":{"type":["boolean","null"],"description":"Explicit source paid-product-placement flag when publicly returned."},"topic_ids":{"type":["array","null"],"description":"Legacy source topic IDs, when returned.","items":{"type":["string","null"],"description":"Source value."}},"topic_categories":{"type":["array","null"],"description":"Topic-category URLs.","items":{"type":["string","null"],"description":"Source value."}},"recording_date":{"type":["string","null"],"description":"Public recording date, when returned."},"embed_html":{"type":["string","null"],"description":"Source embed markup as a string. Never execute returned HTML without sanitizing."},"embed_height":{"type":["number","null"],"description":"Source embed height."},"embed_width":{"type":["number","null"],"description":"Source embed width."},"live_status":{"type":["string","null"],"description":"live, upcoming or none when supplied."},"title":{"type":["string","null"],"description":"Video title."},"description":{"type":["string","null"],"description":"Video description."},"channel_id":{"type":["string","null"],"description":"Owning channel ID."},"tags":{"type":["array","null"],"description":"Keyword tags; distinct from hashtags.","items":{"type":["string","null"],"description":"Keyword tag."}},"thumbnails":{"type":["array","null"],"description":"Returned thumbnail variants and dimensions.","items":{"type":["object","null"],"description":"One source media variant; URLs may expire.","properties":{"url":{"type":["string","null"],"description":"Source URL."},"width":{"type":["number","null"],"description":"Width in pixels."},"height":{"type":["number","null"],"description":"Height in pixels."},"asset_type":{"type":["string","null"],"description":"image, video, thumbnail or avatar."},"variant":{"type":["string","null"],"description":"Source variant when known."},"expires_at":{"type":["string","null"],"description":"Expiry timestamp when known."}}}},"author_avatar_url":{"type":["string","null"],"description":"Channel avatar from the watch page."},"channel_url":{"type":["string","null"],"description":"Channel URL built from the observed channel ID."},"upload_date":{"type":["string","null"],"description":"Source upload date, separate from publication date."},"available_countries":{"type":["array","null"],"description":"Allowed country list when the player exposes it; no inferred blocked countries.","items":{"type":["string","null"],"description":"Country code."}},"unlisted":{"type":["boolean","null"],"description":"Source unlisted flag."},"family_safe":{"type":["boolean","null"],"description":"Source family-safe flag; not the made-for-kids designation."},"counts_rounded":{"type":["object","null"],"description":"Precision of observed counters. Unknown precision is null.","properties":{"views":{"type":["boolean","null"],"description":"Views rounded."},"likes":{"type":["boolean","null"],"description":"Likes rounded."},"comments":{"type":["boolean","null"],"description":"Comments rounded."}}},"caption_tracks":{"type":["array","null"],"description":"Caption-track metadata without caption text.","items":{"type":["object","null"],"description":"One available caption language; URLs are not returned.","properties":{"language":{"type":["string","null"],"description":"Source language code."},"language_name":{"type":["string","null"],"description":"Source language label."},"generated":{"type":["boolean","null"],"description":"True for an automatic caption track."},"translatable":{"type":["boolean","null"],"description":"Source translation capability."}}}},"category":{"type":["string","null"],"description":"Source category name."},"is_live":{"type":["boolean","null"],"description":"Explicit current live state."},"is_live_content":{"type":["boolean","null"],"description":"Explicit live-content classification."},"captions_available":{"type":["boolean","null"],"description":"Caption-track availability when observable."},"embeddable":{"type":["boolean","null"],"description":"Player embed permission when returned."},"live":{"type":["object","null"],"description":"Returned broadcast start/end times and live-now state.","properties":{"actual_start_time":{"type":["string","null"],"description":"Source broadcast start time."},"actual_end_time":{"type":["string","null"],"description":"Source broadcast end time."},"is_live_now":{"type":["boolean","null"],"description":"Explicit live-now state."},"scheduled_start_time":{"type":["string","null"],"description":"Scheduled start time."},"scheduled_end_time":{"type":["string","null"],"description":"Scheduled end time."},"concurrent_viewers":{"type":["number","null"],"description":"Current live viewers, when public."},"active_live_chat_id":{"type":["string","null"],"description":"Active public live-chat ID when supplied."}}}}}}}}}]}}}},"400":{"$ref":"#/components/responses/InvalidInput"},"401":{"$ref":"#/components/responses/InvalidApiKey"},"402":{"$ref":"#/components/responses/InsufficientCredits"},"403":{"$ref":"#/components/responses/SourceRestricted"},"404":{"$ref":"#/components/responses/ResourceNotFound"},"408":{"$ref":"#/components/responses/SourceTimeout"},"422":{"$ref":"#/components/responses/SourceResponseChanged"},"429":{"$ref":"#/components/responses/TemporaryCapacity"},"501":{"$ref":"#/components/responses/SourceNotImplemented"},"503":{"$ref":"#/components/responses/SourceUnavailable"}},"x-availability":"available","x-identifier-one-of":["id","url"],"x-credits":1,"x-source-access":"public_page","x-preview":false,"x-codeSamples":[{"lang":"curl","source":"curl 'https://api.socialdatakit.com/v1/youtube/video?id=dQw4w9WgXcQ' \\\n  -H 'x-api-key: YOUR_API_KEY'"},{"lang":"javascript","source":"const response = await fetch(\"https://api.socialdatakit.com/v1/youtube/video?id=dQw4w9WgXcQ\", {\n  headers: { \"x-api-key\": process.env.SOCIALDATAKIT_API_KEY }\n});\nif (!response.ok) throw new Error(await response.text());\nconst result = await response.json();"},{"lang":"python","source":"import os\nimport requests\n\nresponse = requests.get(\n    \"https://api.socialdatakit.com/v1/youtube/video?id=dQw4w9WgXcQ\",\n    headers={\"x-api-key\": os.environ[\"SOCIALDATAKIT_API_KEY\"]},\n    timeout=30,\n)\nresponse.raise_for_status()\nresult = response.json()"}],"x-response-fields":{"id":{"type":"string","description":"Resource identifier used by this endpoint."},"author":{"type":"string","description":"Public creator name or handle."},"published_at":{"type":"string","description":"Source publication date or timestamp; null when absent."},"views":{"type":"number","description":"Observed views, where exposed by this source."},"likes":{"type":"number","description":"Observed likes."},"comments":{"type":"number","description":"Observed comment count, not comment rows."},"media_url":{"type":"string","description":"Preview image URL; not a guaranteed downloadable video."},"permalink":{"type":"string","description":"Public content URL."},"duration_seconds":{"type":"number","description":"Duration in seconds when returned."},"hashtags":{"type":"array","description":"Hashtags with platform or derived_text provenance.","items":{"type":"object","description":"Entity observed at source or derived from text.","properties":{"name":{"type":"string","description":"Hashtag or account name."},"id":{"type":"string","description":"Platform ID when supplied."},"source":{"type":"string","description":"platform or derived_text."}}}},"mentions":{"type":"array","description":"Mentions with platform or derived_text provenance; text is not proof of an account relationship.","items":{"type":"object","description":"Entity observed at source or derived from text.","properties":{"name":{"type":"string","description":"Hashtag or account name."},"id":{"type":"string","description":"Platform ID when supplied."},"source":{"type":"string","description":"platform or derived_text."}}}},"category_id":{"type":"string","description":"YouTube category ID."},"language":{"type":"string","description":"Default metadata language."},"audio_language":{"type":"string","description":"Default audio language."},"localized":{"type":"object","description":"Selected localized text.","properties":{"title":{"type":"string","description":"Title."},"description":{"type":"string","description":"Description."}}},"localizations":{"type":"object","description":"Returned language-to-title/description map."},"duration_iso8601":{"type":"string","description":"Source ISO 8601 duration."},"dimension":{"type":"string","description":"2d or 3d."},"definition":{"type":"string","description":"hd or sd."},"licensed_content":{"type":"boolean","description":"Source licensed-content flag."},"region_restriction":{"type":"object","description":"An omitted list differs from an empty list. An empty allowed list blocks everywhere; an empty blocked list blocks nowhere.","properties":{"allowed":{"type":"array","description":"Countries where viewing is permitted.","items":{"type":"string","description":"Source value."}},"blocked":{"type":"array","description":"Countries where viewing is blocked.","items":{"type":"string","description":"Source value."}}}},"content_rating":{"type":"object","description":"Country/authority rating map retained without enumerating columns."},"projection":{"type":"string","description":"Projection format."},"privacy_status":{"type":"string","description":"Source public/unlisted status when returned without account authorization."},"license":{"type":"string","description":"Source license."},"public_stats_viewable":{"type":"boolean","description":"Source public-statistics setting."},"made_for_kids":{"type":"boolean","description":"Current source designation when publicly returned; not the owner-only self-declared setting."},"contains_synthetic_media":{"type":"boolean","description":"Source altered/synthetic-media disclosure when publicly returned; not an AI prediction."},"paid_partnership":{"type":"boolean","description":"Explicit source paid-product-placement flag when publicly returned."},"topic_ids":{"type":"array","description":"Legacy source topic IDs, when returned.","items":{"type":"string","description":"Source value."}},"topic_categories":{"type":"array","description":"Topic-category URLs.","items":{"type":"string","description":"Source value."}},"recording_date":{"type":"string","description":"Public recording date, when returned."},"embed_html":{"type":"string","description":"Source embed markup as a string. Never execute returned HTML without sanitizing."},"embed_height":{"type":"number","description":"Source embed height."},"embed_width":{"type":"number","description":"Source embed width."},"live_status":{"type":"string","description":"live, upcoming or none when supplied."},"title":{"type":"string","description":"Video title."},"description":{"type":"string","description":"Video description."},"channel_id":{"type":"string","description":"Owning channel ID."},"tags":{"type":"array","description":"Keyword tags; distinct from hashtags.","items":{"type":"string","description":"Keyword tag."}},"thumbnails":{"type":"array","description":"Returned thumbnail variants and dimensions.","items":{"type":"object","description":"One source media variant; URLs may expire.","properties":{"url":{"type":"string","description":"Source URL."},"width":{"type":"number","description":"Width in pixels."},"height":{"type":"number","description":"Height in pixels."},"asset_type":{"type":"string","description":"image, video, thumbnail or avatar."},"variant":{"type":"string","description":"Source variant when known."},"expires_at":{"type":"string","description":"Expiry timestamp when known."}}}},"author_avatar_url":{"type":"string","description":"Channel avatar from the watch page."},"channel_url":{"type":"string","description":"Channel URL built from the observed channel ID."},"upload_date":{"type":"string","description":"Source upload date, separate from publication date."},"available_countries":{"type":"array","description":"Allowed country list when the player exposes it; no inferred blocked countries.","items":{"type":"string","description":"Country code."}},"unlisted":{"type":"boolean","description":"Source unlisted flag."},"family_safe":{"type":"boolean","description":"Source family-safe flag; not the made-for-kids designation."},"counts_rounded":{"type":"object","description":"Precision of observed counters. Unknown precision is null.","properties":{"views":{"type":"boolean","description":"Views rounded."},"likes":{"type":"boolean","description":"Likes rounded."},"comments":{"type":"boolean","description":"Comments rounded."}}},"caption_tracks":{"type":"array","description":"Caption-track metadata without caption text.","items":{"type":"object","description":"One available caption language; URLs are not returned.","properties":{"language":{"type":"string","description":"Source language code."},"language_name":{"type":"string","description":"Source language label."},"generated":{"type":"boolean","description":"True for an automatic caption track."},"translatable":{"type":"boolean","description":"Source translation capability."}}}},"category":{"type":"string","description":"Source category name."},"is_live":{"type":"boolean","description":"Explicit current live state."},"is_live_content":{"type":"boolean","description":"Explicit live-content classification."},"captions_available":{"type":"boolean","description":"Caption-track availability when observable."},"embeddable":{"type":"boolean","description":"Player embed permission when returned."},"live":{"type":"object","description":"Returned broadcast start/end times and live-now state.","properties":{"actual_start_time":{"type":"string","description":"Source broadcast start time."},"actual_end_time":{"type":"string","description":"Source broadcast end time."},"is_live_now":{"type":"boolean","description":"Explicit live-now state."},"scheduled_start_time":{"type":"string","description":"Scheduled start time."},"scheduled_end_time":{"type":"string","description":"Scheduled end time."},"concurrent_viewers":{"type":"number","description":"Current live viewers, when public."},"active_live_chat_id":{"type":"string","description":"Active public live-chat ID when supplied."}}}}}},"/v1/youtube/transcript":{"get":{"operationId":"youtube_transcript","summary":"YouTube transcript","description":"Get available captions as plain text and timed sections, with language details. Core resource for supplied public handles or content IDs.","tags":["youtube"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"id","in":"query","required":true,"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{11}$","example":"dQw4w9WgXcQ"},"description":"Required youtube id."},{"name":"cache_max_age","in":"query","required":false,"schema":{"type":"string","enum":["1d","3d","7d","14d","30d"]},"description":"Maximum acceptable cache age. Valid cache hits cost zero credits."},{"name":"fields","in":"query","required":false,"schema":{"type":"string","example":"text,segments"},"description":"Comma-separated fields or dot paths, including inside arrays such as items.id. Response identity and pagination are retained."},{"name":"trim","in":"query","required":false,"schema":{"type":"boolean","default":false},"description":"Remove null and empty values. Meaningful empty YouTube region-restriction lists are retained."}],"responses":{"200":{"description":"Normalized resource","headers":{"x-request-id":{"schema":{"type":"string"}},"x-data-mode":{"schema":{"type":"string","enum":["live","sandbox"]}},"x-cache":{"schema":{"type":"string","enum":["HIT","MISS"]}},"x-credits-charged":{"schema":{"type":"integer"}},"x-credits-remaining":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"data":{"type":"object","properties":{"video_id":{"type":["string","null"],"description":"YouTube video ID."},"video_title":{"type":["string","null"],"description":"Public video title."},"author":{"type":["string","null"],"description":"Channel display name."},"channel_id":{"type":["string","null"],"description":"Owning channel ID."},"language":{"type":["string","null"],"description":"Selected caption language; English is preferred when available."},"language_name":{"type":["string","null"],"description":"Selected language display name."},"generated":{"type":["boolean","null"],"description":"True for automatic speech-recognition captions."},"available_languages":{"type":["array","null"],"description":"All caption tracks exposed by the player, not translated text.","items":{"type":["object","null"],"description":"One available caption language; URLs are not returned.","properties":{"language":{"type":["string","null"],"description":"Source language code."},"language_name":{"type":["string","null"],"description":"Source language label."},"generated":{"type":["boolean","null"],"description":"True for an automatic caption track."},"translatable":{"type":["boolean","null"],"description":"Source translation capability."}}}},"text":{"type":["string","null"],"description":"Joined text of the selected caption track."},"segment_count":{"type":["number","null"],"description":"Number of returned text segments."},"duration_seconds":{"type":["number","null"],"description":"Last caption end time in seconds, not the video's duration; null if timing is incomplete."},"segments":{"type":["array","null"],"description":"Caption segments in source order.","items":{"type":["object","null"],"description":"One caption segment.","properties":{"start":{"type":["number","null"],"description":"Start in seconds."},"duration":{"type":["number","null"],"description":"Duration in seconds when supplied."},"text":{"type":["string","null"],"description":"Caption text."}}}}}}}}]}}}},"400":{"$ref":"#/components/responses/InvalidInput"},"401":{"$ref":"#/components/responses/InvalidApiKey"},"402":{"$ref":"#/components/responses/InsufficientCredits"},"403":{"$ref":"#/components/responses/SourceRestricted"},"404":{"$ref":"#/components/responses/ResourceNotFound"},"408":{"$ref":"#/components/responses/SourceTimeout"},"422":{"$ref":"#/components/responses/SourceResponseChanged"},"429":{"$ref":"#/components/responses/TemporaryCapacity"},"501":{"$ref":"#/components/responses/SourceNotImplemented"},"503":{"$ref":"#/components/responses/SourceUnavailable"}},"x-availability":"available","x-identifier-one-of":["id"],"x-credits":4,"x-source-access":"public_page","x-preview":false,"x-codeSamples":[{"lang":"curl","source":"curl 'https://api.socialdatakit.com/v1/youtube/transcript?id=dQw4w9WgXcQ' \\\n  -H 'x-api-key: YOUR_API_KEY'"},{"lang":"javascript","source":"const response = await fetch(\"https://api.socialdatakit.com/v1/youtube/transcript?id=dQw4w9WgXcQ\", {\n  headers: { \"x-api-key\": process.env.SOCIALDATAKIT_API_KEY }\n});\nif (!response.ok) throw new Error(await response.text());\nconst result = await response.json();"},{"lang":"python","source":"import os\nimport requests\n\nresponse = requests.get(\n    \"https://api.socialdatakit.com/v1/youtube/transcript?id=dQw4w9WgXcQ\",\n    headers={\"x-api-key\": os.environ[\"SOCIALDATAKIT_API_KEY\"]},\n    timeout=30,\n)\nresponse.raise_for_status()\nresult = response.json()"}],"x-response-fields":{"video_id":{"type":"string","description":"YouTube video ID."},"video_title":{"type":"string","description":"Public video title."},"author":{"type":"string","description":"Channel display name."},"channel_id":{"type":"string","description":"Owning channel ID."},"language":{"type":"string","description":"Selected caption language; English is preferred when available."},"language_name":{"type":"string","description":"Selected language display name."},"generated":{"type":"boolean","description":"True for automatic speech-recognition captions."},"available_languages":{"type":"array","description":"All caption tracks exposed by the player, not translated text.","items":{"type":"object","description":"One available caption language; URLs are not returned.","properties":{"language":{"type":"string","description":"Source language code."},"language_name":{"type":"string","description":"Source language label."},"generated":{"type":"boolean","description":"True for an automatic caption track."},"translatable":{"type":"boolean","description":"Source translation capability."}}}},"text":{"type":"string","description":"Joined text of the selected caption track."},"segment_count":{"type":"number","description":"Number of returned text segments."},"duration_seconds":{"type":"number","description":"Last caption end time in seconds, not the video's duration; null if timing is incomplete."},"segments":{"type":"array","description":"Caption segments in source order.","items":{"type":"object","description":"One caption segment.","properties":{"start":{"type":"number","description":"Start in seconds."},"duration":{"type":"number","description":"Duration in seconds when supplied."},"text":{"type":"string","description":"Caption text."}}}}}}},"/v1/youtube/channel":{"get":{"operationId":"youtube_channel","summary":"YouTube channel","description":"Get a public channel’s name, description, subscriber count, videos, thumbnails and links. Preview: evaluate live availability and source coverage before customer use.","tags":["youtube"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"handle","in":"query","required":false,"schema":{"type":"string","pattern":"^@?[\\p{L}\\p{N}_.-]{3,30}$","example":"RickAstleyYT"},"description":"Required youtube handle. Supply exactly one of: handle, url, channelId, channel_id."},{"name":"cache_max_age","in":"query","required":false,"schema":{"type":"string","enum":["1d","3d","7d","14d","30d"]},"description":"Maximum acceptable cache age. Valid cache hits cost zero credits."},{"name":"fields","in":"query","required":false,"schema":{"type":"string","example":"profile.username,profile.followers"},"description":"Comma-separated fields or dot paths, including inside arrays such as items.id. Response identity and pagination are retained."},{"name":"trim","in":"query","required":false,"schema":{"type":"boolean","default":false},"description":"Remove null and empty values. Meaningful empty YouTube region-restriction lists are retained."},{"name":"url","in":"query","required":false,"schema":{"type":"string","format":"uri"},"description":"Alternative to handle. Supply exactly one identifier. URLs must belong to youtube."},{"name":"channelId","in":"query","required":false,"schema":{"type":"string","pattern":"^@?[\\p{L}\\p{N}_.-]{3,30}$"},"description":"Alternative to handle. Supply exactly one identifier."},{"name":"channel_id","in":"query","required":false,"schema":{"type":"string","pattern":"^@?[\\p{L}\\p{N}_.-]{3,30}$"},"description":"Alternative to handle. Supply exactly one identifier."}],"responses":{"200":{"description":"Normalized resource","headers":{"x-request-id":{"schema":{"type":"string"}},"x-data-mode":{"schema":{"type":"string","enum":["live","sandbox"]}},"x-cache":{"schema":{"type":"string","enum":["HIT","MISS"]}},"x-credits-charged":{"schema":{"type":"integer"}},"x-credits-remaining":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"data":{"type":"object","properties":{"profile":{"type":"object","additionalProperties":true,"properties":{"id":{"type":["string","null"],"description":"Stable platform account ID when supplied; never an inferred username ID."},"username":{"type":["string","null"],"description":"Current account handle."},"display_name":{"type":["string","null"],"description":"Public display name."},"bio":{"type":["string","null"],"description":"Public biography."},"profile_url":{"type":["string","null"],"description":"Public profile URL."},"followers":{"type":["number","null"],"description":"Observed audience count; page summaries may be rounded."},"following":{"type":["number","null"],"description":"Observed following count."},"posts":{"type":["number","null"],"description":"Observed content count."},"verified":{"type":["boolean","null"],"description":"True or false only when explicitly returned; null means unknown."},"private":{"type":["boolean","null"],"description":"Observed privacy state; null means unknown."},"avatar_url":{"type":["string","null"],"description":"Source avatar URL, which can expire or restrict hotlinking."},"avatar_variants":{"type":["array","null"],"description":"Returned avatar image variants.","items":{"type":["object","null"],"description":"One source media variant; URLs may expire.","properties":{"url":{"type":["string","null"],"description":"Source URL."},"width":{"type":["number","null"],"description":"Width in pixels."},"height":{"type":["number","null"],"description":"Height in pixels."},"asset_type":{"type":["string","null"],"description":"image, video, thumbnail or avatar."},"variant":{"type":["string","null"],"description":"Source variant when known."},"expires_at":{"type":["string","null"],"description":"Expiry timestamp when known."}}}},"external_url":{"type":["string","null"],"description":"Public external website."},"created_at_platform":{"type":["string","null"],"description":"Channel creation timestamp."},"country_code":{"type":["string","null"],"description":"Country set on the channel, not inferred location."},"default_language":{"type":["string","null"],"description":"Source default language."},"localized":{"type":["object","null"],"description":"Selected localized text.","properties":{"title":{"type":["string","null"],"description":"Title."},"description":{"type":["string","null"],"description":"Description."}}},"localizations":{"type":["object","null"],"description":"Returned language-to-title/description map."},"total_views":{"type":["number","null"],"description":"Public channel view count."},"hidden_subscriber_count":{"type":["boolean","null"],"description":"Source subscriber-visibility flag."},"subscriber_count_is_rounded":{"type":["boolean","null"],"description":"Public subscriber counts are rounded to three significant figures."},"follower_count_is_rounded":{"type":["boolean","null"],"description":"Same precision marker for normalized followers."},"uploads_playlist_id":{"type":["string","null"],"description":"Uploads playlist ID."},"topic_ids":{"type":["array","null"],"description":"Legacy source topic IDs, when returned.","items":{"type":["string","null"],"description":"Source value."}},"topic_categories":{"type":["array","null"],"description":"Source topic-category URLs.","items":{"type":["string","null"],"description":"Source value."}},"keywords":{"type":["string","null"],"description":"Source channel keyword string."},"unsubscribed_trailer":{"type":["string","null"],"description":"Public channel trailer video ID."}}}}}}}]}}}},"400":{"$ref":"#/components/responses/InvalidInput"},"401":{"$ref":"#/components/responses/InvalidApiKey"},"402":{"$ref":"#/components/responses/InsufficientCredits"},"403":{"$ref":"#/components/responses/SourceRestricted"},"404":{"$ref":"#/components/responses/ResourceNotFound"},"408":{"$ref":"#/components/responses/SourceTimeout"},"422":{"$ref":"#/components/responses/SourceResponseChanged"},"429":{"$ref":"#/components/responses/TemporaryCapacity"},"501":{"$ref":"#/components/responses/SourceNotImplemented"},"503":{"$ref":"#/components/responses/SourceUnavailable"}},"x-availability":"preview","x-identifier-one-of":["handle","url","channelId","channel_id"],"x-credits":1,"x-source-access":"youtube_data_api","x-preview":true,"x-codeSamples":[{"lang":"curl","source":"curl 'https://api.socialdatakit.com/v1/youtube/channel?handle=RickAstleyYT' \\\n  -H 'x-api-key: YOUR_API_KEY'"},{"lang":"javascript","source":"const response = await fetch(\"https://api.socialdatakit.com/v1/youtube/channel?handle=RickAstleyYT\", {\n  headers: { \"x-api-key\": process.env.SOCIALDATAKIT_API_KEY }\n});\nif (!response.ok) throw new Error(await response.text());\nconst result = await response.json();"},{"lang":"python","source":"import os\nimport requests\n\nresponse = requests.get(\n    \"https://api.socialdatakit.com/v1/youtube/channel?handle=RickAstleyYT\",\n    headers={\"x-api-key\": os.environ[\"SOCIALDATAKIT_API_KEY\"]},\n    timeout=30,\n)\nresponse.raise_for_status()\nresult = response.json()"}],"x-response-fields":{"id":{"type":"string","description":"Stable platform account ID when supplied; never an inferred username ID."},"username":{"type":"string","description":"Current account handle."},"display_name":{"type":"string","description":"Public display name."},"bio":{"type":"string","description":"Public biography."},"profile_url":{"type":"string","description":"Public profile URL."},"followers":{"type":"number","description":"Observed audience count; page summaries may be rounded."},"following":{"type":"number","description":"Observed following count."},"posts":{"type":"number","description":"Observed content count."},"verified":{"type":"boolean","description":"True or false only when explicitly returned; null means unknown."},"private":{"type":"boolean","description":"Observed privacy state; null means unknown."},"avatar_url":{"type":"string","description":"Source avatar URL, which can expire or restrict hotlinking."},"avatar_variants":{"type":"array","description":"Returned avatar image variants.","items":{"type":"object","description":"One source media variant; URLs may expire.","properties":{"url":{"type":"string","description":"Source URL."},"width":{"type":"number","description":"Width in pixels."},"height":{"type":"number","description":"Height in pixels."},"asset_type":{"type":"string","description":"image, video, thumbnail or avatar."},"variant":{"type":"string","description":"Source variant when known."},"expires_at":{"type":"string","description":"Expiry timestamp when known."}}}},"external_url":{"type":"string","description":"Public external website."},"created_at_platform":{"type":"string","description":"Channel creation timestamp."},"country_code":{"type":"string","description":"Country set on the channel, not inferred location."},"default_language":{"type":"string","description":"Source default language."},"localized":{"type":"object","description":"Selected localized text.","properties":{"title":{"type":"string","description":"Title."},"description":{"type":"string","description":"Description."}}},"localizations":{"type":"object","description":"Returned language-to-title/description map."},"total_views":{"type":"number","description":"Public channel view count."},"hidden_subscriber_count":{"type":"boolean","description":"Source subscriber-visibility flag."},"subscriber_count_is_rounded":{"type":"boolean","description":"Public subscriber counts are rounded to three significant figures."},"follower_count_is_rounded":{"type":"boolean","description":"Same precision marker for normalized followers."},"uploads_playlist_id":{"type":"string","description":"Uploads playlist ID."},"topic_ids":{"type":"array","description":"Legacy source topic IDs, when returned.","items":{"type":"string","description":"Source value."}},"topic_categories":{"type":"array","description":"Source topic-category URLs.","items":{"type":"string","description":"Source value."}},"keywords":{"type":"string","description":"Source channel keyword string."},"unsubscribed_trailer":{"type":"string","description":"Public channel trailer video ID."}}}},"/v1/youtube/channel/videos":{"get":{"operationId":"youtube_channel_videos","summary":"YouTube channel videos","description":"Get videos uploaded by a public channel, with titles, thumbnails and available metrics. Preview: evaluate live availability and source coverage before customer use.","tags":["youtube"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"channel_id","in":"query","required":true,"schema":{"type":"string","pattern":"^UC[A-Za-z0-9_-]{22}$","example":"UCuAXFkgsw1L7xaCfnd5JJOw"},"description":"Required youtube channel_id."},{"name":"cache_max_age","in":"query","required":false,"schema":{"type":"string","enum":["1d","3d","7d","14d","30d"]},"description":"Maximum acceptable cache age. Valid cache hits cost zero credits."},{"name":"fields","in":"query","required":false,"schema":{"type":"string","example":"items"},"description":"Comma-separated fields or dot paths, including inside arrays such as items.id. Response identity and pagination are retained."},{"name":"trim","in":"query","required":false,"schema":{"type":"boolean","default":false},"description":"Remove null and empty values. Meaningful empty YouTube region-restriction lists are retained."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":20,"default":3},"description":"Number of items to return."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"},"description":"Opaque pagination value returned as data.pagination.next_cursor. Keep the identifier, filters and limit unchanged."}],"responses":{"200":{"description":"Normalized resource","headers":{"x-request-id":{"schema":{"type":"string"}},"x-data-mode":{"schema":{"type":"string","enum":["live","sandbox"]}},"x-cache":{"schema":{"type":"string","enum":["HIT","MISS"]}},"x-credits-charged":{"schema":{"type":"integer"}},"x-credits-remaining":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"data":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","additionalProperties":true,"properties":{"id":{"type":["string","null"],"description":"Resource identifier used by this endpoint."},"author":{"type":["string","null"],"description":"Public creator name or handle."},"published_at":{"type":["string","null"],"description":"Source publication date or timestamp; null when absent."},"views":{"type":["number","null"],"description":"Observed views, where exposed by this source."},"likes":{"type":["number","null"],"description":"Observed likes."},"comments":{"type":["number","null"],"description":"Observed comment count, not comment rows."},"media_url":{"type":["string","null"],"description":"Preview image URL; not a guaranteed downloadable video."},"permalink":{"type":["string","null"],"description":"Public content URL."},"duration_seconds":{"type":["number","null"],"description":"Duration in seconds when returned."},"hashtags":{"type":["array","null"],"description":"Hashtags with platform or derived_text provenance.","items":{"type":["object","null"],"description":"Entity observed at source or derived from text.","properties":{"name":{"type":["string","null"],"description":"Hashtag or account name."},"id":{"type":["string","null"],"description":"Platform ID when supplied."},"source":{"type":["string","null"],"description":"platform or derived_text."}}}},"mentions":{"type":["array","null"],"description":"Mentions with platform or derived_text provenance; text is not proof of an account relationship.","items":{"type":["object","null"],"description":"Entity observed at source or derived from text.","properties":{"name":{"type":["string","null"],"description":"Hashtag or account name."},"id":{"type":["string","null"],"description":"Platform ID when supplied."},"source":{"type":["string","null"],"description":"platform or derived_text."}}}},"category_id":{"type":["string","null"],"description":"YouTube category ID."},"language":{"type":["string","null"],"description":"Default metadata language."},"audio_language":{"type":["string","null"],"description":"Default audio language."},"localized":{"type":["object","null"],"description":"Selected localized text.","properties":{"title":{"type":["string","null"],"description":"Title."},"description":{"type":["string","null"],"description":"Description."}}},"localizations":{"type":["object","null"],"description":"Returned language-to-title/description map."},"duration_iso8601":{"type":["string","null"],"description":"Source ISO 8601 duration."},"dimension":{"type":["string","null"],"description":"2d or 3d."},"definition":{"type":["string","null"],"description":"hd or sd."},"licensed_content":{"type":["boolean","null"],"description":"Source licensed-content flag."},"region_restriction":{"type":["object","null"],"description":"An omitted list differs from an empty list. An empty allowed list blocks everywhere; an empty blocked list blocks nowhere.","properties":{"allowed":{"type":["array","null"],"description":"Countries where viewing is permitted.","items":{"type":["string","null"],"description":"Source value."}},"blocked":{"type":["array","null"],"description":"Countries where viewing is blocked.","items":{"type":["string","null"],"description":"Source value."}}}},"content_rating":{"type":["object","null"],"description":"Country/authority rating map retained without enumerating columns."},"projection":{"type":["string","null"],"description":"Projection format."},"privacy_status":{"type":["string","null"],"description":"Source public/unlisted status when returned without account authorization."},"license":{"type":["string","null"],"description":"Source license."},"public_stats_viewable":{"type":["boolean","null"],"description":"Source public-statistics setting."},"made_for_kids":{"type":["boolean","null"],"description":"Current source designation when publicly returned; not the owner-only self-declared setting."},"contains_synthetic_media":{"type":["boolean","null"],"description":"Source altered/synthetic-media disclosure when publicly returned; not an AI prediction."},"paid_partnership":{"type":["boolean","null"],"description":"Explicit source paid-product-placement flag when publicly returned."},"topic_ids":{"type":["array","null"],"description":"Legacy source topic IDs, when returned.","items":{"type":["string","null"],"description":"Source value."}},"topic_categories":{"type":["array","null"],"description":"Topic-category URLs.","items":{"type":["string","null"],"description":"Source value."}},"recording_date":{"type":["string","null"],"description":"Public recording date, when returned."},"embed_html":{"type":["string","null"],"description":"Source embed markup as a string. Never execute returned HTML without sanitizing."},"embed_height":{"type":["number","null"],"description":"Source embed height."},"embed_width":{"type":["number","null"],"description":"Source embed width."},"live_status":{"type":["string","null"],"description":"live, upcoming or none when supplied."},"title":{"type":["string","null"],"description":"Video title."},"description":{"type":["string","null"],"description":"Video description."},"channel_id":{"type":["string","null"],"description":"Owning channel ID."},"tags":{"type":["array","null"],"description":"Keyword tags; distinct from hashtags.","items":{"type":["string","null"],"description":"Keyword tag."}},"thumbnails":{"type":["array","null"],"description":"Returned thumbnail variants and dimensions.","items":{"type":["object","null"],"description":"One source media variant; URLs may expire.","properties":{"url":{"type":["string","null"],"description":"Source URL."},"width":{"type":["number","null"],"description":"Width in pixels."},"height":{"type":["number","null"],"description":"Height in pixels."},"asset_type":{"type":["string","null"],"description":"image, video, thumbnail or avatar."},"variant":{"type":["string","null"],"description":"Source variant when known."},"expires_at":{"type":["string","null"],"description":"Expiry timestamp when known."}}}},"author_avatar_url":{"type":["string","null"],"description":"Channel avatar from the watch page."},"channel_url":{"type":["string","null"],"description":"Channel URL built from the observed channel ID."},"upload_date":{"type":["string","null"],"description":"Source upload date, separate from publication date."},"available_countries":{"type":["array","null"],"description":"Allowed country list when the player exposes it; no inferred blocked countries.","items":{"type":["string","null"],"description":"Country code."}},"unlisted":{"type":["boolean","null"],"description":"Source unlisted flag."},"family_safe":{"type":["boolean","null"],"description":"Source family-safe flag; not the made-for-kids designation."},"counts_rounded":{"type":["object","null"],"description":"Precision of observed counters. Unknown precision is null.","properties":{"views":{"type":["boolean","null"],"description":"Views rounded."},"likes":{"type":["boolean","null"],"description":"Likes rounded."},"comments":{"type":["boolean","null"],"description":"Comments rounded."}}},"caption_tracks":{"type":["array","null"],"description":"Caption-track metadata without caption text.","items":{"type":["object","null"],"description":"One available caption language; URLs are not returned.","properties":{"language":{"type":["string","null"],"description":"Source language code."},"language_name":{"type":["string","null"],"description":"Source language label."},"generated":{"type":["boolean","null"],"description":"True for an automatic caption track."},"translatable":{"type":["boolean","null"],"description":"Source translation capability."}}}},"category":{"type":["string","null"],"description":"Source category name."},"is_live":{"type":["boolean","null"],"description":"Explicit current live state."},"is_live_content":{"type":["boolean","null"],"description":"Explicit live-content classification."},"captions_available":{"type":["boolean","null"],"description":"Caption-track availability when observable."},"embeddable":{"type":["boolean","null"],"description":"Player embed permission when returned."},"live":{"type":["object","null"],"description":"Returned broadcast start/end times and live-now state.","properties":{"actual_start_time":{"type":["string","null"],"description":"Source broadcast start time."},"actual_end_time":{"type":["string","null"],"description":"Source broadcast end time."},"is_live_now":{"type":["boolean","null"],"description":"Explicit live-now state."},"scheduled_start_time":{"type":["string","null"],"description":"Scheduled start time."},"scheduled_end_time":{"type":["string","null"],"description":"Scheduled end time."},"concurrent_viewers":{"type":["number","null"],"description":"Current live viewers, when public."},"active_live_chat_id":{"type":["string","null"],"description":"Active public live-chat ID when supplied."}}}}}}}}}}]}}}},"400":{"$ref":"#/components/responses/InvalidInput"},"401":{"$ref":"#/components/responses/InvalidApiKey"},"402":{"$ref":"#/components/responses/InsufficientCredits"},"403":{"$ref":"#/components/responses/SourceRestricted"},"404":{"$ref":"#/components/responses/ResourceNotFound"},"408":{"$ref":"#/components/responses/SourceTimeout"},"422":{"$ref":"#/components/responses/SourceResponseChanged"},"429":{"$ref":"#/components/responses/TemporaryCapacity"},"501":{"$ref":"#/components/responses/SourceNotImplemented"},"503":{"$ref":"#/components/responses/SourceUnavailable"}},"x-availability":"preview","x-identifier-one-of":["channel_id"],"x-credits":3,"x-source-access":"youtube_data_api","x-preview":true,"x-codeSamples":[{"lang":"curl","source":"curl 'https://api.socialdatakit.com/v1/youtube/channel/videos?channel_id=UCuAXFkgsw1L7xaCfnd5JJOw' \\\n  -H 'x-api-key: YOUR_API_KEY'"},{"lang":"javascript","source":"const response = await fetch(\"https://api.socialdatakit.com/v1/youtube/channel/videos?channel_id=UCuAXFkgsw1L7xaCfnd5JJOw\", {\n  headers: { \"x-api-key\": process.env.SOCIALDATAKIT_API_KEY }\n});\nif (!response.ok) throw new Error(await response.text());\nconst result = await response.json();"},{"lang":"python","source":"import os\nimport requests\n\nresponse = requests.get(\n    \"https://api.socialdatakit.com/v1/youtube/channel/videos?channel_id=UCuAXFkgsw1L7xaCfnd5JJOw\",\n    headers={\"x-api-key\": os.environ[\"SOCIALDATAKIT_API_KEY\"]},\n    timeout=30,\n)\nresponse.raise_for_status()\nresult = response.json()"}],"x-response-fields":{"id":{"type":"string","description":"Resource identifier used by this endpoint."},"author":{"type":"string","description":"Public creator name or handle."},"published_at":{"type":"string","description":"Source publication date or timestamp; null when absent."},"views":{"type":"number","description":"Observed views, where exposed by this source."},"likes":{"type":"number","description":"Observed likes."},"comments":{"type":"number","description":"Observed comment count, not comment rows."},"media_url":{"type":"string","description":"Preview image URL; not a guaranteed downloadable video."},"permalink":{"type":"string","description":"Public content URL."},"duration_seconds":{"type":"number","description":"Duration in seconds when returned."},"hashtags":{"type":"array","description":"Hashtags with platform or derived_text provenance.","items":{"type":"object","description":"Entity observed at source or derived from text.","properties":{"name":{"type":"string","description":"Hashtag or account name."},"id":{"type":"string","description":"Platform ID when supplied."},"source":{"type":"string","description":"platform or derived_text."}}}},"mentions":{"type":"array","description":"Mentions with platform or derived_text provenance; text is not proof of an account relationship.","items":{"type":"object","description":"Entity observed at source or derived from text.","properties":{"name":{"type":"string","description":"Hashtag or account name."},"id":{"type":"string","description":"Platform ID when supplied."},"source":{"type":"string","description":"platform or derived_text."}}}},"category_id":{"type":"string","description":"YouTube category ID."},"language":{"type":"string","description":"Default metadata language."},"audio_language":{"type":"string","description":"Default audio language."},"localized":{"type":"object","description":"Selected localized text.","properties":{"title":{"type":"string","description":"Title."},"description":{"type":"string","description":"Description."}}},"localizations":{"type":"object","description":"Returned language-to-title/description map."},"duration_iso8601":{"type":"string","description":"Source ISO 8601 duration."},"dimension":{"type":"string","description":"2d or 3d."},"definition":{"type":"string","description":"hd or sd."},"licensed_content":{"type":"boolean","description":"Source licensed-content flag."},"region_restriction":{"type":"object","description":"An omitted list differs from an empty list. An empty allowed list blocks everywhere; an empty blocked list blocks nowhere.","properties":{"allowed":{"type":"array","description":"Countries where viewing is permitted.","items":{"type":"string","description":"Source value."}},"blocked":{"type":"array","description":"Countries where viewing is blocked.","items":{"type":"string","description":"Source value."}}}},"content_rating":{"type":"object","description":"Country/authority rating map retained without enumerating columns."},"projection":{"type":"string","description":"Projection format."},"privacy_status":{"type":"string","description":"Source public/unlisted status when returned without account authorization."},"license":{"type":"string","description":"Source license."},"public_stats_viewable":{"type":"boolean","description":"Source public-statistics setting."},"made_for_kids":{"type":"boolean","description":"Current source designation when publicly returned; not the owner-only self-declared setting."},"contains_synthetic_media":{"type":"boolean","description":"Source altered/synthetic-media disclosure when publicly returned; not an AI prediction."},"paid_partnership":{"type":"boolean","description":"Explicit source paid-product-placement flag when publicly returned."},"topic_ids":{"type":"array","description":"Legacy source topic IDs, when returned.","items":{"type":"string","description":"Source value."}},"topic_categories":{"type":"array","description":"Topic-category URLs.","items":{"type":"string","description":"Source value."}},"recording_date":{"type":"string","description":"Public recording date, when returned."},"embed_html":{"type":"string","description":"Source embed markup as a string. Never execute returned HTML without sanitizing."},"embed_height":{"type":"number","description":"Source embed height."},"embed_width":{"type":"number","description":"Source embed width."},"live_status":{"type":"string","description":"live, upcoming or none when supplied."},"title":{"type":"string","description":"Video title."},"description":{"type":"string","description":"Video description."},"channel_id":{"type":"string","description":"Owning channel ID."},"tags":{"type":"array","description":"Keyword tags; distinct from hashtags.","items":{"type":"string","description":"Keyword tag."}},"thumbnails":{"type":"array","description":"Returned thumbnail variants and dimensions.","items":{"type":"object","description":"One source media variant; URLs may expire.","properties":{"url":{"type":"string","description":"Source URL."},"width":{"type":"number","description":"Width in pixels."},"height":{"type":"number","description":"Height in pixels."},"asset_type":{"type":"string","description":"image, video, thumbnail or avatar."},"variant":{"type":"string","description":"Source variant when known."},"expires_at":{"type":"string","description":"Expiry timestamp when known."}}}},"author_avatar_url":{"type":"string","description":"Channel avatar from the watch page."},"channel_url":{"type":"string","description":"Channel URL built from the observed channel ID."},"upload_date":{"type":"string","description":"Source upload date, separate from publication date."},"available_countries":{"type":"array","description":"Allowed country list when the player exposes it; no inferred blocked countries.","items":{"type":"string","description":"Country code."}},"unlisted":{"type":"boolean","description":"Source unlisted flag."},"family_safe":{"type":"boolean","description":"Source family-safe flag; not the made-for-kids designation."},"counts_rounded":{"type":"object","description":"Precision of observed counters. Unknown precision is null.","properties":{"views":{"type":"boolean","description":"Views rounded."},"likes":{"type":"boolean","description":"Likes rounded."},"comments":{"type":"boolean","description":"Comments rounded."}}},"caption_tracks":{"type":"array","description":"Caption-track metadata without caption text.","items":{"type":"object","description":"One available caption language; URLs are not returned.","properties":{"language":{"type":"string","description":"Source language code."},"language_name":{"type":"string","description":"Source language label."},"generated":{"type":"boolean","description":"True for an automatic caption track."},"translatable":{"type":"boolean","description":"Source translation capability."}}}},"category":{"type":"string","description":"Source category name."},"is_live":{"type":"boolean","description":"Explicit current live state."},"is_live_content":{"type":"boolean","description":"Explicit live-content classification."},"captions_available":{"type":"boolean","description":"Caption-track availability when observable."},"embeddable":{"type":"boolean","description":"Player embed permission when returned."},"live":{"type":"object","description":"Returned broadcast start/end times and live-now state.","properties":{"actual_start_time":{"type":"string","description":"Source broadcast start time."},"actual_end_time":{"type":"string","description":"Source broadcast end time."},"is_live_now":{"type":"boolean","description":"Explicit live-now state."},"scheduled_start_time":{"type":"string","description":"Scheduled start time."},"scheduled_end_time":{"type":"string","description":"Scheduled end time."},"concurrent_viewers":{"type":"number","description":"Current live viewers, when public."},"active_live_chat_id":{"type":"string","description":"Active public live-chat ID when supplied."}}}}}},"/v1/youtube/channel/playlists":{"get":{"operationId":"youtube_channel_playlists","summary":"YouTube channel playlists","description":"Public playlists owned by a channel, with descriptions, counts, thumbnails and languages. Preview: evaluate live availability and source coverage before customer use.","tags":["youtube"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"channel_id","in":"query","required":true,"schema":{"type":"string","pattern":"^UC[A-Za-z0-9_-]{22}$","example":"UCuAXFkgsw1L7xaCfnd5JJOw"},"description":"Required youtube channel_id."},{"name":"cache_max_age","in":"query","required":false,"schema":{"type":"string","enum":["1d","3d","7d","14d","30d"]},"description":"Maximum acceptable cache age. Valid cache hits cost zero credits."},{"name":"fields","in":"query","required":false,"schema":{"type":"string","example":"items"},"description":"Comma-separated fields or dot paths, including inside arrays such as items.id. Response identity and pagination are retained."},{"name":"trim","in":"query","required":false,"schema":{"type":"boolean","default":false},"description":"Remove null and empty values. Meaningful empty YouTube region-restriction lists are retained."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":20,"default":3},"description":"Number of items to return."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"},"description":"Opaque pagination value returned as data.pagination.next_cursor. Keep the identifier, filters and limit unchanged."}],"responses":{"200":{"description":"Normalized resource","headers":{"x-request-id":{"schema":{"type":"string"}},"x-data-mode":{"schema":{"type":"string","enum":["live","sandbox"]}},"x-cache":{"schema":{"type":"string","enum":["HIT","MISS"]}},"x-credits-charged":{"schema":{"type":"integer"}},"x-credits-remaining":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"data":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","additionalProperties":true,"properties":{"id":{"type":["string","null"],"description":"Playlist ID."},"title":{"type":["string","null"],"description":"Playlist title."},"description":{"type":["string","null"],"description":"Public description."},"author":{"type":["string","null"],"description":"Public owner name/handle."},"account_id":{"type":["string","null"],"description":"Playlist owner account ID."},"item_count":{"type":["number","null"],"description":"Source total item count."},"published_at":{"type":["string","null"],"description":"Creation timestamp."},"updated_at":{"type":["string","null"],"description":"Source update time."},"thumbnails":{"type":["array","null"],"description":"All returned thumbnail variants; dimensions are source values.","items":{"type":["object","null"],"description":"Thumbnail.","properties":{"url":{"type":["string","null"],"description":"Source URL."},"variant":{"type":["string","null"],"description":"Source variant."},"width":{"type":["number","null"],"description":"Width."},"height":{"type":["number","null"],"description":"Height."},"asset_type":{"type":["string","null"],"description":"thumbnail."},"expires_at":{"type":["string","null"],"description":"Expiry when known."}}}},"language":{"type":["string","null"],"description":"Default language."},"localized":{"type":["object","null"],"description":"Selected localized text.","properties":{"title":{"type":["string","null"],"description":"Title."},"description":{"type":["string","null"],"description":"Description."}}},"localizations":{"type":["object","null"],"description":"Returned localizations map."},"privacy_status":{"type":["string","null"],"description":"Explicit source privacy status."},"embed_html":{"type":["string","null"],"description":"Public embed markup as text."},"permalink":{"type":["string","null"],"description":"Public playlist URL."}}}}}}}}]}}}},"400":{"$ref":"#/components/responses/InvalidInput"},"401":{"$ref":"#/components/responses/InvalidApiKey"},"402":{"$ref":"#/components/responses/InsufficientCredits"},"403":{"$ref":"#/components/responses/SourceRestricted"},"404":{"$ref":"#/components/responses/ResourceNotFound"},"408":{"$ref":"#/components/responses/SourceTimeout"},"422":{"$ref":"#/components/responses/SourceResponseChanged"},"429":{"$ref":"#/components/responses/TemporaryCapacity"},"501":{"$ref":"#/components/responses/SourceNotImplemented"},"503":{"$ref":"#/components/responses/SourceUnavailable"}},"x-availability":"preview","x-identifier-one-of":["channel_id"],"x-credits":1,"x-source-access":"youtube_data_api","x-preview":true,"x-codeSamples":[{"lang":"curl","source":"curl 'https://api.socialdatakit.com/v1/youtube/channel/playlists?channel_id=UCuAXFkgsw1L7xaCfnd5JJOw' \\\n  -H 'x-api-key: YOUR_API_KEY'"},{"lang":"javascript","source":"const response = await fetch(\"https://api.socialdatakit.com/v1/youtube/channel/playlists?channel_id=UCuAXFkgsw1L7xaCfnd5JJOw\", {\n  headers: { \"x-api-key\": process.env.SOCIALDATAKIT_API_KEY }\n});\nif (!response.ok) throw new Error(await response.text());\nconst result = await response.json();"},{"lang":"python","source":"import os\nimport requests\n\nresponse = requests.get(\n    \"https://api.socialdatakit.com/v1/youtube/channel/playlists?channel_id=UCuAXFkgsw1L7xaCfnd5JJOw\",\n    headers={\"x-api-key\": os.environ[\"SOCIALDATAKIT_API_KEY\"]},\n    timeout=30,\n)\nresponse.raise_for_status()\nresult = response.json()"}],"x-response-fields":{"id":{"type":"string","description":"Playlist ID."},"title":{"type":"string","description":"Playlist title."},"description":{"type":"string","description":"Public description."},"author":{"type":"string","description":"Public owner name/handle."},"account_id":{"type":"string","description":"Playlist owner account ID."},"item_count":{"type":"number","description":"Source total item count."},"published_at":{"type":"string","description":"Creation timestamp."},"updated_at":{"type":"string","description":"Source update time."},"thumbnails":{"type":"array","description":"All returned thumbnail variants; dimensions are source values.","items":{"type":"object","description":"Thumbnail.","properties":{"url":{"type":"string","description":"Source URL."},"variant":{"type":"string","description":"Source variant."},"width":{"type":"number","description":"Width."},"height":{"type":"number","description":"Height."},"asset_type":{"type":"string","description":"thumbnail."},"expires_at":{"type":"string","description":"Expiry when known."}}}},"language":{"type":"string","description":"Default language."},"localized":{"type":"object","description":"Selected localized text.","properties":{"title":{"type":"string","description":"Title."},"description":{"type":"string","description":"Description."}}},"localizations":{"type":"object","description":"Returned localizations map."},"privacy_status":{"type":"string","description":"Explicit source privacy status."},"embed_html":{"type":"string","description":"Public embed markup as text."},"permalink":{"type":"string","description":"Public playlist URL."}}}},"/v1/youtube/playlist":{"get":{"operationId":"youtube_playlist","summary":"YouTube playlist","description":"Get a public playlist’s title, description, owner, video count and thumbnails. Preview: evaluate live availability and source coverage before customer use.","tags":["youtube"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"playlist_id","in":"query","required":true,"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{10,100}$","example":"UUuAXFkgsw1L7xaCfnd5JJOw"},"description":"Required youtube playlist_id."},{"name":"cache_max_age","in":"query","required":false,"schema":{"type":"string","enum":["1d","3d","7d","14d","30d"]},"description":"Maximum acceptable cache age. Valid cache hits cost zero credits."},{"name":"fields","in":"query","required":false,"schema":{"type":"string","example":"item"},"description":"Comma-separated fields or dot paths, including inside arrays such as items.id. Response identity and pagination are retained."},{"name":"trim","in":"query","required":false,"schema":{"type":"boolean","default":false},"description":"Remove null and empty values. Meaningful empty YouTube region-restriction lists are retained."}],"responses":{"200":{"description":"Normalized resource","headers":{"x-request-id":{"schema":{"type":"string"}},"x-data-mode":{"schema":{"type":"string","enum":["live","sandbox"]}},"x-cache":{"schema":{"type":"string","enum":["HIT","MISS"]}},"x-credits-charged":{"schema":{"type":"integer"}},"x-credits-remaining":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"data":{"type":"object","properties":{"item":{"type":"object","additionalProperties":true,"properties":{"id":{"type":["string","null"],"description":"Playlist ID."},"title":{"type":["string","null"],"description":"Playlist title."},"description":{"type":["string","null"],"description":"Public description."},"author":{"type":["string","null"],"description":"Public owner name/handle."},"account_id":{"type":["string","null"],"description":"Playlist owner account ID."},"item_count":{"type":["number","null"],"description":"Source total item count."},"published_at":{"type":["string","null"],"description":"Creation timestamp."},"updated_at":{"type":["string","null"],"description":"Source update time."},"thumbnails":{"type":["array","null"],"description":"All returned thumbnail variants; dimensions are source values.","items":{"type":["object","null"],"description":"Thumbnail.","properties":{"url":{"type":["string","null"],"description":"Source URL."},"variant":{"type":["string","null"],"description":"Source variant."},"width":{"type":["number","null"],"description":"Width."},"height":{"type":["number","null"],"description":"Height."},"asset_type":{"type":["string","null"],"description":"thumbnail."},"expires_at":{"type":["string","null"],"description":"Expiry when known."}}}},"language":{"type":["string","null"],"description":"Default language."},"localized":{"type":["object","null"],"description":"Selected localized text.","properties":{"title":{"type":["string","null"],"description":"Title."},"description":{"type":["string","null"],"description":"Description."}}},"localizations":{"type":["object","null"],"description":"Returned localizations map."},"privacy_status":{"type":["string","null"],"description":"Explicit source privacy status."},"embed_html":{"type":["string","null"],"description":"Public embed markup as text."},"permalink":{"type":["string","null"],"description":"Public playlist URL."}}}}}}}]}}}},"400":{"$ref":"#/components/responses/InvalidInput"},"401":{"$ref":"#/components/responses/InvalidApiKey"},"402":{"$ref":"#/components/responses/InsufficientCredits"},"403":{"$ref":"#/components/responses/SourceRestricted"},"404":{"$ref":"#/components/responses/ResourceNotFound"},"408":{"$ref":"#/components/responses/SourceTimeout"},"422":{"$ref":"#/components/responses/SourceResponseChanged"},"429":{"$ref":"#/components/responses/TemporaryCapacity"},"501":{"$ref":"#/components/responses/SourceNotImplemented"},"503":{"$ref":"#/components/responses/SourceUnavailable"}},"x-availability":"preview","x-identifier-one-of":["playlist_id"],"x-credits":1,"x-source-access":"youtube_data_api","x-preview":true,"x-codeSamples":[{"lang":"curl","source":"curl 'https://api.socialdatakit.com/v1/youtube/playlist?playlist_id=UUuAXFkgsw1L7xaCfnd5JJOw' \\\n  -H 'x-api-key: YOUR_API_KEY'"},{"lang":"javascript","source":"const response = await fetch(\"https://api.socialdatakit.com/v1/youtube/playlist?playlist_id=UUuAXFkgsw1L7xaCfnd5JJOw\", {\n  headers: { \"x-api-key\": process.env.SOCIALDATAKIT_API_KEY }\n});\nif (!response.ok) throw new Error(await response.text());\nconst result = await response.json();"},{"lang":"python","source":"import os\nimport requests\n\nresponse = requests.get(\n    \"https://api.socialdatakit.com/v1/youtube/playlist?playlist_id=UUuAXFkgsw1L7xaCfnd5JJOw\",\n    headers={\"x-api-key\": os.environ[\"SOCIALDATAKIT_API_KEY\"]},\n    timeout=30,\n)\nresponse.raise_for_status()\nresult = response.json()"}],"x-response-fields":{"id":{"type":"string","description":"Playlist ID."},"title":{"type":"string","description":"Playlist title."},"description":{"type":"string","description":"Public description."},"author":{"type":"string","description":"Public owner name/handle."},"account_id":{"type":"string","description":"Playlist owner account ID."},"item_count":{"type":"number","description":"Source total item count."},"published_at":{"type":"string","description":"Creation timestamp."},"updated_at":{"type":"string","description":"Source update time."},"thumbnails":{"type":"array","description":"All returned thumbnail variants; dimensions are source values.","items":{"type":"object","description":"Thumbnail.","properties":{"url":{"type":"string","description":"Source URL."},"variant":{"type":"string","description":"Source variant."},"width":{"type":"number","description":"Width."},"height":{"type":"number","description":"Height."},"asset_type":{"type":"string","description":"thumbnail."},"expires_at":{"type":"string","description":"Expiry when known."}}}},"language":{"type":"string","description":"Default language."},"localized":{"type":"object","description":"Selected localized text.","properties":{"title":{"type":"string","description":"Title."},"description":{"type":"string","description":"Description."}}},"localizations":{"type":"object","description":"Returned localizations map."},"privacy_status":{"type":"string","description":"Explicit source privacy status."},"embed_html":{"type":"string","description":"Public embed markup as text."},"permalink":{"type":"string","description":"Public playlist URL."}}}},"/v1/youtube/playlist/items":{"get":{"operationId":"youtube_playlist_items","summary":"YouTube playlist items","description":"Get a public playlist’s videos in order, with IDs, titles and thumbnails. Preview: evaluate live availability and source coverage before customer use.","tags":["youtube"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"playlist_id","in":"query","required":true,"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{10,100}$","example":"UUuAXFkgsw1L7xaCfnd5JJOw"},"description":"Required youtube playlist_id."},{"name":"cache_max_age","in":"query","required":false,"schema":{"type":"string","enum":["1d","3d","7d","14d","30d"]},"description":"Maximum acceptable cache age. Valid cache hits cost zero credits."},{"name":"fields","in":"query","required":false,"schema":{"type":"string","example":"items"},"description":"Comma-separated fields or dot paths, including inside arrays such as items.id. Response identity and pagination are retained."},{"name":"trim","in":"query","required":false,"schema":{"type":"boolean","default":false},"description":"Remove null and empty values. Meaningful empty YouTube region-restriction lists are retained."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":20,"default":3},"description":"Number of items to return."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"},"description":"Opaque pagination value returned as data.pagination.next_cursor. Keep the identifier, filters and limit unchanged."}],"responses":{"200":{"description":"Normalized resource","headers":{"x-request-id":{"schema":{"type":"string"}},"x-data-mode":{"schema":{"type":"string","enum":["live","sandbox"]}},"x-cache":{"schema":{"type":"string","enum":["HIT","MISS"]}},"x-credits-charged":{"schema":{"type":"integer"}},"x-credits-remaining":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"data":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","additionalProperties":true,"properties":{"id":{"type":["string","null"],"description":"Playlist entry ID. Duplicate occurrences of a video have distinct entry IDs."},"playlist_id":{"type":["string","null"],"description":"Parent playlist ID."},"content_id":{"type":["string","null"],"description":"Video ID."},"resource_kind":{"type":["string","null"],"description":"Source resource kind, normally youtube#video."},"position":{"type":["number","null"],"description":"Zero-based source playlist position."},"title":{"type":["string","null"],"description":"Entry title."},"description":{"type":["string","null"],"description":"Entry description."},"author":{"type":["string","null"],"description":"Video owner's channel name."},"author_id":{"type":["string","null"],"description":"Video owner's channel ID."},"playlist_owner_id":{"type":["string","null"],"description":"Playlist owner ID."},"playlist_owner_name":{"type":["string","null"],"description":"Playlist owner name."},"added_at":{"type":["string","null"],"description":"When the item was added to this playlist."},"published_at":{"type":["string","null"],"description":"Video publication timestamp."},"thumbnails":{"type":["array","null"],"description":"All returned thumbnail variants; dimensions are source values.","items":{"type":["object","null"],"description":"Thumbnail.","properties":{"url":{"type":["string","null"],"description":"Source URL."},"variant":{"type":["string","null"],"description":"Source variant."},"width":{"type":["number","null"],"description":"Width."},"height":{"type":["number","null"],"description":"Height."},"asset_type":{"type":["string","null"],"description":"thumbnail."},"expires_at":{"type":["string","null"],"description":"Expiry when known."}}}},"privacy_status":{"type":["string","null"],"description":"Source privacy status."},"permalink":{"type":["string","null"],"description":"Video URL."}}}}}}}}]}}}},"400":{"$ref":"#/components/responses/InvalidInput"},"401":{"$ref":"#/components/responses/InvalidApiKey"},"402":{"$ref":"#/components/responses/InsufficientCredits"},"403":{"$ref":"#/components/responses/SourceRestricted"},"404":{"$ref":"#/components/responses/ResourceNotFound"},"408":{"$ref":"#/components/responses/SourceTimeout"},"422":{"$ref":"#/components/responses/SourceResponseChanged"},"429":{"$ref":"#/components/responses/TemporaryCapacity"},"501":{"$ref":"#/components/responses/SourceNotImplemented"},"503":{"$ref":"#/components/responses/SourceUnavailable"}},"x-availability":"preview","x-identifier-one-of":["playlist_id"],"x-credits":1,"x-source-access":"youtube_data_api","x-preview":true,"x-codeSamples":[{"lang":"curl","source":"curl 'https://api.socialdatakit.com/v1/youtube/playlist/items?playlist_id=UUuAXFkgsw1L7xaCfnd5JJOw' \\\n  -H 'x-api-key: YOUR_API_KEY'"},{"lang":"javascript","source":"const response = await fetch(\"https://api.socialdatakit.com/v1/youtube/playlist/items?playlist_id=UUuAXFkgsw1L7xaCfnd5JJOw\", {\n  headers: { \"x-api-key\": process.env.SOCIALDATAKIT_API_KEY }\n});\nif (!response.ok) throw new Error(await response.text());\nconst result = await response.json();"},{"lang":"python","source":"import os\nimport requests\n\nresponse = requests.get(\n    \"https://api.socialdatakit.com/v1/youtube/playlist/items?playlist_id=UUuAXFkgsw1L7xaCfnd5JJOw\",\n    headers={\"x-api-key\": os.environ[\"SOCIALDATAKIT_API_KEY\"]},\n    timeout=30,\n)\nresponse.raise_for_status()\nresult = response.json()"}],"x-response-fields":{"id":{"type":"string","description":"Playlist entry ID. Duplicate occurrences of a video have distinct entry IDs."},"playlist_id":{"type":"string","description":"Parent playlist ID."},"content_id":{"type":"string","description":"Video ID."},"resource_kind":{"type":"string","description":"Source resource kind, normally youtube#video."},"position":{"type":"number","description":"Zero-based source playlist position."},"title":{"type":"string","description":"Entry title."},"description":{"type":"string","description":"Entry description."},"author":{"type":"string","description":"Video owner's channel name."},"author_id":{"type":"string","description":"Video owner's channel ID."},"playlist_owner_id":{"type":"string","description":"Playlist owner ID."},"playlist_owner_name":{"type":"string","description":"Playlist owner name."},"added_at":{"type":"string","description":"When the item was added to this playlist."},"published_at":{"type":"string","description":"Video publication timestamp."},"thumbnails":{"type":"array","description":"All returned thumbnail variants; dimensions are source values.","items":{"type":"object","description":"Thumbnail.","properties":{"url":{"type":"string","description":"Source URL."},"variant":{"type":"string","description":"Source variant."},"width":{"type":"number","description":"Width."},"height":{"type":"number","description":"Height."},"asset_type":{"type":"string","description":"thumbnail."},"expires_at":{"type":"string","description":"Expiry when known."}}}},"privacy_status":{"type":"string","description":"Source privacy status."},"permalink":{"type":"string","description":"Video URL."}}}},"/v1/youtube/comments":{"get":{"operationId":"youtube_comments","summary":"YouTube video comments","description":"Public top-level comments with author identity, text, likes, timestamps and reply counts. Use comment replies for the thread. Preview: evaluate live availability and source coverage before customer use.","tags":["youtube"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"id","in":"query","required":true,"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{11}$","example":"dQw4w9WgXcQ"},"description":"Required youtube id."},{"name":"cache_max_age","in":"query","required":false,"schema":{"type":"string","enum":["1d","3d","7d","14d","30d"]},"description":"Maximum acceptable cache age. Valid cache hits cost zero credits."},{"name":"fields","in":"query","required":false,"schema":{"type":"string","example":"items"},"description":"Comma-separated fields or dot paths, including inside arrays such as items.id. Response identity and pagination are retained."},{"name":"trim","in":"query","required":false,"schema":{"type":"boolean","default":false},"description":"Remove null and empty values. Meaningful empty YouTube region-restriction lists are retained."},{"name":"order","in":"query","required":false,"description":"Comment order","schema":{"type":"string","enum":["time","relevance"],"example":"time"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":20,"default":3},"description":"Number of items to return."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"},"description":"Opaque pagination value returned as data.pagination.next_cursor. Keep the identifier, filters and limit unchanged."}],"responses":{"200":{"description":"Normalized resource","headers":{"x-request-id":{"schema":{"type":"string"}},"x-data-mode":{"schema":{"type":"string","enum":["live","sandbox"]}},"x-cache":{"schema":{"type":"string","enum":["HIT","MISS"]}},"x-credits-charged":{"schema":{"type":"integer"}},"x-credits-remaining":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"data":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","additionalProperties":true,"properties":{"id":{"type":["string","null"],"description":"Platform comment ID, retained as a string."},"content_id":{"type":["string","null"],"description":"Parent video/post ID when known."},"parent_comment_id":{"type":["string","null"],"description":"Top-level comment ID for a reply; null for a top-level comment or unknown parent."},"text":{"type":["string","null"],"description":"Public comment text. YouTube requests plainText formatting; no owner-only textOriginal."},"likes":{"type":["number","null"],"description":"Observed comment likes."},"reply_count":{"type":["number","null"],"description":"Observed total reply count; not the number of replies returned."},"author_id":{"type":["string","null"],"description":"Public author account ID."},"author_username":{"type":["string","null"],"description":"Public author handle."},"author_display_name":{"type":["string","null"],"description":"Public display name."},"author_avatar_url":{"type":["string","null"],"description":"Public avatar URL."},"author_profile_url":{"type":["string","null"],"description":"Public author profile URL."},"published_at":{"type":["string","null"],"description":"Comment publication timestamp."},"updated_at":{"type":["string","null"],"description":"Source edit timestamp when available."},"image_url":{"type":["string","null"],"description":"Optional image/GIF attachment URL; null when absent. Signed URL expires six hours after retrieval."},"image_url_retrieved_at":{"type":["string","null"],"description":"UTC timestamp when the attachment URL was retrieved; null without an attachment."},"image_url_expires_at":{"type":["string","null"],"description":"UTC expiry of the signed attachment URL. Refresh the comment after expiry; historical archives do not refresh links."}}}}}}}}]}}}},"400":{"$ref":"#/components/responses/InvalidInput"},"401":{"$ref":"#/components/responses/InvalidApiKey"},"402":{"$ref":"#/components/responses/InsufficientCredits"},"403":{"$ref":"#/components/responses/SourceRestricted"},"404":{"$ref":"#/components/responses/ResourceNotFound"},"408":{"$ref":"#/components/responses/SourceTimeout"},"422":{"$ref":"#/components/responses/SourceResponseChanged"},"429":{"$ref":"#/components/responses/TemporaryCapacity"},"501":{"$ref":"#/components/responses/SourceNotImplemented"},"503":{"$ref":"#/components/responses/SourceUnavailable"}},"x-availability":"preview","x-identifier-one-of":["id"],"x-credits":1,"x-source-access":"youtube_data_api","x-preview":true,"x-codeSamples":[{"lang":"curl","source":"curl 'https://api.socialdatakit.com/v1/youtube/comments?id=dQw4w9WgXcQ' \\\n  -H 'x-api-key: YOUR_API_KEY'"},{"lang":"javascript","source":"const response = await fetch(\"https://api.socialdatakit.com/v1/youtube/comments?id=dQw4w9WgXcQ\", {\n  headers: { \"x-api-key\": process.env.SOCIALDATAKIT_API_KEY }\n});\nif (!response.ok) throw new Error(await response.text());\nconst result = await response.json();"},{"lang":"python","source":"import os\nimport requests\n\nresponse = requests.get(\n    \"https://api.socialdatakit.com/v1/youtube/comments?id=dQw4w9WgXcQ\",\n    headers={\"x-api-key\": os.environ[\"SOCIALDATAKIT_API_KEY\"]},\n    timeout=30,\n)\nresponse.raise_for_status()\nresult = response.json()"}],"x-response-fields":{"id":{"type":"string","description":"Platform comment ID, retained as a string."},"content_id":{"type":"string","description":"Parent video/post ID when known."},"parent_comment_id":{"type":"string","description":"Top-level comment ID for a reply; null for a top-level comment or unknown parent."},"text":{"type":"string","description":"Public comment text. YouTube requests plainText formatting; no owner-only textOriginal."},"likes":{"type":"number","description":"Observed comment likes."},"reply_count":{"type":"number","description":"Observed total reply count; not the number of replies returned."},"author_id":{"type":"string","description":"Public author account ID."},"author_username":{"type":"string","description":"Public author handle."},"author_display_name":{"type":"string","description":"Public display name."},"author_avatar_url":{"type":"string","description":"Public avatar URL."},"author_profile_url":{"type":"string","description":"Public author profile URL."},"published_at":{"type":"string","description":"Comment publication timestamp."},"updated_at":{"type":"string","description":"Source edit timestamp when available."},"image_url":{"type":"string","description":"Optional image/GIF attachment URL; null when absent. Signed URL expires six hours after retrieval."},"image_url_retrieved_at":{"type":"string","description":"UTC timestamp when the attachment URL was retrieved; null without an attachment."},"image_url_expires_at":{"type":"string","description":"UTC expiry of the signed attachment URL. Refresh the comment after expiry; historical archives do not refresh links."}}}},"/v1/youtube/comment/replies":{"get":{"operationId":"youtube_comment_replies","summary":"YouTube comment replies","description":"Public replies to a top-level comment; author details, text, likes, parent ID and timestamps. Preview: evaluate live availability and source coverage before customer use.","tags":["youtube"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"comment_id","in":"query","required":true,"schema":{"type":"string","pattern":"^[A-Za-z0-9_.-]{5,180}$","example":"UgxExampleCommentId"},"description":"Required youtube comment_id."},{"name":"cache_max_age","in":"query","required":false,"schema":{"type":"string","enum":["1d","3d","7d","14d","30d"]},"description":"Maximum acceptable cache age. Valid cache hits cost zero credits."},{"name":"fields","in":"query","required":false,"schema":{"type":"string","example":"items"},"description":"Comma-separated fields or dot paths, including inside arrays such as items.id. Response identity and pagination are retained."},{"name":"trim","in":"query","required":false,"schema":{"type":"boolean","default":false},"description":"Remove null and empty values. Meaningful empty YouTube region-restriction lists are retained."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":20,"default":3},"description":"Number of items to return."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"},"description":"Opaque pagination value returned as data.pagination.next_cursor. Keep the identifier, filters and limit unchanged."}],"responses":{"200":{"description":"Normalized resource","headers":{"x-request-id":{"schema":{"type":"string"}},"x-data-mode":{"schema":{"type":"string","enum":["live","sandbox"]}},"x-cache":{"schema":{"type":"string","enum":["HIT","MISS"]}},"x-credits-charged":{"schema":{"type":"integer"}},"x-credits-remaining":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"data":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","additionalProperties":true,"properties":{"id":{"type":["string","null"],"description":"Platform comment ID, retained as a string."},"content_id":{"type":["string","null"],"description":"Parent video/post ID when known."},"parent_comment_id":{"type":["string","null"],"description":"Top-level comment ID for a reply; null for a top-level comment or unknown parent."},"text":{"type":["string","null"],"description":"Public comment text. YouTube requests plainText formatting; no owner-only textOriginal."},"likes":{"type":["number","null"],"description":"Observed comment likes."},"reply_count":{"type":["number","null"],"description":"Observed total reply count; not the number of replies returned."},"author_id":{"type":["string","null"],"description":"Public author account ID."},"author_username":{"type":["string","null"],"description":"Public author handle."},"author_display_name":{"type":["string","null"],"description":"Public display name."},"author_avatar_url":{"type":["string","null"],"description":"Public avatar URL."},"author_profile_url":{"type":["string","null"],"description":"Public author profile URL."},"published_at":{"type":["string","null"],"description":"Comment publication timestamp."},"updated_at":{"type":["string","null"],"description":"Source edit timestamp when available."},"image_url":{"type":["string","null"],"description":"Optional image/GIF attachment URL; null when absent. Signed URL expires six hours after retrieval."},"image_url_retrieved_at":{"type":["string","null"],"description":"UTC timestamp when the attachment URL was retrieved; null without an attachment."},"image_url_expires_at":{"type":["string","null"],"description":"UTC expiry of the signed attachment URL. Refresh the comment after expiry; historical archives do not refresh links."}}}}}}}}]}}}},"400":{"$ref":"#/components/responses/InvalidInput"},"401":{"$ref":"#/components/responses/InvalidApiKey"},"402":{"$ref":"#/components/responses/InsufficientCredits"},"403":{"$ref":"#/components/responses/SourceRestricted"},"404":{"$ref":"#/components/responses/ResourceNotFound"},"408":{"$ref":"#/components/responses/SourceTimeout"},"422":{"$ref":"#/components/responses/SourceResponseChanged"},"429":{"$ref":"#/components/responses/TemporaryCapacity"},"501":{"$ref":"#/components/responses/SourceNotImplemented"},"503":{"$ref":"#/components/responses/SourceUnavailable"}},"x-availability":"preview","x-identifier-one-of":["comment_id"],"x-credits":1,"x-source-access":"youtube_data_api","x-preview":true,"x-codeSamples":[{"lang":"curl","source":"curl 'https://api.socialdatakit.com/v1/youtube/comment/replies?comment_id=UgxExampleCommentId' \\\n  -H 'x-api-key: YOUR_API_KEY'"},{"lang":"javascript","source":"const response = await fetch(\"https://api.socialdatakit.com/v1/youtube/comment/replies?comment_id=UgxExampleCommentId\", {\n  headers: { \"x-api-key\": process.env.SOCIALDATAKIT_API_KEY }\n});\nif (!response.ok) throw new Error(await response.text());\nconst result = await response.json();"},{"lang":"python","source":"import os\nimport requests\n\nresponse = requests.get(\n    \"https://api.socialdatakit.com/v1/youtube/comment/replies?comment_id=UgxExampleCommentId\",\n    headers={\"x-api-key\": os.environ[\"SOCIALDATAKIT_API_KEY\"]},\n    timeout=30,\n)\nresponse.raise_for_status()\nresult = response.json()"}],"x-response-fields":{"id":{"type":"string","description":"Platform comment ID, retained as a string."},"content_id":{"type":"string","description":"Parent video/post ID when known."},"parent_comment_id":{"type":"string","description":"Top-level comment ID for a reply; null for a top-level comment or unknown parent."},"text":{"type":"string","description":"Public comment text. YouTube requests plainText formatting; no owner-only textOriginal."},"likes":{"type":"number","description":"Observed comment likes."},"reply_count":{"type":"number","description":"Observed total reply count; not the number of replies returned."},"author_id":{"type":"string","description":"Public author account ID."},"author_username":{"type":"string","description":"Public author handle."},"author_display_name":{"type":"string","description":"Public display name."},"author_avatar_url":{"type":"string","description":"Public avatar URL."},"author_profile_url":{"type":"string","description":"Public author profile URL."},"published_at":{"type":"string","description":"Comment publication timestamp."},"updated_at":{"type":"string","description":"Source edit timestamp when available."},"image_url":{"type":"string","description":"Optional image/GIF attachment URL; null when absent. Signed URL expires six hours after retrieval."},"image_url_retrieved_at":{"type":"string","description":"UTC timestamp when the attachment URL was retrieved; null without an attachment."},"image_url_expires_at":{"type":"string","description":"UTC expiry of the signed attachment URL. Refresh the comment after expiry; historical archives do not refresh links."}}}},"/v1/youtube/search":{"get":{"operationId":"youtube_search","summary":"YouTube search","description":"Public video, channel or playlist search results. Records query, returned order, region and language; not personalized website ranking. Preview: evaluate live availability and source coverage before customer use.","tags":["youtube"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"q","in":"query","required":false,"schema":{"type":"string","pattern":"^.{1,180}$","example":"creator tools"},"description":"Required youtube q. Supply exactly one of: q, query."},{"name":"cache_max_age","in":"query","required":false,"schema":{"type":"string","enum":["1d","3d","7d","14d","30d"]},"description":"Maximum acceptable cache age. Valid cache hits cost zero credits."},{"name":"fields","in":"query","required":false,"schema":{"type":"string","example":"items"},"description":"Comma-separated fields or dot paths, including inside arrays such as items.id. Response identity and pagination are retained."},{"name":"trim","in":"query","required":false,"schema":{"type":"boolean","default":false},"description":"Remove null and empty values. Meaningful empty YouTube region-restriction lists are retained."},{"name":"query","in":"query","required":false,"schema":{"type":"string","pattern":"^.{1,180}$"},"description":"Alternative to q. Supply exactly one identifier."},{"name":"type","in":"query","required":false,"description":"Result type","schema":{"type":"string","enum":["video","channel","playlist"],"example":"video"}},{"name":"order","in":"query","required":false,"description":"Search order","schema":{"type":"string","enum":["relevance","date","viewCount","rating","title"],"example":"relevance"}},{"name":"region_code","in":"query","required":false,"description":"Region","schema":{"type":"string","pattern":"^[A-Z]{2}$","example":"GB"}},{"name":"language","in":"query","required":false,"description":"Language","schema":{"type":"string","pattern":"^[a-z]{2,3}(-[A-Za-z0-9]{2,8})?$","example":"en"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":20,"default":3},"description":"Number of items to return."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"},"description":"Opaque pagination value returned as data.pagination.next_cursor. Keep the identifier, filters and limit unchanged."}],"responses":{"200":{"description":"Normalized resource","headers":{"x-request-id":{"schema":{"type":"string"}},"x-data-mode":{"schema":{"type":"string","enum":["live","sandbox"]}},"x-cache":{"schema":{"type":"string","enum":["HIT","MISS"]}},"x-credits-charged":{"schema":{"type":"integer"}},"x-credits-remaining":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"data":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","additionalProperties":true,"properties":{"id":{"type":["string","null"],"description":"Matched platform object ID."},"result_type":{"type":["string","null"],"description":"video, channel or playlist."},"title":{"type":["string","null"],"description":"Source title."},"description":{"type":["string","null"],"description":"Search snippet."},"channel_id":{"type":["string","null"],"description":"Owning channel ID."},"author":{"type":["string","null"],"description":"Channel name."},"published_at":{"type":["string","null"],"description":"Source publish time."},"thumbnails":{"type":["array","null"],"description":"All returned thumbnail variants; dimensions are source values.","items":{"type":["object","null"],"description":"Thumbnail.","properties":{"url":{"type":["string","null"],"description":"Source URL."},"variant":{"type":["string","null"],"description":"Source variant."},"width":{"type":["number","null"],"description":"Width."},"height":{"type":["number","null"],"description":"Height."},"asset_type":{"type":["string","null"],"description":"thumbnail."},"expires_at":{"type":["string","null"],"description":"Expiry when known."}}}},"live_status":{"type":["string","null"],"description":"Broadcast status."},"permalink":{"type":["string","null"],"description":"Public result URL."},"query":{"type":["string","null"],"description":"Query submitted."},"position":{"type":["number","null"],"description":"One-based position in this API result traversal, not personalized website ranking."},"region_code":{"type":["string","null"],"description":"Requested region, if specified."},"language":{"type":["string","null"],"description":"Requested relevance language, if specified."},"order":{"type":["string","null"],"description":"Requested sorting order."}}}}}}}}]}}}},"400":{"$ref":"#/components/responses/InvalidInput"},"401":{"$ref":"#/components/responses/InvalidApiKey"},"402":{"$ref":"#/components/responses/InsufficientCredits"},"403":{"$ref":"#/components/responses/SourceRestricted"},"404":{"$ref":"#/components/responses/ResourceNotFound"},"408":{"$ref":"#/components/responses/SourceTimeout"},"422":{"$ref":"#/components/responses/SourceResponseChanged"},"429":{"$ref":"#/components/responses/TemporaryCapacity"},"501":{"$ref":"#/components/responses/SourceNotImplemented"},"503":{"$ref":"#/components/responses/SourceUnavailable"}},"x-availability":"preview","x-identifier-one-of":["q","query"],"x-credits":10,"x-source-access":"youtube_data_api","x-preview":true,"x-codeSamples":[{"lang":"curl","source":"curl 'https://api.socialdatakit.com/v1/youtube/search?q=creator+tools' \\\n  -H 'x-api-key: YOUR_API_KEY'"},{"lang":"javascript","source":"const response = await fetch(\"https://api.socialdatakit.com/v1/youtube/search?q=creator+tools\", {\n  headers: { \"x-api-key\": process.env.SOCIALDATAKIT_API_KEY }\n});\nif (!response.ok) throw new Error(await response.text());\nconst result = await response.json();"},{"lang":"python","source":"import os\nimport requests\n\nresponse = requests.get(\n    \"https://api.socialdatakit.com/v1/youtube/search?q=creator+tools\",\n    headers={\"x-api-key\": os.environ[\"SOCIALDATAKIT_API_KEY\"]},\n    timeout=30,\n)\nresponse.raise_for_status()\nresult = response.json()"}],"x-response-fields":{"id":{"type":"string","description":"Matched platform object ID."},"result_type":{"type":"string","description":"video, channel or playlist."},"title":{"type":"string","description":"Source title."},"description":{"type":"string","description":"Search snippet."},"channel_id":{"type":"string","description":"Owning channel ID."},"author":{"type":"string","description":"Channel name."},"published_at":{"type":"string","description":"Source publish time."},"thumbnails":{"type":"array","description":"All returned thumbnail variants; dimensions are source values.","items":{"type":"object","description":"Thumbnail.","properties":{"url":{"type":"string","description":"Source URL."},"variant":{"type":"string","description":"Source variant."},"width":{"type":"number","description":"Width."},"height":{"type":"number","description":"Height."},"asset_type":{"type":"string","description":"thumbnail."},"expires_at":{"type":"string","description":"Expiry when known."}}}},"live_status":{"type":"string","description":"Broadcast status."},"permalink":{"type":"string","description":"Public result URL."},"query":{"type":"string","description":"Query submitted."},"position":{"type":"number","description":"One-based position in this API result traversal, not personalized website ranking."},"region_code":{"type":"string","description":"Requested region, if specified."},"language":{"type":"string","description":"Requested relevance language, if specified."},"order":{"type":"string","description":"Requested sorting order."}}}},"/v1/instagram/reels":{"get":{"operationId":"instagram_reels","summary":"Instagram Reels","description":"Get reels from a public profile, including captions, media and available metrics. Live collection for this Instagram resource is unavailable while direct source access is being resolved. Profiles, visible profile posts, individual posts and carousel items are supported separately. Fresh production requests return 503 SOURCE_UNAVAILABLE without credit charges. Valid requested cache hits are free.","tags":["instagram"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"handle","in":"query","required":true,"schema":{"type":"string","pattern":"^@?[A-Za-z0-9._]{1,30}$","example":"instagram"},"description":"Required instagram handle."},{"name":"cache_max_age","in":"query","required":false,"schema":{"type":"string","enum":["1d","3d","7d","14d","30d"]},"description":"Maximum acceptable cache age. Valid cache hits cost zero credits."},{"name":"fields","in":"query","required":false,"schema":{"type":"string","example":"items"},"description":"Comma-separated fields or dot paths, including inside arrays such as items.id. Response identity and pagination are retained."},{"name":"trim","in":"query","required":false,"schema":{"type":"boolean","default":false},"description":"Remove null and empty values. Meaningful empty YouTube region-restriction lists are retained."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":20,"default":3},"description":"Number of items to return."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"},"description":"Opaque pagination value returned as data.pagination.next_cursor. Keep the identifier, filters and limit unchanged."}],"responses":{"200":{"description":"Normalized resource","headers":{"x-request-id":{"schema":{"type":"string"}},"x-data-mode":{"schema":{"type":"string","enum":["live","sandbox"]}},"x-cache":{"schema":{"type":"string","enum":["HIT","MISS"]}},"x-credits-charged":{"schema":{"type":"integer"}},"x-credits-remaining":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"data":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","additionalProperties":true,"properties":{"id":{"type":["string","null"],"description":"Resource identifier used by this endpoint."},"author":{"type":["string","null"],"description":"Public creator name or handle."},"published_at":{"type":["string","null"],"description":"Source publication date or timestamp; null when absent."},"views":{"type":["number","null"],"description":"Observed views, where exposed by this source."},"likes":{"type":["number","null"],"description":"Observed likes."},"comments":{"type":["number","null"],"description":"Observed comment count, not comment rows."},"media_url":{"type":["string","null"],"description":"Preview image URL; not a guaranteed downloadable video."},"permalink":{"type":["string","null"],"description":"Public content URL."},"duration_seconds":{"type":["number","null"],"description":"Duration in seconds when returned."},"hashtags":{"type":["array","null"],"description":"Hashtags with platform or derived_text provenance.","items":{"type":["object","null"],"description":"Entity observed at source or derived from text.","properties":{"name":{"type":["string","null"],"description":"Hashtag or account name."},"id":{"type":["string","null"],"description":"Platform ID when supplied."},"source":{"type":["string","null"],"description":"platform or derived_text."}}}},"mentions":{"type":["array","null"],"description":"Mentions with platform or derived_text provenance; text is not proof of an account relationship.","items":{"type":["object","null"],"description":"Entity observed at source or derived from text.","properties":{"name":{"type":["string","null"],"description":"Hashtag or account name."},"id":{"type":["string","null"],"description":"Platform ID when supplied."},"source":{"type":["string","null"],"description":"platform or derived_text."}}}},"author_id":{"type":["string","null"],"description":"Stable creator ID when returned."},"author_display_name":{"type":["string","null"],"description":"Public display name."},"author_verified":{"type":["boolean","null"],"description":"Explicit creator verification state."},"author_avatar_url":{"type":["string","null"],"description":"Public creator avatar URL."},"platform_content_id":{"type":["string","null"],"description":"Platform media ID, separate from the shortcode."},"caption":{"type":["string","null"],"description":"Public caption."},"media_type":{"type":["string","null"],"description":"image, video, carousel, or null when unknown."},"media_product_type":{"type":["string","null"],"description":"Source product type, kept separate from media type."},"width":{"type":["number","null"],"description":"Media width in pixels."},"height":{"type":["number","null"],"description":"Media height in pixels."},"video_url":{"type":["string","null"],"description":"Source video URL where returned; may expire."},"comments_enabled":{"type":["boolean","null"],"description":"Observed comments setting."},"paid_partnership":{"type":["boolean","null"],"description":"Explicit source partnership flag; null when unavailable."},"accessibility_caption":{"type":["string","null"],"description":"Source alt text or accessibility description."},"location":{"type":["object","null"],"description":"Publicly attached location label.","properties":{"id":{"type":["string","null"],"description":"Location ID."},"name":{"type":["string","null"],"description":"Location name."},"slug":{"type":["string","null"],"description":"Location slug."}}},"tagged_users":{"type":["array","null"],"description":"Accounts explicitly tagged in the media.","items":{"type":["object","null"],"description":"Tagged account.","properties":{"id":{"type":["string","null"],"description":"Platform account ID."},"username":{"type":["string","null"],"description":"Handle."},"display_name":{"type":["string","null"],"description":"Display name."}}}},"media_assets":{"type":["array","null"],"description":"Returned image/video variants with dimensions.","items":{"type":["object","null"],"description":"One source media variant; URLs may expire.","properties":{"url":{"type":["string","null"],"description":"Source URL."},"width":{"type":["number","null"],"description":"Width in pixels."},"height":{"type":["number","null"],"description":"Height in pixels."},"asset_type":{"type":["string","null"],"description":"image, video, thumbnail or avatar."},"variant":{"type":["string","null"],"description":"Source variant when known."},"expires_at":{"type":["string","null"],"description":"Expiry timestamp when known."}}}},"children":{"type":["array","null"],"description":"Ordered carousel children when returned; null for non-carousels.","items":{"type":["object","null"],"description":"One carousel child.","properties":{"id":{"type":["string","null"],"description":"Media ID."},"position":{"type":["number","null"],"description":"Zero-based position."},"media_type":{"type":["string","null"],"description":"image, video or null."},"media_url":{"type":["string","null"],"description":"Preview image URL."},"video_url":{"type":["string","null"],"description":"Source video URL when available."},"width":{"type":["number","null"],"description":"Width in pixels."},"height":{"type":["number","null"],"description":"Height in pixels."}}}}}}}}}}}]}}}},"400":{"$ref":"#/components/responses/InvalidInput"},"401":{"$ref":"#/components/responses/InvalidApiKey"},"402":{"$ref":"#/components/responses/InsufficientCredits"},"403":{"$ref":"#/components/responses/SourceRestricted"},"404":{"$ref":"#/components/responses/ResourceNotFound"},"408":{"$ref":"#/components/responses/SourceTimeout"},"422":{"$ref":"#/components/responses/SourceResponseChanged"},"429":{"$ref":"#/components/responses/TemporaryCapacity"},"501":{"$ref":"#/components/responses/SourceNotImplemented"},"503":{"$ref":"#/components/responses/SourceUnavailable"}},"x-availability":"unavailable","x-identifier-one-of":["handle"],"x-credits":2,"x-source-access":"public_page","x-preview":true,"x-codeSamples":[{"lang":"curl","source":"curl 'https://api.socialdatakit.com/v1/instagram/reels?handle=instagram' \\\n  -H 'x-api-key: YOUR_API_KEY'"},{"lang":"javascript","source":"const response = await fetch(\"https://api.socialdatakit.com/v1/instagram/reels?handle=instagram\", {\n  headers: { \"x-api-key\": process.env.SOCIALDATAKIT_API_KEY }\n});\nif (!response.ok) throw new Error(await response.text());\nconst result = await response.json();"},{"lang":"python","source":"import os\nimport requests\n\nresponse = requests.get(\n    \"https://api.socialdatakit.com/v1/instagram/reels?handle=instagram\",\n    headers={\"x-api-key\": os.environ[\"SOCIALDATAKIT_API_KEY\"]},\n    timeout=30,\n)\nresponse.raise_for_status()\nresult = response.json()"}],"x-response-fields":{"id":{"type":"string","description":"Resource identifier used by this endpoint."},"author":{"type":"string","description":"Public creator name or handle."},"published_at":{"type":"string","description":"Source publication date or timestamp; null when absent."},"views":{"type":"number","description":"Observed views, where exposed by this source."},"likes":{"type":"number","description":"Observed likes."},"comments":{"type":"number","description":"Observed comment count, not comment rows."},"media_url":{"type":"string","description":"Preview image URL; not a guaranteed downloadable video."},"permalink":{"type":"string","description":"Public content URL."},"duration_seconds":{"type":"number","description":"Duration in seconds when returned."},"hashtags":{"type":"array","description":"Hashtags with platform or derived_text provenance.","items":{"type":"object","description":"Entity observed at source or derived from text.","properties":{"name":{"type":"string","description":"Hashtag or account name."},"id":{"type":"string","description":"Platform ID when supplied."},"source":{"type":"string","description":"platform or derived_text."}}}},"mentions":{"type":"array","description":"Mentions with platform or derived_text provenance; text is not proof of an account relationship.","items":{"type":"object","description":"Entity observed at source or derived from text.","properties":{"name":{"type":"string","description":"Hashtag or account name."},"id":{"type":"string","description":"Platform ID when supplied."},"source":{"type":"string","description":"platform or derived_text."}}}},"author_id":{"type":"string","description":"Stable creator ID when returned."},"author_display_name":{"type":"string","description":"Public display name."},"author_verified":{"type":"boolean","description":"Explicit creator verification state."},"author_avatar_url":{"type":"string","description":"Public creator avatar URL."},"platform_content_id":{"type":"string","description":"Platform media ID, separate from the shortcode."},"caption":{"type":"string","description":"Public caption."},"media_type":{"type":"string","description":"image, video, carousel, or null when unknown."},"media_product_type":{"type":"string","description":"Source product type, kept separate from media type."},"width":{"type":"number","description":"Media width in pixels."},"height":{"type":"number","description":"Media height in pixels."},"video_url":{"type":"string","description":"Source video URL where returned; may expire."},"comments_enabled":{"type":"boolean","description":"Observed comments setting."},"paid_partnership":{"type":"boolean","description":"Explicit source partnership flag; null when unavailable."},"accessibility_caption":{"type":"string","description":"Source alt text or accessibility description."},"location":{"type":"object","description":"Publicly attached location label.","properties":{"id":{"type":"string","description":"Location ID."},"name":{"type":"string","description":"Location name."},"slug":{"type":"string","description":"Location slug."}}},"tagged_users":{"type":"array","description":"Accounts explicitly tagged in the media.","items":{"type":"object","description":"Tagged account.","properties":{"id":{"type":"string","description":"Platform account ID."},"username":{"type":"string","description":"Handle."},"display_name":{"type":"string","description":"Display name."}}}},"media_assets":{"type":"array","description":"Returned image/video variants with dimensions.","items":{"type":"object","description":"One source media variant; URLs may expire.","properties":{"url":{"type":"string","description":"Source URL."},"width":{"type":"number","description":"Width in pixels."},"height":{"type":"number","description":"Height in pixels."},"asset_type":{"type":"string","description":"image, video, thumbnail or avatar."},"variant":{"type":"string","description":"Source variant when known."},"expires_at":{"type":"string","description":"Expiry timestamp when known."}}}},"children":{"type":"array","description":"Ordered carousel children when returned; null for non-carousels.","items":{"type":"object","description":"One carousel child.","properties":{"id":{"type":"string","description":"Media ID."},"position":{"type":"number","description":"Zero-based position."},"media_type":{"type":"string","description":"image, video or null."},"media_url":{"type":"string","description":"Preview image URL."},"video_url":{"type":"string","description":"Source video URL when available."},"width":{"type":"number","description":"Width in pixels."},"height":{"type":"number","description":"Height in pixels."}}}}}}},"/v1/instagram/post/children":{"get":{"operationId":"instagram_post_children","summary":"Instagram carousel items","description":"Get the images and videos in a public carousel post, in their original order. Preview: evaluate live availability and source coverage before customer use.","tags":["instagram"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"id","in":"query","required":true,"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{5,32}$","example":"CxDemo123"},"description":"Required instagram id."},{"name":"cache_max_age","in":"query","required":false,"schema":{"type":"string","enum":["1d","3d","7d","14d","30d"]},"description":"Maximum acceptable cache age. Valid cache hits cost zero credits."},{"name":"fields","in":"query","required":false,"schema":{"type":"string","example":"items"},"description":"Comma-separated fields or dot paths, including inside arrays such as items.id. Response identity and pagination are retained."},{"name":"trim","in":"query","required":false,"schema":{"type":"boolean","default":false},"description":"Remove null and empty values. Meaningful empty YouTube region-restriction lists are retained."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":20,"default":3},"description":"Number of items to return."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"},"description":"Opaque pagination value returned as data.pagination.next_cursor. Keep the identifier, filters and limit unchanged."}],"responses":{"200":{"description":"Normalized resource","headers":{"x-request-id":{"schema":{"type":"string"}},"x-data-mode":{"schema":{"type":"string","enum":["live","sandbox"]}},"x-cache":{"schema":{"type":"string","enum":["HIT","MISS"]}},"x-credits-charged":{"schema":{"type":"integer"}},"x-credits-remaining":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"data":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","additionalProperties":true,"properties":{"id":{"type":["string","null"],"description":"Carousel child media ID."},"position":{"type":["number","null"],"description":"Zero-based carousel position."},"media_type":{"type":["string","null"],"description":"image or video."},"media_url":{"type":["string","null"],"description":"Preview image URL."},"video_url":{"type":["string","null"],"description":"Source video URL when exposed."},"width":{"type":["number","null"],"description":"Width in pixels."},"height":{"type":["number","null"],"description":"Height in pixels."}}}}}}}}]}}}},"400":{"$ref":"#/components/responses/InvalidInput"},"401":{"$ref":"#/components/responses/InvalidApiKey"},"402":{"$ref":"#/components/responses/InsufficientCredits"},"403":{"$ref":"#/components/responses/SourceRestricted"},"404":{"$ref":"#/components/responses/ResourceNotFound"},"408":{"$ref":"#/components/responses/SourceTimeout"},"422":{"$ref":"#/components/responses/SourceResponseChanged"},"429":{"$ref":"#/components/responses/TemporaryCapacity"},"501":{"$ref":"#/components/responses/SourceNotImplemented"},"503":{"$ref":"#/components/responses/SourceUnavailable"}},"x-availability":"preview","x-identifier-one-of":["id"],"x-credits":1,"x-source-access":"public_page","x-preview":true,"x-codeSamples":[{"lang":"curl","source":"curl 'https://api.socialdatakit.com/v1/instagram/post/children?id=CxDemo123' \\\n  -H 'x-api-key: YOUR_API_KEY'"},{"lang":"javascript","source":"const response = await fetch(\"https://api.socialdatakit.com/v1/instagram/post/children?id=CxDemo123\", {\n  headers: { \"x-api-key\": process.env.SOCIALDATAKIT_API_KEY }\n});\nif (!response.ok) throw new Error(await response.text());\nconst result = await response.json();"},{"lang":"python","source":"import os\nimport requests\n\nresponse = requests.get(\n    \"https://api.socialdatakit.com/v1/instagram/post/children?id=CxDemo123\",\n    headers={\"x-api-key\": os.environ[\"SOCIALDATAKIT_API_KEY\"]},\n    timeout=30,\n)\nresponse.raise_for_status()\nresult = response.json()"}],"x-response-fields":{"id":{"type":"string","description":"Carousel child media ID."},"position":{"type":"number","description":"Zero-based carousel position."},"media_type":{"type":"string","description":"image or video."},"media_url":{"type":"string","description":"Preview image URL."},"video_url":{"type":"string","description":"Source video URL when exposed."},"width":{"type":"number","description":"Width in pixels."},"height":{"type":"number","description":"Height in pixels."}}}},"/v1/instagram/comments":{"get":{"operationId":"instagram_comments","summary":"Instagram post comments","description":"Get available public comments, author names, likes and reply counts. Live collection for this Instagram resource is unavailable while direct source access is being resolved. Profiles, visible profile posts, individual posts and carousel items are supported separately. Fresh production requests return 503 SOURCE_UNAVAILABLE without credit charges. Valid requested cache hits are free.","tags":["instagram"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"id","in":"query","required":true,"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{5,32}$","example":"CxDemo123"},"description":"Required instagram id."},{"name":"cache_max_age","in":"query","required":false,"schema":{"type":"string","enum":["1d","3d","7d","14d","30d"]},"description":"Maximum acceptable cache age. Valid cache hits cost zero credits."},{"name":"fields","in":"query","required":false,"schema":{"type":"string","example":"items"},"description":"Comma-separated fields or dot paths, including inside arrays such as items.id. Response identity and pagination are retained."},{"name":"trim","in":"query","required":false,"schema":{"type":"boolean","default":false},"description":"Remove null and empty values. Meaningful empty YouTube region-restriction lists are retained."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":20,"default":3},"description":"Number of items to return."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"},"description":"Opaque pagination value returned as data.pagination.next_cursor. Keep the identifier, filters and limit unchanged."}],"responses":{"200":{"description":"Normalized resource","headers":{"x-request-id":{"schema":{"type":"string"}},"x-data-mode":{"schema":{"type":"string","enum":["live","sandbox"]}},"x-cache":{"schema":{"type":"string","enum":["HIT","MISS"]}},"x-credits-charged":{"schema":{"type":"integer"}},"x-credits-remaining":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"data":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","additionalProperties":true,"properties":{"id":{"type":["string","null"],"description":"Platform comment ID, retained as a string."},"content_id":{"type":["string","null"],"description":"Parent video/post ID when known."},"parent_comment_id":{"type":["string","null"],"description":"Top-level comment ID for a reply; null for a top-level comment or unknown parent."},"text":{"type":["string","null"],"description":"Public comment text. YouTube requests plainText formatting; no owner-only textOriginal."},"likes":{"type":["number","null"],"description":"Observed comment likes."},"reply_count":{"type":["number","null"],"description":"Observed total reply count; not the number of replies returned."},"author_id":{"type":["string","null"],"description":"Public author account ID."},"author_username":{"type":["string","null"],"description":"Public author handle."},"author_display_name":{"type":["string","null"],"description":"Public display name."},"author_avatar_url":{"type":["string","null"],"description":"Public avatar URL."},"author_profile_url":{"type":["string","null"],"description":"Public author profile URL."},"published_at":{"type":["string","null"],"description":"Comment publication timestamp."},"updated_at":{"type":["string","null"],"description":"Source edit timestamp when available."}}}}}}}}]}}}},"400":{"$ref":"#/components/responses/InvalidInput"},"401":{"$ref":"#/components/responses/InvalidApiKey"},"402":{"$ref":"#/components/responses/InsufficientCredits"},"403":{"$ref":"#/components/responses/SourceRestricted"},"404":{"$ref":"#/components/responses/ResourceNotFound"},"408":{"$ref":"#/components/responses/SourceTimeout"},"422":{"$ref":"#/components/responses/SourceResponseChanged"},"429":{"$ref":"#/components/responses/TemporaryCapacity"},"501":{"$ref":"#/components/responses/SourceNotImplemented"},"503":{"$ref":"#/components/responses/SourceUnavailable"}},"x-availability":"unavailable","x-identifier-one-of":["id"],"x-credits":2,"x-source-access":"public_json","x-preview":true,"x-codeSamples":[{"lang":"curl","source":"curl 'https://api.socialdatakit.com/v1/instagram/comments?id=CxDemo123' \\\n  -H 'x-api-key: YOUR_API_KEY'"},{"lang":"javascript","source":"const response = await fetch(\"https://api.socialdatakit.com/v1/instagram/comments?id=CxDemo123\", {\n  headers: { \"x-api-key\": process.env.SOCIALDATAKIT_API_KEY }\n});\nif (!response.ok) throw new Error(await response.text());\nconst result = await response.json();"},{"lang":"python","source":"import os\nimport requests\n\nresponse = requests.get(\n    \"https://api.socialdatakit.com/v1/instagram/comments?id=CxDemo123\",\n    headers={\"x-api-key\": os.environ[\"SOCIALDATAKIT_API_KEY\"]},\n    timeout=30,\n)\nresponse.raise_for_status()\nresult = response.json()"}],"x-response-fields":{"id":{"type":"string","description":"Platform comment ID, retained as a string."},"content_id":{"type":"string","description":"Parent video/post ID when known."},"parent_comment_id":{"type":"string","description":"Top-level comment ID for a reply; null for a top-level comment or unknown parent."},"text":{"type":"string","description":"Public comment text. YouTube requests plainText formatting; no owner-only textOriginal."},"likes":{"type":"number","description":"Observed comment likes."},"reply_count":{"type":"number","description":"Observed total reply count; not the number of replies returned."},"author_id":{"type":"string","description":"Public author account ID."},"author_username":{"type":"string","description":"Public author handle."},"author_display_name":{"type":"string","description":"Public display name."},"author_avatar_url":{"type":"string","description":"Public avatar URL."},"author_profile_url":{"type":"string","description":"Public author profile URL."},"published_at":{"type":"string","description":"Comment publication timestamp."},"updated_at":{"type":"string","description":"Source edit timestamp when available."}}}},"/v1/instagram/hashtag":{"get":{"operationId":"instagram_hashtag","summary":"Instagram hashtag","description":"Get a public hashtag’s name and available post count. Live collection for this Instagram resource is unavailable while direct source access is being resolved. Profiles, visible profile posts, individual posts and carousel items are supported separately. Fresh production requests return 503 SOURCE_UNAVAILABLE without credit charges. Valid requested cache hits are free.","tags":["instagram"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"tag","in":"query","required":false,"schema":{"type":"string","pattern":"^[\\p{L}\\p{N}_]{1,100}$","example":"photography"},"description":"Required instagram tag. Supply exactly one of: tag, hashtag."},{"name":"cache_max_age","in":"query","required":false,"schema":{"type":"string","enum":["1d","3d","7d","14d","30d"]},"description":"Maximum acceptable cache age. Valid cache hits cost zero credits."},{"name":"fields","in":"query","required":false,"schema":{"type":"string","example":"item"},"description":"Comma-separated fields or dot paths, including inside arrays such as items.id. Response identity and pagination are retained."},{"name":"trim","in":"query","required":false,"schema":{"type":"boolean","default":false},"description":"Remove null and empty values. Meaningful empty YouTube region-restriction lists are retained."},{"name":"hashtag","in":"query","required":false,"schema":{"type":"string","pattern":"^[\\p{L}\\p{N}_]{1,100}$"},"description":"Alternative to tag. Supply exactly one identifier."}],"responses":{"200":{"description":"Normalized resource","headers":{"x-request-id":{"schema":{"type":"string"}},"x-data-mode":{"schema":{"type":"string","enum":["live","sandbox"]}},"x-cache":{"schema":{"type":"string","enum":["HIT","MISS"]}},"x-credits-charged":{"schema":{"type":"integer"}},"x-credits-remaining":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"data":{"type":"object","properties":{"item":{"type":"object","additionalProperties":true,"properties":{"id":{"type":["string","null"],"description":"Source hashtag ID."},"name":{"type":["string","null"],"description":"Hashtag name."},"description":{"type":["string","null"],"description":"Source description."},"content_count":{"type":["number","null"],"description":"Observed number of related posts/videos."},"views":{"type":["number","null"],"description":"Observed aggregate hashtag views, where exposed."},"cover_url":{"type":["string","null"],"description":"Public cover URL."},"permalink":{"type":["string","null"],"description":"Public hashtag page."}}}}}}}]}}}},"400":{"$ref":"#/components/responses/InvalidInput"},"401":{"$ref":"#/components/responses/InvalidApiKey"},"402":{"$ref":"#/components/responses/InsufficientCredits"},"403":{"$ref":"#/components/responses/SourceRestricted"},"404":{"$ref":"#/components/responses/ResourceNotFound"},"408":{"$ref":"#/components/responses/SourceTimeout"},"422":{"$ref":"#/components/responses/SourceResponseChanged"},"429":{"$ref":"#/components/responses/TemporaryCapacity"},"501":{"$ref":"#/components/responses/SourceNotImplemented"},"503":{"$ref":"#/components/responses/SourceUnavailable"}},"x-availability":"unavailable","x-identifier-one-of":["tag","hashtag"],"x-credits":1,"x-source-access":"public_page","x-preview":true,"x-codeSamples":[{"lang":"curl","source":"curl 'https://api.socialdatakit.com/v1/instagram/hashtag?tag=photography' \\\n  -H 'x-api-key: YOUR_API_KEY'"},{"lang":"javascript","source":"const response = await fetch(\"https://api.socialdatakit.com/v1/instagram/hashtag?tag=photography\", {\n  headers: { \"x-api-key\": process.env.SOCIALDATAKIT_API_KEY }\n});\nif (!response.ok) throw new Error(await response.text());\nconst result = await response.json();"},{"lang":"python","source":"import os\nimport requests\n\nresponse = requests.get(\n    \"https://api.socialdatakit.com/v1/instagram/hashtag?tag=photography\",\n    headers={\"x-api-key\": os.environ[\"SOCIALDATAKIT_API_KEY\"]},\n    timeout=30,\n)\nresponse.raise_for_status()\nresult = response.json()"}],"x-response-fields":{"id":{"type":"string","description":"Source hashtag ID."},"name":{"type":"string","description":"Hashtag name."},"description":{"type":"string","description":"Source description."},"content_count":{"type":"number","description":"Observed number of related posts/videos."},"views":{"type":"number","description":"Observed aggregate hashtag views, where exposed."},"cover_url":{"type":"string","description":"Public cover URL."},"permalink":{"type":"string","description":"Public hashtag page."}}}},"/v1/instagram/hashtag/posts":{"get":{"operationId":"instagram_hashtag_posts","summary":"Instagram hashtag posts","description":"Get posts shown on a public hashtag page. Results may cover only part of the hashtag’s posts. Live collection for this Instagram resource is unavailable while direct source access is being resolved. Profiles, visible profile posts, individual posts and carousel items are supported separately. Fresh production requests return 503 SOURCE_UNAVAILABLE without credit charges. Valid requested cache hits are free.","tags":["instagram"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"tag","in":"query","required":true,"schema":{"type":"string","pattern":"^[\\p{L}\\p{N}_]{1,100}$","example":"photography"},"description":"Required instagram tag."},{"name":"cache_max_age","in":"query","required":false,"schema":{"type":"string","enum":["1d","3d","7d","14d","30d"]},"description":"Maximum acceptable cache age. Valid cache hits cost zero credits."},{"name":"fields","in":"query","required":false,"schema":{"type":"string","example":"items"},"description":"Comma-separated fields or dot paths, including inside arrays such as items.id. Response identity and pagination are retained."},{"name":"trim","in":"query","required":false,"schema":{"type":"boolean","default":false},"description":"Remove null and empty values. Meaningful empty YouTube region-restriction lists are retained."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":20,"default":3},"description":"Number of items to return."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"},"description":"Opaque pagination value returned as data.pagination.next_cursor. Keep the identifier, filters and limit unchanged."}],"responses":{"200":{"description":"Normalized resource","headers":{"x-request-id":{"schema":{"type":"string"}},"x-data-mode":{"schema":{"type":"string","enum":["live","sandbox"]}},"x-cache":{"schema":{"type":"string","enum":["HIT","MISS"]}},"x-credits-charged":{"schema":{"type":"integer"}},"x-credits-remaining":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"data":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","additionalProperties":true,"properties":{"id":{"type":["string","null"],"description":"Resource identifier used by this endpoint."},"author":{"type":["string","null"],"description":"Public creator name or handle."},"published_at":{"type":["string","null"],"description":"Source publication date or timestamp; null when absent."},"views":{"type":["number","null"],"description":"Observed views, where exposed by this source."},"likes":{"type":["number","null"],"description":"Observed likes."},"comments":{"type":["number","null"],"description":"Observed comment count, not comment rows."},"media_url":{"type":["string","null"],"description":"Preview image URL; not a guaranteed downloadable video."},"permalink":{"type":["string","null"],"description":"Public content URL."},"duration_seconds":{"type":["number","null"],"description":"Duration in seconds when returned."},"hashtags":{"type":["array","null"],"description":"Hashtags with platform or derived_text provenance.","items":{"type":["object","null"],"description":"Entity observed at source or derived from text.","properties":{"name":{"type":["string","null"],"description":"Hashtag or account name."},"id":{"type":["string","null"],"description":"Platform ID when supplied."},"source":{"type":["string","null"],"description":"platform or derived_text."}}}},"mentions":{"type":["array","null"],"description":"Mentions with platform or derived_text provenance; text is not proof of an account relationship.","items":{"type":["object","null"],"description":"Entity observed at source or derived from text.","properties":{"name":{"type":["string","null"],"description":"Hashtag or account name."},"id":{"type":["string","null"],"description":"Platform ID when supplied."},"source":{"type":["string","null"],"description":"platform or derived_text."}}}},"author_id":{"type":["string","null"],"description":"Stable creator ID when returned."},"author_display_name":{"type":["string","null"],"description":"Public display name."},"author_verified":{"type":["boolean","null"],"description":"Explicit creator verification state."},"author_avatar_url":{"type":["string","null"],"description":"Public creator avatar URL."},"platform_content_id":{"type":["string","null"],"description":"Platform media ID, separate from the shortcode."},"caption":{"type":["string","null"],"description":"Public caption."},"media_type":{"type":["string","null"],"description":"image, video, carousel, or null when unknown."},"media_product_type":{"type":["string","null"],"description":"Source product type, kept separate from media type."},"width":{"type":["number","null"],"description":"Media width in pixels."},"height":{"type":["number","null"],"description":"Media height in pixels."},"video_url":{"type":["string","null"],"description":"Source video URL where returned; may expire."},"comments_enabled":{"type":["boolean","null"],"description":"Observed comments setting."},"paid_partnership":{"type":["boolean","null"],"description":"Explicit source partnership flag; null when unavailable."},"accessibility_caption":{"type":["string","null"],"description":"Source alt text or accessibility description."},"location":{"type":["object","null"],"description":"Publicly attached location label.","properties":{"id":{"type":["string","null"],"description":"Location ID."},"name":{"type":["string","null"],"description":"Location name."},"slug":{"type":["string","null"],"description":"Location slug."}}},"tagged_users":{"type":["array","null"],"description":"Accounts explicitly tagged in the media.","items":{"type":["object","null"],"description":"Tagged account.","properties":{"id":{"type":["string","null"],"description":"Platform account ID."},"username":{"type":["string","null"],"description":"Handle."},"display_name":{"type":["string","null"],"description":"Display name."}}}},"media_assets":{"type":["array","null"],"description":"Returned image/video variants with dimensions.","items":{"type":["object","null"],"description":"One source media variant; URLs may expire.","properties":{"url":{"type":["string","null"],"description":"Source URL."},"width":{"type":["number","null"],"description":"Width in pixels."},"height":{"type":["number","null"],"description":"Height in pixels."},"asset_type":{"type":["string","null"],"description":"image, video, thumbnail or avatar."},"variant":{"type":["string","null"],"description":"Source variant when known."},"expires_at":{"type":["string","null"],"description":"Expiry timestamp when known."}}}},"children":{"type":["array","null"],"description":"Ordered carousel children when returned; null for non-carousels.","items":{"type":["object","null"],"description":"One carousel child.","properties":{"id":{"type":["string","null"],"description":"Media ID."},"position":{"type":["number","null"],"description":"Zero-based position."},"media_type":{"type":["string","null"],"description":"image, video or null."},"media_url":{"type":["string","null"],"description":"Preview image URL."},"video_url":{"type":["string","null"],"description":"Source video URL when available."},"width":{"type":["number","null"],"description":"Width in pixels."},"height":{"type":["number","null"],"description":"Height in pixels."}}}}}}}}}}}]}}}},"400":{"$ref":"#/components/responses/InvalidInput"},"401":{"$ref":"#/components/responses/InvalidApiKey"},"402":{"$ref":"#/components/responses/InsufficientCredits"},"403":{"$ref":"#/components/responses/SourceRestricted"},"404":{"$ref":"#/components/responses/ResourceNotFound"},"408":{"$ref":"#/components/responses/SourceTimeout"},"422":{"$ref":"#/components/responses/SourceResponseChanged"},"429":{"$ref":"#/components/responses/TemporaryCapacity"},"501":{"$ref":"#/components/responses/SourceNotImplemented"},"503":{"$ref":"#/components/responses/SourceUnavailable"}},"x-availability":"unavailable","x-identifier-one-of":["tag"],"x-credits":2,"x-source-access":"public_page","x-preview":true,"x-codeSamples":[{"lang":"curl","source":"curl 'https://api.socialdatakit.com/v1/instagram/hashtag/posts?tag=photography' \\\n  -H 'x-api-key: YOUR_API_KEY'"},{"lang":"javascript","source":"const response = await fetch(\"https://api.socialdatakit.com/v1/instagram/hashtag/posts?tag=photography\", {\n  headers: { \"x-api-key\": process.env.SOCIALDATAKIT_API_KEY }\n});\nif (!response.ok) throw new Error(await response.text());\nconst result = await response.json();"},{"lang":"python","source":"import os\nimport requests\n\nresponse = requests.get(\n    \"https://api.socialdatakit.com/v1/instagram/hashtag/posts?tag=photography\",\n    headers={\"x-api-key\": os.environ[\"SOCIALDATAKIT_API_KEY\"]},\n    timeout=30,\n)\nresponse.raise_for_status()\nresult = response.json()"}],"x-response-fields":{"id":{"type":"string","description":"Resource identifier used by this endpoint."},"author":{"type":"string","description":"Public creator name or handle."},"published_at":{"type":"string","description":"Source publication date or timestamp; null when absent."},"views":{"type":"number","description":"Observed views, where exposed by this source."},"likes":{"type":"number","description":"Observed likes."},"comments":{"type":"number","description":"Observed comment count, not comment rows."},"media_url":{"type":"string","description":"Preview image URL; not a guaranteed downloadable video."},"permalink":{"type":"string","description":"Public content URL."},"duration_seconds":{"type":"number","description":"Duration in seconds when returned."},"hashtags":{"type":"array","description":"Hashtags with platform or derived_text provenance.","items":{"type":"object","description":"Entity observed at source or derived from text.","properties":{"name":{"type":"string","description":"Hashtag or account name."},"id":{"type":"string","description":"Platform ID when supplied."},"source":{"type":"string","description":"platform or derived_text."}}}},"mentions":{"type":"array","description":"Mentions with platform or derived_text provenance; text is not proof of an account relationship.","items":{"type":"object","description":"Entity observed at source or derived from text.","properties":{"name":{"type":"string","description":"Hashtag or account name."},"id":{"type":"string","description":"Platform ID when supplied."},"source":{"type":"string","description":"platform or derived_text."}}}},"author_id":{"type":"string","description":"Stable creator ID when returned."},"author_display_name":{"type":"string","description":"Public display name."},"author_verified":{"type":"boolean","description":"Explicit creator verification state."},"author_avatar_url":{"type":"string","description":"Public creator avatar URL."},"platform_content_id":{"type":"string","description":"Platform media ID, separate from the shortcode."},"caption":{"type":"string","description":"Public caption."},"media_type":{"type":"string","description":"image, video, carousel, or null when unknown."},"media_product_type":{"type":"string","description":"Source product type, kept separate from media type."},"width":{"type":"number","description":"Media width in pixels."},"height":{"type":"number","description":"Media height in pixels."},"video_url":{"type":"string","description":"Source video URL where returned; may expire."},"comments_enabled":{"type":"boolean","description":"Observed comments setting."},"paid_partnership":{"type":"boolean","description":"Explicit source partnership flag; null when unavailable."},"accessibility_caption":{"type":"string","description":"Source alt text or accessibility description."},"location":{"type":"object","description":"Publicly attached location label.","properties":{"id":{"type":"string","description":"Location ID."},"name":{"type":"string","description":"Location name."},"slug":{"type":"string","description":"Location slug."}}},"tagged_users":{"type":"array","description":"Accounts explicitly tagged in the media.","items":{"type":"object","description":"Tagged account.","properties":{"id":{"type":"string","description":"Platform account ID."},"username":{"type":"string","description":"Handle."},"display_name":{"type":"string","description":"Display name."}}}},"media_assets":{"type":"array","description":"Returned image/video variants with dimensions.","items":{"type":"object","description":"One source media variant; URLs may expire.","properties":{"url":{"type":"string","description":"Source URL."},"width":{"type":"number","description":"Width in pixels."},"height":{"type":"number","description":"Height in pixels."},"asset_type":{"type":"string","description":"image, video, thumbnail or avatar."},"variant":{"type":"string","description":"Source variant when known."},"expires_at":{"type":"string","description":"Expiry timestamp when known."}}}},"children":{"type":"array","description":"Ordered carousel children when returned; null for non-carousels.","items":{"type":"object","description":"One carousel child.","properties":{"id":{"type":"string","description":"Media ID."},"position":{"type":"number","description":"Zero-based position."},"media_type":{"type":"string","description":"image, video or null."},"media_url":{"type":"string","description":"Preview image URL."},"video_url":{"type":"string","description":"Source video URL when available."},"width":{"type":"number","description":"Width in pixels."},"height":{"type":"number","description":"Height in pixels."}}}}}}},"/v1/tiktok/pinned":{"get":{"operationId":"tiktok_pinned","summary":"TikTok pinned videos","description":"Get videos marked as pinned on a public profile. Live collection for this TikTok resource is unavailable until its direct source access is verified. Fresh production requests return 503 SOURCE_UNAVAILABLE without credit charges. Valid requested cache hits are free.","tags":["tiktok"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"handle","in":"query","required":true,"schema":{"type":"string","pattern":"^@?[A-Za-z0-9._]{2,24}$","example":"tiktok"},"description":"Required tiktok handle."},{"name":"cache_max_age","in":"query","required":false,"schema":{"type":"string","enum":["1d","3d","7d","14d","30d"]},"description":"Maximum acceptable cache age. Valid cache hits cost zero credits."},{"name":"fields","in":"query","required":false,"schema":{"type":"string","example":"items"},"description":"Comma-separated fields or dot paths, including inside arrays such as items.id. Response identity and pagination are retained."},{"name":"trim","in":"query","required":false,"schema":{"type":"boolean","default":false},"description":"Remove null and empty values. Meaningful empty YouTube region-restriction lists are retained."},{"name":"region","in":"query","required":false,"description":"Country code","schema":{"type":"string","pattern":"^[A-Z]{2}$","example":"GB"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":20,"default":3},"description":"Number of items to return."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"},"description":"Opaque pagination value returned as data.pagination.next_cursor. Keep the identifier, filters and limit unchanged."}],"responses":{"200":{"description":"Normalized resource","headers":{"x-request-id":{"schema":{"type":"string"}},"x-data-mode":{"schema":{"type":"string","enum":["live","sandbox"]}},"x-cache":{"schema":{"type":"string","enum":["HIT","MISS"]}},"x-credits-charged":{"schema":{"type":"integer"}},"x-credits-remaining":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"data":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","additionalProperties":true,"properties":{"id":{"type":["string","null"],"description":"Resource identifier used by this endpoint."},"author":{"type":["string","null"],"description":"Public creator name or handle."},"published_at":{"type":["string","null"],"description":"Source publication date or timestamp; null when absent."},"views":{"type":["number","null"],"description":"Observed views, where exposed by this source."},"likes":{"type":["number","null"],"description":"Observed likes."},"comments":{"type":["number","null"],"description":"Observed comment count, not comment rows."},"media_url":{"type":["string","null"],"description":"Preview image URL; not a guaranteed downloadable video."},"permalink":{"type":["string","null"],"description":"Public content URL."},"duration_seconds":{"type":["number","null"],"description":"Duration in seconds when returned."},"hashtags":{"type":["array","null"],"description":"Hashtags with platform or derived_text provenance.","items":{"type":["object","null"],"description":"Entity observed at source or derived from text.","properties":{"name":{"type":["string","null"],"description":"Hashtag or account name."},"id":{"type":["string","null"],"description":"Platform ID when supplied."},"source":{"type":["string","null"],"description":"platform or derived_text."}}}},"mentions":{"type":["array","null"],"description":"Mentions with platform or derived_text provenance; text is not proof of an account relationship.","items":{"type":["object","null"],"description":"Entity observed at source or derived from text.","properties":{"name":{"type":["string","null"],"description":"Hashtag or account name."},"id":{"type":["string","null"],"description":"Platform ID when supplied."},"source":{"type":["string","null"],"description":"platform or derived_text."}}}},"caption":{"type":["string","null"],"description":"Public video description."},"shares":{"type":["number","null"],"description":"Observed shares."},"favorites":{"type":["number","null"],"description":"Observed collect count; null when absent."},"width":{"type":["number","null"],"description":"Video width in pixels."},"height":{"type":["number","null"],"description":"Video height in pixels."},"author_id":{"type":["string","null"],"description":"Stable creator ID when returned."},"author_display_name":{"type":["string","null"],"description":"Public display name."},"author_verified":{"type":["boolean","null"],"description":"Explicit creator verification state."},"author_avatar_url":{"type":["string","null"],"description":"Public creator avatar URL."},"region_code":{"type":["string","null"],"description":"Source content region code when exposed; not proof of creator residence."},"video_url":{"type":["string","null"],"description":"Public playback URL when supplied; may expire or require source request headers."},"subtitle_tracks":{"type":["array","null"],"description":"Subtitle links exposed by the public video; does not run transcription.","items":{"type":["object","null"],"description":"Subtitle track.","properties":{"language":{"type":["string","null"],"description":"Source language code."},"language_id":{"type":["string","null"],"description":"Source language identifier."},"url":{"type":["string","null"],"description":"Source subtitle URL."},"format":{"type":["string","null"],"description":"Subtitle format."}}}},"effects":{"type":["array","null"],"description":"Effect metadata exposed by the public page.","items":{"type":["object","null"],"description":"Effect.","properties":{"id":{"type":["string","null"],"description":"Effect ID."},"name":{"type":["string","null"],"description":"Effect name."}}}},"stickers":{"type":["array","null"],"description":"Sticker metadata exposed by the public page.","items":{"type":["object","null"],"description":"Sticker.","properties":{"type":{"type":["number","null"],"description":"Source sticker type."},"texts":{"type":["array","null"],"description":"Returned sticker text.","items":{"type":["string","null"],"description":"Text."}}}}},"music":{"type":["object","null"],"description":"Sound metadata from the public video.","properties":{"id":{"type":["string","null"],"description":"Sound ID."},"title":{"type":["string","null"],"description":"Sound title."},"author":{"type":["string","null"],"description":"Sound author."},"original":{"type":["boolean","null"],"description":"Source original-sound flag."},"duration_seconds":{"type":["number","null"],"description":"Sound duration."},"cover_url":{"type":["string","null"],"description":"Sound cover URL."},"play_url":{"type":["string","null"],"description":"Sound preview URL."}}},"playlist_id":{"type":["string","null"],"description":"Source playlist ID when returned."},"pinned":{"type":["boolean","null"],"description":"Explicit pinned-item state when returned."},"media_assets":{"type":["array","null"],"description":"Returned cover variants.","items":{"type":["object","null"],"description":"One source media variant; URLs may expire.","properties":{"url":{"type":["string","null"],"description":"Source URL."},"width":{"type":["number","null"],"description":"Width in pixels."},"height":{"type":["number","null"],"description":"Height in pixels."},"asset_type":{"type":["string","null"],"description":"image, video, thumbnail or avatar."},"variant":{"type":["string","null"],"description":"Source variant when known."},"expires_at":{"type":["string","null"],"description":"Expiry timestamp when known."}}}}}}}}}}}]}}}},"400":{"$ref":"#/components/responses/InvalidInput"},"401":{"$ref":"#/components/responses/InvalidApiKey"},"402":{"$ref":"#/components/responses/InsufficientCredits"},"403":{"$ref":"#/components/responses/SourceRestricted"},"404":{"$ref":"#/components/responses/ResourceNotFound"},"408":{"$ref":"#/components/responses/SourceTimeout"},"422":{"$ref":"#/components/responses/SourceResponseChanged"},"429":{"$ref":"#/components/responses/TemporaryCapacity"},"501":{"$ref":"#/components/responses/SourceNotImplemented"},"503":{"$ref":"#/components/responses/SourceUnavailable"}},"x-availability":"unavailable","x-identifier-one-of":["handle"],"x-credits":2,"x-source-access":"public_json","x-preview":true,"x-codeSamples":[{"lang":"curl","source":"curl 'https://api.socialdatakit.com/v1/tiktok/pinned?handle=tiktok' \\\n  -H 'x-api-key: YOUR_API_KEY'"},{"lang":"javascript","source":"const response = await fetch(\"https://api.socialdatakit.com/v1/tiktok/pinned?handle=tiktok\", {\n  headers: { \"x-api-key\": process.env.SOCIALDATAKIT_API_KEY }\n});\nif (!response.ok) throw new Error(await response.text());\nconst result = await response.json();"},{"lang":"python","source":"import os\nimport requests\n\nresponse = requests.get(\n    \"https://api.socialdatakit.com/v1/tiktok/pinned?handle=tiktok\",\n    headers={\"x-api-key\": os.environ[\"SOCIALDATAKIT_API_KEY\"]},\n    timeout=30,\n)\nresponse.raise_for_status()\nresult = response.json()"}],"x-response-fields":{"id":{"type":"string","description":"Resource identifier used by this endpoint."},"author":{"type":"string","description":"Public creator name or handle."},"published_at":{"type":"string","description":"Source publication date or timestamp; null when absent."},"views":{"type":"number","description":"Observed views, where exposed by this source."},"likes":{"type":"number","description":"Observed likes."},"comments":{"type":"number","description":"Observed comment count, not comment rows."},"media_url":{"type":"string","description":"Preview image URL; not a guaranteed downloadable video."},"permalink":{"type":"string","description":"Public content URL."},"duration_seconds":{"type":"number","description":"Duration in seconds when returned."},"hashtags":{"type":"array","description":"Hashtags with platform or derived_text provenance.","items":{"type":"object","description":"Entity observed at source or derived from text.","properties":{"name":{"type":"string","description":"Hashtag or account name."},"id":{"type":"string","description":"Platform ID when supplied."},"source":{"type":"string","description":"platform or derived_text."}}}},"mentions":{"type":"array","description":"Mentions with platform or derived_text provenance; text is not proof of an account relationship.","items":{"type":"object","description":"Entity observed at source or derived from text.","properties":{"name":{"type":"string","description":"Hashtag or account name."},"id":{"type":"string","description":"Platform ID when supplied."},"source":{"type":"string","description":"platform or derived_text."}}}},"caption":{"type":"string","description":"Public video description."},"shares":{"type":"number","description":"Observed shares."},"favorites":{"type":"number","description":"Observed collect count; null when absent."},"width":{"type":"number","description":"Video width in pixels."},"height":{"type":"number","description":"Video height in pixels."},"author_id":{"type":"string","description":"Stable creator ID when returned."},"author_display_name":{"type":"string","description":"Public display name."},"author_verified":{"type":"boolean","description":"Explicit creator verification state."},"author_avatar_url":{"type":"string","description":"Public creator avatar URL."},"region_code":{"type":"string","description":"Source content region code when exposed; not proof of creator residence."},"video_url":{"type":"string","description":"Public playback URL when supplied; may expire or require source request headers."},"subtitle_tracks":{"type":"array","description":"Subtitle links exposed by the public video; does not run transcription.","items":{"type":"object","description":"Subtitle track.","properties":{"language":{"type":"string","description":"Source language code."},"language_id":{"type":"string","description":"Source language identifier."},"url":{"type":"string","description":"Source subtitle URL."},"format":{"type":"string","description":"Subtitle format."}}}},"effects":{"type":"array","description":"Effect metadata exposed by the public page.","items":{"type":"object","description":"Effect.","properties":{"id":{"type":"string","description":"Effect ID."},"name":{"type":"string","description":"Effect name."}}}},"stickers":{"type":"array","description":"Sticker metadata exposed by the public page.","items":{"type":"object","description":"Sticker.","properties":{"type":{"type":"number","description":"Source sticker type."},"texts":{"type":"array","description":"Returned sticker text.","items":{"type":"string","description":"Text."}}}}},"music":{"type":"object","description":"Sound metadata from the public video.","properties":{"id":{"type":"string","description":"Sound ID."},"title":{"type":"string","description":"Sound title."},"author":{"type":"string","description":"Sound author."},"original":{"type":"boolean","description":"Source original-sound flag."},"duration_seconds":{"type":"number","description":"Sound duration."},"cover_url":{"type":"string","description":"Sound cover URL."},"play_url":{"type":"string","description":"Sound preview URL."}}},"playlist_id":{"type":"string","description":"Source playlist ID when returned."},"pinned":{"type":"boolean","description":"Explicit pinned-item state when returned."},"media_assets":{"type":"array","description":"Returned cover variants.","items":{"type":"object","description":"One source media variant; URLs may expire.","properties":{"url":{"type":"string","description":"Source URL."},"width":{"type":"number","description":"Width in pixels."},"height":{"type":"number","description":"Height in pixels."},"asset_type":{"type":"string","description":"image, video, thumbnail or avatar."},"variant":{"type":"string","description":"Source variant when known."},"expires_at":{"type":"string","description":"Expiry timestamp when known."}}}}}}},"/v1/tiktok/music":{"get":{"operationId":"tiktok_music","summary":"TikTok sound","description":"Get a sound’s title, creator, duration, cover and available usage count. Preview: evaluate live availability and source coverage before customer use.","tags":["tiktok"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"id","in":"query","required":true,"schema":{"type":"string","pattern":"^[0-9]{10,24}$","example":"6793970793613265670"},"description":"Required tiktok id."},{"name":"cache_max_age","in":"query","required":false,"schema":{"type":"string","enum":["1d","3d","7d","14d","30d"]},"description":"Maximum acceptable cache age. Valid cache hits cost zero credits."},{"name":"fields","in":"query","required":false,"schema":{"type":"string","example":"item"},"description":"Comma-separated fields or dot paths, including inside arrays such as items.id. Response identity and pagination are retained."},{"name":"trim","in":"query","required":false,"schema":{"type":"boolean","default":false},"description":"Remove null and empty values. Meaningful empty YouTube region-restriction lists are retained."},{"name":"region","in":"query","required":false,"description":"Country code","schema":{"type":"string","pattern":"^[A-Z]{2}$","example":"GB"}}],"responses":{"200":{"description":"Normalized resource","headers":{"x-request-id":{"schema":{"type":"string"}},"x-data-mode":{"schema":{"type":"string","enum":["live","sandbox"]}},"x-cache":{"schema":{"type":"string","enum":["HIT","MISS"]}},"x-credits-charged":{"schema":{"type":"integer"}},"x-credits-remaining":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"data":{"type":"object","properties":{"item":{"type":"object","additionalProperties":true,"properties":{"id":{"type":["string","null"],"description":"Sound ID."},"title":{"type":["string","null"],"description":"Sound title."},"author":{"type":["string","null"],"description":"Public sound author."},"original":{"type":["boolean","null"],"description":"Explicit source original-sound flag."},"duration_seconds":{"type":["number","null"],"description":"Sound duration."},"cover_url":{"type":["string","null"],"description":"Cover URL."},"play_url":{"type":["string","null"],"description":"Source preview URL; may expire."},"content_count":{"type":["number","null"],"description":"Observed videos using the sound."},"permalink":{"type":["string","null"],"description":"Public sound URL."}}}}}}}]}}}},"400":{"$ref":"#/components/responses/InvalidInput"},"401":{"$ref":"#/components/responses/InvalidApiKey"},"402":{"$ref":"#/components/responses/InsufficientCredits"},"403":{"$ref":"#/components/responses/SourceRestricted"},"404":{"$ref":"#/components/responses/ResourceNotFound"},"408":{"$ref":"#/components/responses/SourceTimeout"},"422":{"$ref":"#/components/responses/SourceResponseChanged"},"429":{"$ref":"#/components/responses/TemporaryCapacity"},"501":{"$ref":"#/components/responses/SourceNotImplemented"},"503":{"$ref":"#/components/responses/SourceUnavailable"}},"x-availability":"preview","x-identifier-one-of":["id"],"x-credits":1,"x-source-access":"public_page","x-preview":true,"x-codeSamples":[{"lang":"curl","source":"curl 'https://api.socialdatakit.com/v1/tiktok/music?id=6793970793613265670' \\\n  -H 'x-api-key: YOUR_API_KEY'"},{"lang":"javascript","source":"const response = await fetch(\"https://api.socialdatakit.com/v1/tiktok/music?id=6793970793613265670\", {\n  headers: { \"x-api-key\": process.env.SOCIALDATAKIT_API_KEY }\n});\nif (!response.ok) throw new Error(await response.text());\nconst result = await response.json();"},{"lang":"python","source":"import os\nimport requests\n\nresponse = requests.get(\n    \"https://api.socialdatakit.com/v1/tiktok/music?id=6793970793613265670\",\n    headers={\"x-api-key\": os.environ[\"SOCIALDATAKIT_API_KEY\"]},\n    timeout=30,\n)\nresponse.raise_for_status()\nresult = response.json()"}],"x-response-fields":{"id":{"type":"string","description":"Sound ID."},"title":{"type":"string","description":"Sound title."},"author":{"type":"string","description":"Public sound author."},"original":{"type":"boolean","description":"Explicit source original-sound flag."},"duration_seconds":{"type":"number","description":"Sound duration."},"cover_url":{"type":"string","description":"Cover URL."},"play_url":{"type":"string","description":"Source preview URL; may expire."},"content_count":{"type":"number","description":"Observed videos using the sound."},"permalink":{"type":"string","description":"Public sound URL."}}}},"/v1/tiktok/music/videos":{"get":{"operationId":"tiktok_music_videos","summary":"TikTok sound videos","description":"Get public videos that use a specific sound. Preview: evaluate live availability and source coverage before customer use.","tags":["tiktok"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"id","in":"query","required":true,"schema":{"type":"string","pattern":"^[0-9]{10,24}$","example":"6793970793613265670"},"description":"Required tiktok id."},{"name":"cache_max_age","in":"query","required":false,"schema":{"type":"string","enum":["1d","3d","7d","14d","30d"]},"description":"Maximum acceptable cache age. Valid cache hits cost zero credits."},{"name":"fields","in":"query","required":false,"schema":{"type":"string","example":"items"},"description":"Comma-separated fields or dot paths, including inside arrays such as items.id. Response identity and pagination are retained."},{"name":"trim","in":"query","required":false,"schema":{"type":"boolean","default":false},"description":"Remove null and empty values. Meaningful empty YouTube region-restriction lists are retained."},{"name":"region","in":"query","required":false,"description":"Country code","schema":{"type":"string","pattern":"^[A-Z]{2}$","example":"GB"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":20,"default":3},"description":"Number of items to return."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"},"description":"Opaque pagination value returned as data.pagination.next_cursor. Keep the identifier, filters and limit unchanged."}],"responses":{"200":{"description":"Normalized resource","headers":{"x-request-id":{"schema":{"type":"string"}},"x-data-mode":{"schema":{"type":"string","enum":["live","sandbox"]}},"x-cache":{"schema":{"type":"string","enum":["HIT","MISS"]}},"x-credits-charged":{"schema":{"type":"integer"}},"x-credits-remaining":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"data":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","additionalProperties":true,"properties":{"id":{"type":["string","null"],"description":"Resource identifier used by this endpoint."},"author":{"type":["string","null"],"description":"Public creator name or handle."},"published_at":{"type":["string","null"],"description":"Source publication date or timestamp; null when absent."},"views":{"type":["number","null"],"description":"Observed views, where exposed by this source."},"likes":{"type":["number","null"],"description":"Observed likes."},"comments":{"type":["number","null"],"description":"Observed comment count, not comment rows."},"media_url":{"type":["string","null"],"description":"Preview image URL; not a guaranteed downloadable video."},"permalink":{"type":["string","null"],"description":"Public content URL."},"duration_seconds":{"type":["number","null"],"description":"Duration in seconds when returned."},"hashtags":{"type":["array","null"],"description":"Hashtags with platform or derived_text provenance.","items":{"type":["object","null"],"description":"Entity observed at source or derived from text.","properties":{"name":{"type":["string","null"],"description":"Hashtag or account name."},"id":{"type":["string","null"],"description":"Platform ID when supplied."},"source":{"type":["string","null"],"description":"platform or derived_text."}}}},"mentions":{"type":["array","null"],"description":"Mentions with platform or derived_text provenance; text is not proof of an account relationship.","items":{"type":["object","null"],"description":"Entity observed at source or derived from text.","properties":{"name":{"type":["string","null"],"description":"Hashtag or account name."},"id":{"type":["string","null"],"description":"Platform ID when supplied."},"source":{"type":["string","null"],"description":"platform or derived_text."}}}},"caption":{"type":["string","null"],"description":"Public video description."},"shares":{"type":["number","null"],"description":"Observed shares."},"favorites":{"type":["number","null"],"description":"Observed collect count; null when absent."},"width":{"type":["number","null"],"description":"Video width in pixels."},"height":{"type":["number","null"],"description":"Video height in pixels."},"author_id":{"type":["string","null"],"description":"Stable creator ID when returned."},"author_display_name":{"type":["string","null"],"description":"Public display name."},"author_verified":{"type":["boolean","null"],"description":"Explicit creator verification state."},"author_avatar_url":{"type":["string","null"],"description":"Public creator avatar URL."},"region_code":{"type":["string","null"],"description":"Source content region code when exposed; not proof of creator residence."},"video_url":{"type":["string","null"],"description":"Public playback URL when supplied; may expire or require source request headers."},"subtitle_tracks":{"type":["array","null"],"description":"Subtitle links exposed by the public video; does not run transcription.","items":{"type":["object","null"],"description":"Subtitle track.","properties":{"language":{"type":["string","null"],"description":"Source language code."},"language_id":{"type":["string","null"],"description":"Source language identifier."},"url":{"type":["string","null"],"description":"Source subtitle URL."},"format":{"type":["string","null"],"description":"Subtitle format."}}}},"effects":{"type":["array","null"],"description":"Effect metadata exposed by the public page.","items":{"type":["object","null"],"description":"Effect.","properties":{"id":{"type":["string","null"],"description":"Effect ID."},"name":{"type":["string","null"],"description":"Effect name."}}}},"stickers":{"type":["array","null"],"description":"Sticker metadata exposed by the public page.","items":{"type":["object","null"],"description":"Sticker.","properties":{"type":{"type":["number","null"],"description":"Source sticker type."},"texts":{"type":["array","null"],"description":"Returned sticker text.","items":{"type":["string","null"],"description":"Text."}}}}},"music":{"type":["object","null"],"description":"Sound metadata from the public video.","properties":{"id":{"type":["string","null"],"description":"Sound ID."},"title":{"type":["string","null"],"description":"Sound title."},"author":{"type":["string","null"],"description":"Sound author."},"original":{"type":["boolean","null"],"description":"Source original-sound flag."},"duration_seconds":{"type":["number","null"],"description":"Sound duration."},"cover_url":{"type":["string","null"],"description":"Sound cover URL."},"play_url":{"type":["string","null"],"description":"Sound preview URL."}}},"playlist_id":{"type":["string","null"],"description":"Source playlist ID when returned."},"pinned":{"type":["boolean","null"],"description":"Explicit pinned-item state when returned."},"media_assets":{"type":["array","null"],"description":"Returned cover variants.","items":{"type":["object","null"],"description":"One source media variant; URLs may expire.","properties":{"url":{"type":["string","null"],"description":"Source URL."},"width":{"type":["number","null"],"description":"Width in pixels."},"height":{"type":["number","null"],"description":"Height in pixels."},"asset_type":{"type":["string","null"],"description":"image, video, thumbnail or avatar."},"variant":{"type":["string","null"],"description":"Source variant when known."},"expires_at":{"type":["string","null"],"description":"Expiry timestamp when known."}}}}}}}}}}}]}}}},"400":{"$ref":"#/components/responses/InvalidInput"},"401":{"$ref":"#/components/responses/InvalidApiKey"},"402":{"$ref":"#/components/responses/InsufficientCredits"},"403":{"$ref":"#/components/responses/SourceRestricted"},"404":{"$ref":"#/components/responses/ResourceNotFound"},"408":{"$ref":"#/components/responses/SourceTimeout"},"422":{"$ref":"#/components/responses/SourceResponseChanged"},"429":{"$ref":"#/components/responses/TemporaryCapacity"},"501":{"$ref":"#/components/responses/SourceNotImplemented"},"503":{"$ref":"#/components/responses/SourceUnavailable"}},"x-availability":"preview","x-identifier-one-of":["id"],"x-credits":2,"x-source-access":"public_json","x-preview":true,"x-codeSamples":[{"lang":"curl","source":"curl 'https://api.socialdatakit.com/v1/tiktok/music/videos?id=6793970793613265670' \\\n  -H 'x-api-key: YOUR_API_KEY'"},{"lang":"javascript","source":"const response = await fetch(\"https://api.socialdatakit.com/v1/tiktok/music/videos?id=6793970793613265670\", {\n  headers: { \"x-api-key\": process.env.SOCIALDATAKIT_API_KEY }\n});\nif (!response.ok) throw new Error(await response.text());\nconst result = await response.json();"},{"lang":"python","source":"import os\nimport requests\n\nresponse = requests.get(\n    \"https://api.socialdatakit.com/v1/tiktok/music/videos?id=6793970793613265670\",\n    headers={\"x-api-key\": os.environ[\"SOCIALDATAKIT_API_KEY\"]},\n    timeout=30,\n)\nresponse.raise_for_status()\nresult = response.json()"}],"x-response-fields":{"id":{"type":"string","description":"Resource identifier used by this endpoint."},"author":{"type":"string","description":"Public creator name or handle."},"published_at":{"type":"string","description":"Source publication date or timestamp; null when absent."},"views":{"type":"number","description":"Observed views, where exposed by this source."},"likes":{"type":"number","description":"Observed likes."},"comments":{"type":"number","description":"Observed comment count, not comment rows."},"media_url":{"type":"string","description":"Preview image URL; not a guaranteed downloadable video."},"permalink":{"type":"string","description":"Public content URL."},"duration_seconds":{"type":"number","description":"Duration in seconds when returned."},"hashtags":{"type":"array","description":"Hashtags with platform or derived_text provenance.","items":{"type":"object","description":"Entity observed at source or derived from text.","properties":{"name":{"type":"string","description":"Hashtag or account name."},"id":{"type":"string","description":"Platform ID when supplied."},"source":{"type":"string","description":"platform or derived_text."}}}},"mentions":{"type":"array","description":"Mentions with platform or derived_text provenance; text is not proof of an account relationship.","items":{"type":"object","description":"Entity observed at source or derived from text.","properties":{"name":{"type":"string","description":"Hashtag or account name."},"id":{"type":"string","description":"Platform ID when supplied."},"source":{"type":"string","description":"platform or derived_text."}}}},"caption":{"type":"string","description":"Public video description."},"shares":{"type":"number","description":"Observed shares."},"favorites":{"type":"number","description":"Observed collect count; null when absent."},"width":{"type":"number","description":"Video width in pixels."},"height":{"type":"number","description":"Video height in pixels."},"author_id":{"type":"string","description":"Stable creator ID when returned."},"author_display_name":{"type":"string","description":"Public display name."},"author_verified":{"type":"boolean","description":"Explicit creator verification state."},"author_avatar_url":{"type":"string","description":"Public creator avatar URL."},"region_code":{"type":"string","description":"Source content region code when exposed; not proof of creator residence."},"video_url":{"type":"string","description":"Public playback URL when supplied; may expire or require source request headers."},"subtitle_tracks":{"type":"array","description":"Subtitle links exposed by the public video; does not run transcription.","items":{"type":"object","description":"Subtitle track.","properties":{"language":{"type":"string","description":"Source language code."},"language_id":{"type":"string","description":"Source language identifier."},"url":{"type":"string","description":"Source subtitle URL."},"format":{"type":"string","description":"Subtitle format."}}}},"effects":{"type":"array","description":"Effect metadata exposed by the public page.","items":{"type":"object","description":"Effect.","properties":{"id":{"type":"string","description":"Effect ID."},"name":{"type":"string","description":"Effect name."}}}},"stickers":{"type":"array","description":"Sticker metadata exposed by the public page.","items":{"type":"object","description":"Sticker.","properties":{"type":{"type":"number","description":"Source sticker type."},"texts":{"type":"array","description":"Returned sticker text.","items":{"type":"string","description":"Text."}}}}},"music":{"type":"object","description":"Sound metadata from the public video.","properties":{"id":{"type":"string","description":"Sound ID."},"title":{"type":"string","description":"Sound title."},"author":{"type":"string","description":"Sound author."},"original":{"type":"boolean","description":"Source original-sound flag."},"duration_seconds":{"type":"number","description":"Sound duration."},"cover_url":{"type":"string","description":"Sound cover URL."},"play_url":{"type":"string","description":"Sound preview URL."}}},"playlist_id":{"type":"string","description":"Source playlist ID when returned."},"pinned":{"type":"boolean","description":"Explicit pinned-item state when returned."},"media_assets":{"type":"array","description":"Returned cover variants.","items":{"type":"object","description":"One source media variant; URLs may expire.","properties":{"url":{"type":"string","description":"Source URL."},"width":{"type":"number","description":"Width in pixels."},"height":{"type":"number","description":"Height in pixels."},"asset_type":{"type":"string","description":"image, video, thumbnail or avatar."},"variant":{"type":"string","description":"Source variant when known."},"expires_at":{"type":"string","description":"Expiry timestamp when known."}}}}}}},"/v1/tiktok/hashtag":{"get":{"operationId":"tiktok_hashtag","summary":"TikTok hashtag","description":"Get a hashtag’s name, description, cover and available video and view counts. Preview: evaluate live availability and source coverage before customer use.","tags":["tiktok"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"tag","in":"query","required":false,"schema":{"type":"string","pattern":"^[\\p{L}\\p{N}_]{1,100}$","example":"photography"},"description":"Required tiktok tag. Supply exactly one of: tag, hashtag."},{"name":"cache_max_age","in":"query","required":false,"schema":{"type":"string","enum":["1d","3d","7d","14d","30d"]},"description":"Maximum acceptable cache age. Valid cache hits cost zero credits."},{"name":"fields","in":"query","required":false,"schema":{"type":"string","example":"item"},"description":"Comma-separated fields or dot paths, including inside arrays such as items.id. Response identity and pagination are retained."},{"name":"trim","in":"query","required":false,"schema":{"type":"boolean","default":false},"description":"Remove null and empty values. Meaningful empty YouTube region-restriction lists are retained."},{"name":"hashtag","in":"query","required":false,"schema":{"type":"string","pattern":"^[\\p{L}\\p{N}_]{1,100}$"},"description":"Alternative to tag. Supply exactly one identifier."},{"name":"region","in":"query","required":false,"description":"Country code","schema":{"type":"string","pattern":"^[A-Z]{2}$","example":"GB"}}],"responses":{"200":{"description":"Normalized resource","headers":{"x-request-id":{"schema":{"type":"string"}},"x-data-mode":{"schema":{"type":"string","enum":["live","sandbox"]}},"x-cache":{"schema":{"type":"string","enum":["HIT","MISS"]}},"x-credits-charged":{"schema":{"type":"integer"}},"x-credits-remaining":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"data":{"type":"object","properties":{"item":{"type":"object","additionalProperties":true,"properties":{"id":{"type":["string","null"],"description":"Source hashtag ID."},"name":{"type":["string","null"],"description":"Hashtag name."},"description":{"type":["string","null"],"description":"Source description."},"content_count":{"type":["number","null"],"description":"Observed number of related posts/videos."},"views":{"type":["number","null"],"description":"Observed aggregate hashtag views, where exposed."},"cover_url":{"type":["string","null"],"description":"Public cover URL."},"permalink":{"type":["string","null"],"description":"Public hashtag page."}}}}}}}]}}}},"400":{"$ref":"#/components/responses/InvalidInput"},"401":{"$ref":"#/components/responses/InvalidApiKey"},"402":{"$ref":"#/components/responses/InsufficientCredits"},"403":{"$ref":"#/components/responses/SourceRestricted"},"404":{"$ref":"#/components/responses/ResourceNotFound"},"408":{"$ref":"#/components/responses/SourceTimeout"},"422":{"$ref":"#/components/responses/SourceResponseChanged"},"429":{"$ref":"#/components/responses/TemporaryCapacity"},"501":{"$ref":"#/components/responses/SourceNotImplemented"},"503":{"$ref":"#/components/responses/SourceUnavailable"}},"x-availability":"preview","x-identifier-one-of":["tag","hashtag"],"x-credits":1,"x-source-access":"public_page","x-preview":true,"x-codeSamples":[{"lang":"curl","source":"curl 'https://api.socialdatakit.com/v1/tiktok/hashtag?tag=photography' \\\n  -H 'x-api-key: YOUR_API_KEY'"},{"lang":"javascript","source":"const response = await fetch(\"https://api.socialdatakit.com/v1/tiktok/hashtag?tag=photography\", {\n  headers: { \"x-api-key\": process.env.SOCIALDATAKIT_API_KEY }\n});\nif (!response.ok) throw new Error(await response.text());\nconst result = await response.json();"},{"lang":"python","source":"import os\nimport requests\n\nresponse = requests.get(\n    \"https://api.socialdatakit.com/v1/tiktok/hashtag?tag=photography\",\n    headers={\"x-api-key\": os.environ[\"SOCIALDATAKIT_API_KEY\"]},\n    timeout=30,\n)\nresponse.raise_for_status()\nresult = response.json()"}],"x-response-fields":{"id":{"type":"string","description":"Source hashtag ID."},"name":{"type":"string","description":"Hashtag name."},"description":{"type":"string","description":"Source description."},"content_count":{"type":"number","description":"Observed number of related posts/videos."},"views":{"type":"number","description":"Observed aggregate hashtag views, where exposed."},"cover_url":{"type":"string","description":"Public cover URL."},"permalink":{"type":"string","description":"Public hashtag page."}}}},"/v1/tiktok/hashtag/videos":{"get":{"operationId":"tiktok_hashtag_videos","summary":"TikTok hashtag videos","description":"Get available public videos for a hashtag. Preview: evaluate live availability and source coverage before customer use.","tags":["tiktok"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"tag","in":"query","required":true,"schema":{"type":"string","pattern":"^[\\p{L}\\p{N}_]{1,100}$","example":"photography"},"description":"Required tiktok tag."},{"name":"cache_max_age","in":"query","required":false,"schema":{"type":"string","enum":["1d","3d","7d","14d","30d"]},"description":"Maximum acceptable cache age. Valid cache hits cost zero credits."},{"name":"fields","in":"query","required":false,"schema":{"type":"string","example":"items"},"description":"Comma-separated fields or dot paths, including inside arrays such as items.id. Response identity and pagination are retained."},{"name":"trim","in":"query","required":false,"schema":{"type":"boolean","default":false},"description":"Remove null and empty values. Meaningful empty YouTube region-restriction lists are retained."},{"name":"region","in":"query","required":false,"description":"Country code","schema":{"type":"string","pattern":"^[A-Z]{2}$","example":"GB"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":20,"default":3},"description":"Number of items to return."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"},"description":"Opaque pagination value returned as data.pagination.next_cursor. Keep the identifier, filters and limit unchanged."}],"responses":{"200":{"description":"Normalized resource","headers":{"x-request-id":{"schema":{"type":"string"}},"x-data-mode":{"schema":{"type":"string","enum":["live","sandbox"]}},"x-cache":{"schema":{"type":"string","enum":["HIT","MISS"]}},"x-credits-charged":{"schema":{"type":"integer"}},"x-credits-remaining":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"data":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","additionalProperties":true,"properties":{"id":{"type":["string","null"],"description":"Resource identifier used by this endpoint."},"author":{"type":["string","null"],"description":"Public creator name or handle."},"published_at":{"type":["string","null"],"description":"Source publication date or timestamp; null when absent."},"views":{"type":["number","null"],"description":"Observed views, where exposed by this source."},"likes":{"type":["number","null"],"description":"Observed likes."},"comments":{"type":["number","null"],"description":"Observed comment count, not comment rows."},"media_url":{"type":["string","null"],"description":"Preview image URL; not a guaranteed downloadable video."},"permalink":{"type":["string","null"],"description":"Public content URL."},"duration_seconds":{"type":["number","null"],"description":"Duration in seconds when returned."},"hashtags":{"type":["array","null"],"description":"Hashtags with platform or derived_text provenance.","items":{"type":["object","null"],"description":"Entity observed at source or derived from text.","properties":{"name":{"type":["string","null"],"description":"Hashtag or account name."},"id":{"type":["string","null"],"description":"Platform ID when supplied."},"source":{"type":["string","null"],"description":"platform or derived_text."}}}},"mentions":{"type":["array","null"],"description":"Mentions with platform or derived_text provenance; text is not proof of an account relationship.","items":{"type":["object","null"],"description":"Entity observed at source or derived from text.","properties":{"name":{"type":["string","null"],"description":"Hashtag or account name."},"id":{"type":["string","null"],"description":"Platform ID when supplied."},"source":{"type":["string","null"],"description":"platform or derived_text."}}}},"caption":{"type":["string","null"],"description":"Public video description."},"shares":{"type":["number","null"],"description":"Observed shares."},"favorites":{"type":["number","null"],"description":"Observed collect count; null when absent."},"width":{"type":["number","null"],"description":"Video width in pixels."},"height":{"type":["number","null"],"description":"Video height in pixels."},"author_id":{"type":["string","null"],"description":"Stable creator ID when returned."},"author_display_name":{"type":["string","null"],"description":"Public display name."},"author_verified":{"type":["boolean","null"],"description":"Explicit creator verification state."},"author_avatar_url":{"type":["string","null"],"description":"Public creator avatar URL."},"region_code":{"type":["string","null"],"description":"Source content region code when exposed; not proof of creator residence."},"video_url":{"type":["string","null"],"description":"Public playback URL when supplied; may expire or require source request headers."},"subtitle_tracks":{"type":["array","null"],"description":"Subtitle links exposed by the public video; does not run transcription.","items":{"type":["object","null"],"description":"Subtitle track.","properties":{"language":{"type":["string","null"],"description":"Source language code."},"language_id":{"type":["string","null"],"description":"Source language identifier."},"url":{"type":["string","null"],"description":"Source subtitle URL."},"format":{"type":["string","null"],"description":"Subtitle format."}}}},"effects":{"type":["array","null"],"description":"Effect metadata exposed by the public page.","items":{"type":["object","null"],"description":"Effect.","properties":{"id":{"type":["string","null"],"description":"Effect ID."},"name":{"type":["string","null"],"description":"Effect name."}}}},"stickers":{"type":["array","null"],"description":"Sticker metadata exposed by the public page.","items":{"type":["object","null"],"description":"Sticker.","properties":{"type":{"type":["number","null"],"description":"Source sticker type."},"texts":{"type":["array","null"],"description":"Returned sticker text.","items":{"type":["string","null"],"description":"Text."}}}}},"music":{"type":["object","null"],"description":"Sound metadata from the public video.","properties":{"id":{"type":["string","null"],"description":"Sound ID."},"title":{"type":["string","null"],"description":"Sound title."},"author":{"type":["string","null"],"description":"Sound author."},"original":{"type":["boolean","null"],"description":"Source original-sound flag."},"duration_seconds":{"type":["number","null"],"description":"Sound duration."},"cover_url":{"type":["string","null"],"description":"Sound cover URL."},"play_url":{"type":["string","null"],"description":"Sound preview URL."}}},"playlist_id":{"type":["string","null"],"description":"Source playlist ID when returned."},"pinned":{"type":["boolean","null"],"description":"Explicit pinned-item state when returned."},"media_assets":{"type":["array","null"],"description":"Returned cover variants.","items":{"type":["object","null"],"description":"One source media variant; URLs may expire.","properties":{"url":{"type":["string","null"],"description":"Source URL."},"width":{"type":["number","null"],"description":"Width in pixels."},"height":{"type":["number","null"],"description":"Height in pixels."},"asset_type":{"type":["string","null"],"description":"image, video, thumbnail or avatar."},"variant":{"type":["string","null"],"description":"Source variant when known."},"expires_at":{"type":["string","null"],"description":"Expiry timestamp when known."}}}}}}}}}}}]}}}},"400":{"$ref":"#/components/responses/InvalidInput"},"401":{"$ref":"#/components/responses/InvalidApiKey"},"402":{"$ref":"#/components/responses/InsufficientCredits"},"403":{"$ref":"#/components/responses/SourceRestricted"},"404":{"$ref":"#/components/responses/ResourceNotFound"},"408":{"$ref":"#/components/responses/SourceTimeout"},"422":{"$ref":"#/components/responses/SourceResponseChanged"},"429":{"$ref":"#/components/responses/TemporaryCapacity"},"501":{"$ref":"#/components/responses/SourceNotImplemented"},"503":{"$ref":"#/components/responses/SourceUnavailable"}},"x-availability":"preview","x-identifier-one-of":["tag"],"x-credits":2,"x-source-access":"public_json","x-preview":true,"x-codeSamples":[{"lang":"curl","source":"curl 'https://api.socialdatakit.com/v1/tiktok/hashtag/videos?tag=photography' \\\n  -H 'x-api-key: YOUR_API_KEY'"},{"lang":"javascript","source":"const response = await fetch(\"https://api.socialdatakit.com/v1/tiktok/hashtag/videos?tag=photography\", {\n  headers: { \"x-api-key\": process.env.SOCIALDATAKIT_API_KEY }\n});\nif (!response.ok) throw new Error(await response.text());\nconst result = await response.json();"},{"lang":"python","source":"import os\nimport requests\n\nresponse = requests.get(\n    \"https://api.socialdatakit.com/v1/tiktok/hashtag/videos?tag=photography\",\n    headers={\"x-api-key\": os.environ[\"SOCIALDATAKIT_API_KEY\"]},\n    timeout=30,\n)\nresponse.raise_for_status()\nresult = response.json()"}],"x-response-fields":{"id":{"type":"string","description":"Resource identifier used by this endpoint."},"author":{"type":"string","description":"Public creator name or handle."},"published_at":{"type":"string","description":"Source publication date or timestamp; null when absent."},"views":{"type":"number","description":"Observed views, where exposed by this source."},"likes":{"type":"number","description":"Observed likes."},"comments":{"type":"number","description":"Observed comment count, not comment rows."},"media_url":{"type":"string","description":"Preview image URL; not a guaranteed downloadable video."},"permalink":{"type":"string","description":"Public content URL."},"duration_seconds":{"type":"number","description":"Duration in seconds when returned."},"hashtags":{"type":"array","description":"Hashtags with platform or derived_text provenance.","items":{"type":"object","description":"Entity observed at source or derived from text.","properties":{"name":{"type":"string","description":"Hashtag or account name."},"id":{"type":"string","description":"Platform ID when supplied."},"source":{"type":"string","description":"platform or derived_text."}}}},"mentions":{"type":"array","description":"Mentions with platform or derived_text provenance; text is not proof of an account relationship.","items":{"type":"object","description":"Entity observed at source or derived from text.","properties":{"name":{"type":"string","description":"Hashtag or account name."},"id":{"type":"string","description":"Platform ID when supplied."},"source":{"type":"string","description":"platform or derived_text."}}}},"caption":{"type":"string","description":"Public video description."},"shares":{"type":"number","description":"Observed shares."},"favorites":{"type":"number","description":"Observed collect count; null when absent."},"width":{"type":"number","description":"Video width in pixels."},"height":{"type":"number","description":"Video height in pixels."},"author_id":{"type":"string","description":"Stable creator ID when returned."},"author_display_name":{"type":"string","description":"Public display name."},"author_verified":{"type":"boolean","description":"Explicit creator verification state."},"author_avatar_url":{"type":"string","description":"Public creator avatar URL."},"region_code":{"type":"string","description":"Source content region code when exposed; not proof of creator residence."},"video_url":{"type":"string","description":"Public playback URL when supplied; may expire or require source request headers."},"subtitle_tracks":{"type":"array","description":"Subtitle links exposed by the public video; does not run transcription.","items":{"type":"object","description":"Subtitle track.","properties":{"language":{"type":"string","description":"Source language code."},"language_id":{"type":"string","description":"Source language identifier."},"url":{"type":"string","description":"Source subtitle URL."},"format":{"type":"string","description":"Subtitle format."}}}},"effects":{"type":"array","description":"Effect metadata exposed by the public page.","items":{"type":"object","description":"Effect.","properties":{"id":{"type":"string","description":"Effect ID."},"name":{"type":"string","description":"Effect name."}}}},"stickers":{"type":"array","description":"Sticker metadata exposed by the public page.","items":{"type":"object","description":"Sticker.","properties":{"type":{"type":"number","description":"Source sticker type."},"texts":{"type":"array","description":"Returned sticker text.","items":{"type":"string","description":"Text."}}}}},"music":{"type":"object","description":"Sound metadata from the public video.","properties":{"id":{"type":"string","description":"Sound ID."},"title":{"type":"string","description":"Sound title."},"author":{"type":"string","description":"Sound author."},"original":{"type":"boolean","description":"Source original-sound flag."},"duration_seconds":{"type":"number","description":"Sound duration."},"cover_url":{"type":"string","description":"Sound cover URL."},"play_url":{"type":"string","description":"Sound preview URL."}}},"playlist_id":{"type":"string","description":"Source playlist ID when returned."},"pinned":{"type":"boolean","description":"Explicit pinned-item state when returned."},"media_assets":{"type":"array","description":"Returned cover variants.","items":{"type":"object","description":"One source media variant; URLs may expire.","properties":{"url":{"type":"string","description":"Source URL."},"width":{"type":"number","description":"Width in pixels."},"height":{"type":"number","description":"Height in pixels."},"asset_type":{"type":"string","description":"image, video, thumbnail or avatar."},"variant":{"type":"string","description":"Source variant when known."},"expires_at":{"type":"string","description":"Expiry timestamp when known."}}}}}}},"/v1/tiktok/playlist":{"get":{"operationId":"tiktok_playlist","summary":"TikTok playlist","description":"Get a public playlist’s title, creator, video count and last update time. Preview: evaluate live availability and source coverage before customer use.","tags":["tiktok"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"id","in":"query","required":true,"schema":{"type":"string","pattern":"^[0-9]{10,24}$","example":"7350000000000000000"},"description":"Required tiktok id."},{"name":"cache_max_age","in":"query","required":false,"schema":{"type":"string","enum":["1d","3d","7d","14d","30d"]},"description":"Maximum acceptable cache age. Valid cache hits cost zero credits."},{"name":"fields","in":"query","required":false,"schema":{"type":"string","example":"item"},"description":"Comma-separated fields or dot paths, including inside arrays such as items.id. Response identity and pagination are retained."},{"name":"trim","in":"query","required":false,"schema":{"type":"boolean","default":false},"description":"Remove null and empty values. Meaningful empty YouTube region-restriction lists are retained."},{"name":"region","in":"query","required":false,"description":"Country code","schema":{"type":"string","pattern":"^[A-Z]{2}$","example":"GB"}}],"responses":{"200":{"description":"Normalized resource","headers":{"x-request-id":{"schema":{"type":"string"}},"x-data-mode":{"schema":{"type":"string","enum":["live","sandbox"]}},"x-cache":{"schema":{"type":"string","enum":["HIT","MISS"]}},"x-credits-charged":{"schema":{"type":"integer"}},"x-credits-remaining":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"data":{"type":"object","properties":{"item":{"type":"object","additionalProperties":true,"properties":{"id":{"type":["string","null"],"description":"Playlist ID."},"title":{"type":["string","null"],"description":"Playlist title."},"description":{"type":["string","null"],"description":"Public description."},"author":{"type":["string","null"],"description":"Public owner name/handle."},"account_id":{"type":["string","null"],"description":"Playlist owner account ID."},"item_count":{"type":["number","null"],"description":"Source total item count."},"published_at":{"type":["string","null"],"description":"Creation timestamp."},"updated_at":{"type":["string","null"],"description":"Source update time."},"thumbnails":{"type":["array","null"],"description":"All returned thumbnail variants; dimensions are source values.","items":{"type":["object","null"],"description":"Thumbnail.","properties":{"url":{"type":["string","null"],"description":"Source URL."},"variant":{"type":["string","null"],"description":"Source variant."},"width":{"type":["number","null"],"description":"Width."},"height":{"type":["number","null"],"description":"Height."},"asset_type":{"type":["string","null"],"description":"thumbnail."},"expires_at":{"type":["string","null"],"description":"Expiry when known."}}}},"language":{"type":["string","null"],"description":"Default language."},"localized":{"type":["object","null"],"description":"Selected localized text.","properties":{"title":{"type":["string","null"],"description":"Title."},"description":{"type":["string","null"],"description":"Description."}}},"localizations":{"type":["object","null"],"description":"Returned localizations map."},"privacy_status":{"type":["string","null"],"description":"Explicit source privacy status."},"embed_html":{"type":["string","null"],"description":"Public embed markup as text."},"permalink":{"type":["string","null"],"description":"Public playlist URL."}}}}}}}]}}}},"400":{"$ref":"#/components/responses/InvalidInput"},"401":{"$ref":"#/components/responses/InvalidApiKey"},"402":{"$ref":"#/components/responses/InsufficientCredits"},"403":{"$ref":"#/components/responses/SourceRestricted"},"404":{"$ref":"#/components/responses/ResourceNotFound"},"408":{"$ref":"#/components/responses/SourceTimeout"},"422":{"$ref":"#/components/responses/SourceResponseChanged"},"429":{"$ref":"#/components/responses/TemporaryCapacity"},"501":{"$ref":"#/components/responses/SourceNotImplemented"},"503":{"$ref":"#/components/responses/SourceUnavailable"}},"x-availability":"preview","x-identifier-one-of":["id"],"x-credits":1,"x-source-access":"public_page","x-preview":true,"x-codeSamples":[{"lang":"curl","source":"curl 'https://api.socialdatakit.com/v1/tiktok/playlist?id=7350000000000000000' \\\n  -H 'x-api-key: YOUR_API_KEY'"},{"lang":"javascript","source":"const response = await fetch(\"https://api.socialdatakit.com/v1/tiktok/playlist?id=7350000000000000000\", {\n  headers: { \"x-api-key\": process.env.SOCIALDATAKIT_API_KEY }\n});\nif (!response.ok) throw new Error(await response.text());\nconst result = await response.json();"},{"lang":"python","source":"import os\nimport requests\n\nresponse = requests.get(\n    \"https://api.socialdatakit.com/v1/tiktok/playlist?id=7350000000000000000\",\n    headers={\"x-api-key\": os.environ[\"SOCIALDATAKIT_API_KEY\"]},\n    timeout=30,\n)\nresponse.raise_for_status()\nresult = response.json()"}],"x-response-fields":{"id":{"type":"string","description":"Playlist ID."},"title":{"type":"string","description":"Playlist title."},"description":{"type":"string","description":"Public description."},"author":{"type":"string","description":"Public owner name/handle."},"account_id":{"type":"string","description":"Playlist owner account ID."},"item_count":{"type":"number","description":"Source total item count."},"published_at":{"type":"string","description":"Creation timestamp."},"updated_at":{"type":"string","description":"Source update time."},"thumbnails":{"type":"array","description":"All returned thumbnail variants; dimensions are source values.","items":{"type":"object","description":"Thumbnail.","properties":{"url":{"type":"string","description":"Source URL."},"variant":{"type":"string","description":"Source variant."},"width":{"type":"number","description":"Width."},"height":{"type":"number","description":"Height."},"asset_type":{"type":"string","description":"thumbnail."},"expires_at":{"type":"string","description":"Expiry when known."}}}},"language":{"type":"string","description":"Default language."},"localized":{"type":"object","description":"Selected localized text.","properties":{"title":{"type":"string","description":"Title."},"description":{"type":"string","description":"Description."}}},"localizations":{"type":"object","description":"Returned localizations map."},"privacy_status":{"type":"string","description":"Explicit source privacy status."},"embed_html":{"type":"string","description":"Public embed markup as text."},"permalink":{"type":"string","description":"Public playlist URL."}}}},"/v1/tiktok/playlist/videos":{"get":{"operationId":"tiktok_playlist_videos","summary":"TikTok playlist videos","description":"Get videos in a public TikTok playlist. Preview: evaluate live availability and source coverage before customer use.","tags":["tiktok"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"id","in":"query","required":true,"schema":{"type":"string","pattern":"^[0-9]{10,24}$","example":"7350000000000000000"},"description":"Required tiktok id."},{"name":"cache_max_age","in":"query","required":false,"schema":{"type":"string","enum":["1d","3d","7d","14d","30d"]},"description":"Maximum acceptable cache age. Valid cache hits cost zero credits."},{"name":"fields","in":"query","required":false,"schema":{"type":"string","example":"items"},"description":"Comma-separated fields or dot paths, including inside arrays such as items.id. Response identity and pagination are retained."},{"name":"trim","in":"query","required":false,"schema":{"type":"boolean","default":false},"description":"Remove null and empty values. Meaningful empty YouTube region-restriction lists are retained."},{"name":"region","in":"query","required":false,"description":"Country code","schema":{"type":"string","pattern":"^[A-Z]{2}$","example":"GB"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":20,"default":3},"description":"Number of items to return."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"},"description":"Opaque pagination value returned as data.pagination.next_cursor. Keep the identifier, filters and limit unchanged."}],"responses":{"200":{"description":"Normalized resource","headers":{"x-request-id":{"schema":{"type":"string"}},"x-data-mode":{"schema":{"type":"string","enum":["live","sandbox"]}},"x-cache":{"schema":{"type":"string","enum":["HIT","MISS"]}},"x-credits-charged":{"schema":{"type":"integer"}},"x-credits-remaining":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"data":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","additionalProperties":true,"properties":{"id":{"type":["string","null"],"description":"Resource identifier used by this endpoint."},"author":{"type":["string","null"],"description":"Public creator name or handle."},"published_at":{"type":["string","null"],"description":"Source publication date or timestamp; null when absent."},"views":{"type":["number","null"],"description":"Observed views, where exposed by this source."},"likes":{"type":["number","null"],"description":"Observed likes."},"comments":{"type":["number","null"],"description":"Observed comment count, not comment rows."},"media_url":{"type":["string","null"],"description":"Preview image URL; not a guaranteed downloadable video."},"permalink":{"type":["string","null"],"description":"Public content URL."},"duration_seconds":{"type":["number","null"],"description":"Duration in seconds when returned."},"hashtags":{"type":["array","null"],"description":"Hashtags with platform or derived_text provenance.","items":{"type":["object","null"],"description":"Entity observed at source or derived from text.","properties":{"name":{"type":["string","null"],"description":"Hashtag or account name."},"id":{"type":["string","null"],"description":"Platform ID when supplied."},"source":{"type":["string","null"],"description":"platform or derived_text."}}}},"mentions":{"type":["array","null"],"description":"Mentions with platform or derived_text provenance; text is not proof of an account relationship.","items":{"type":["object","null"],"description":"Entity observed at source or derived from text.","properties":{"name":{"type":["string","null"],"description":"Hashtag or account name."},"id":{"type":["string","null"],"description":"Platform ID when supplied."},"source":{"type":["string","null"],"description":"platform or derived_text."}}}},"caption":{"type":["string","null"],"description":"Public video description."},"shares":{"type":["number","null"],"description":"Observed shares."},"favorites":{"type":["number","null"],"description":"Observed collect count; null when absent."},"width":{"type":["number","null"],"description":"Video width in pixels."},"height":{"type":["number","null"],"description":"Video height in pixels."},"author_id":{"type":["string","null"],"description":"Stable creator ID when returned."},"author_display_name":{"type":["string","null"],"description":"Public display name."},"author_verified":{"type":["boolean","null"],"description":"Explicit creator verification state."},"author_avatar_url":{"type":["string","null"],"description":"Public creator avatar URL."},"region_code":{"type":["string","null"],"description":"Source content region code when exposed; not proof of creator residence."},"video_url":{"type":["string","null"],"description":"Public playback URL when supplied; may expire or require source request headers."},"subtitle_tracks":{"type":["array","null"],"description":"Subtitle links exposed by the public video; does not run transcription.","items":{"type":["object","null"],"description":"Subtitle track.","properties":{"language":{"type":["string","null"],"description":"Source language code."},"language_id":{"type":["string","null"],"description":"Source language identifier."},"url":{"type":["string","null"],"description":"Source subtitle URL."},"format":{"type":["string","null"],"description":"Subtitle format."}}}},"effects":{"type":["array","null"],"description":"Effect metadata exposed by the public page.","items":{"type":["object","null"],"description":"Effect.","properties":{"id":{"type":["string","null"],"description":"Effect ID."},"name":{"type":["string","null"],"description":"Effect name."}}}},"stickers":{"type":["array","null"],"description":"Sticker metadata exposed by the public page.","items":{"type":["object","null"],"description":"Sticker.","properties":{"type":{"type":["number","null"],"description":"Source sticker type."},"texts":{"type":["array","null"],"description":"Returned sticker text.","items":{"type":["string","null"],"description":"Text."}}}}},"music":{"type":["object","null"],"description":"Sound metadata from the public video.","properties":{"id":{"type":["string","null"],"description":"Sound ID."},"title":{"type":["string","null"],"description":"Sound title."},"author":{"type":["string","null"],"description":"Sound author."},"original":{"type":["boolean","null"],"description":"Source original-sound flag."},"duration_seconds":{"type":["number","null"],"description":"Sound duration."},"cover_url":{"type":["string","null"],"description":"Sound cover URL."},"play_url":{"type":["string","null"],"description":"Sound preview URL."}}},"playlist_id":{"type":["string","null"],"description":"Source playlist ID when returned."},"pinned":{"type":["boolean","null"],"description":"Explicit pinned-item state when returned."},"media_assets":{"type":["array","null"],"description":"Returned cover variants.","items":{"type":["object","null"],"description":"One source media variant; URLs may expire.","properties":{"url":{"type":["string","null"],"description":"Source URL."},"width":{"type":["number","null"],"description":"Width in pixels."},"height":{"type":["number","null"],"description":"Height in pixels."},"asset_type":{"type":["string","null"],"description":"image, video, thumbnail or avatar."},"variant":{"type":["string","null"],"description":"Source variant when known."},"expires_at":{"type":["string","null"],"description":"Expiry timestamp when known."}}}}}}}}}}}]}}}},"400":{"$ref":"#/components/responses/InvalidInput"},"401":{"$ref":"#/components/responses/InvalidApiKey"},"402":{"$ref":"#/components/responses/InsufficientCredits"},"403":{"$ref":"#/components/responses/SourceRestricted"},"404":{"$ref":"#/components/responses/ResourceNotFound"},"408":{"$ref":"#/components/responses/SourceTimeout"},"422":{"$ref":"#/components/responses/SourceResponseChanged"},"429":{"$ref":"#/components/responses/TemporaryCapacity"},"501":{"$ref":"#/components/responses/SourceNotImplemented"},"503":{"$ref":"#/components/responses/SourceUnavailable"}},"x-availability":"preview","x-identifier-one-of":["id"],"x-credits":2,"x-source-access":"public_json","x-preview":true,"x-codeSamples":[{"lang":"curl","source":"curl 'https://api.socialdatakit.com/v1/tiktok/playlist/videos?id=7350000000000000000' \\\n  -H 'x-api-key: YOUR_API_KEY'"},{"lang":"javascript","source":"const response = await fetch(\"https://api.socialdatakit.com/v1/tiktok/playlist/videos?id=7350000000000000000\", {\n  headers: { \"x-api-key\": process.env.SOCIALDATAKIT_API_KEY }\n});\nif (!response.ok) throw new Error(await response.text());\nconst result = await response.json();"},{"lang":"python","source":"import os\nimport requests\n\nresponse = requests.get(\n    \"https://api.socialdatakit.com/v1/tiktok/playlist/videos?id=7350000000000000000\",\n    headers={\"x-api-key\": os.environ[\"SOCIALDATAKIT_API_KEY\"]},\n    timeout=30,\n)\nresponse.raise_for_status()\nresult = response.json()"}],"x-response-fields":{"id":{"type":"string","description":"Resource identifier used by this endpoint."},"author":{"type":"string","description":"Public creator name or handle."},"published_at":{"type":"string","description":"Source publication date or timestamp; null when absent."},"views":{"type":"number","description":"Observed views, where exposed by this source."},"likes":{"type":"number","description":"Observed likes."},"comments":{"type":"number","description":"Observed comment count, not comment rows."},"media_url":{"type":"string","description":"Preview image URL; not a guaranteed downloadable video."},"permalink":{"type":"string","description":"Public content URL."},"duration_seconds":{"type":"number","description":"Duration in seconds when returned."},"hashtags":{"type":"array","description":"Hashtags with platform or derived_text provenance.","items":{"type":"object","description":"Entity observed at source or derived from text.","properties":{"name":{"type":"string","description":"Hashtag or account name."},"id":{"type":"string","description":"Platform ID when supplied."},"source":{"type":"string","description":"platform or derived_text."}}}},"mentions":{"type":"array","description":"Mentions with platform or derived_text provenance; text is not proof of an account relationship.","items":{"type":"object","description":"Entity observed at source or derived from text.","properties":{"name":{"type":"string","description":"Hashtag or account name."},"id":{"type":"string","description":"Platform ID when supplied."},"source":{"type":"string","description":"platform or derived_text."}}}},"caption":{"type":"string","description":"Public video description."},"shares":{"type":"number","description":"Observed shares."},"favorites":{"type":"number","description":"Observed collect count; null when absent."},"width":{"type":"number","description":"Video width in pixels."},"height":{"type":"number","description":"Video height in pixels."},"author_id":{"type":"string","description":"Stable creator ID when returned."},"author_display_name":{"type":"string","description":"Public display name."},"author_verified":{"type":"boolean","description":"Explicit creator verification state."},"author_avatar_url":{"type":"string","description":"Public creator avatar URL."},"region_code":{"type":"string","description":"Source content region code when exposed; not proof of creator residence."},"video_url":{"type":"string","description":"Public playback URL when supplied; may expire or require source request headers."},"subtitle_tracks":{"type":"array","description":"Subtitle links exposed by the public video; does not run transcription.","items":{"type":"object","description":"Subtitle track.","properties":{"language":{"type":"string","description":"Source language code."},"language_id":{"type":"string","description":"Source language identifier."},"url":{"type":"string","description":"Source subtitle URL."},"format":{"type":"string","description":"Subtitle format."}}}},"effects":{"type":"array","description":"Effect metadata exposed by the public page.","items":{"type":"object","description":"Effect.","properties":{"id":{"type":"string","description":"Effect ID."},"name":{"type":"string","description":"Effect name."}}}},"stickers":{"type":"array","description":"Sticker metadata exposed by the public page.","items":{"type":"object","description":"Sticker.","properties":{"type":{"type":"number","description":"Source sticker type."},"texts":{"type":"array","description":"Returned sticker text.","items":{"type":"string","description":"Text."}}}}},"music":{"type":"object","description":"Sound metadata from the public video.","properties":{"id":{"type":"string","description":"Sound ID."},"title":{"type":"string","description":"Sound title."},"author":{"type":"string","description":"Sound author."},"original":{"type":"boolean","description":"Source original-sound flag."},"duration_seconds":{"type":"number","description":"Sound duration."},"cover_url":{"type":"string","description":"Sound cover URL."},"play_url":{"type":"string","description":"Sound preview URL."}}},"playlist_id":{"type":"string","description":"Source playlist ID when returned."},"pinned":{"type":"boolean","description":"Explicit pinned-item state when returned."},"media_assets":{"type":"array","description":"Returned cover variants.","items":{"type":"object","description":"One source media variant; URLs may expire.","properties":{"url":{"type":"string","description":"Source URL."},"width":{"type":"number","description":"Width in pixels."},"height":{"type":"number","description":"Height in pixels."},"asset_type":{"type":"string","description":"image, video, thumbnail or avatar."},"variant":{"type":"string","description":"Source variant when known."},"expires_at":{"type":"string","description":"Expiry timestamp when known."}}}}}}},"/v1/tiktok/comments":{"get":{"operationId":"tiktok_comments","summary":"TikTok video comments","description":"Get available public video comments, authors, likes and reply counts. Preview: evaluate live availability and source coverage before customer use.","tags":["tiktok"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"id","in":"query","required":true,"schema":{"type":"string","pattern":"^[0-9]{10,24}$","example":"7350000000000000000"},"description":"Required tiktok id."},{"name":"cache_max_age","in":"query","required":false,"schema":{"type":"string","enum":["1d","3d","7d","14d","30d"]},"description":"Maximum acceptable cache age. Valid cache hits cost zero credits."},{"name":"fields","in":"query","required":false,"schema":{"type":"string","example":"items"},"description":"Comma-separated fields or dot paths, including inside arrays such as items.id. Response identity and pagination are retained."},{"name":"trim","in":"query","required":false,"schema":{"type":"boolean","default":false},"description":"Remove null and empty values. Meaningful empty YouTube region-restriction lists are retained."},{"name":"region","in":"query","required":false,"description":"Country code","schema":{"type":"string","pattern":"^[A-Z]{2}$","example":"GB"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":20,"default":3},"description":"Number of items to return."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"},"description":"Opaque pagination value returned as data.pagination.next_cursor. Keep the identifier, filters and limit unchanged."}],"responses":{"200":{"description":"Normalized resource","headers":{"x-request-id":{"schema":{"type":"string"}},"x-data-mode":{"schema":{"type":"string","enum":["live","sandbox"]}},"x-cache":{"schema":{"type":"string","enum":["HIT","MISS"]}},"x-credits-charged":{"schema":{"type":"integer"}},"x-credits-remaining":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"data":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","additionalProperties":true,"properties":{"id":{"type":["string","null"],"description":"Platform comment ID, retained as a string."},"content_id":{"type":["string","null"],"description":"Parent video/post ID when known."},"parent_comment_id":{"type":["string","null"],"description":"Top-level comment ID for a reply; null for a top-level comment or unknown parent."},"text":{"type":["string","null"],"description":"Public comment text. YouTube requests plainText formatting; no owner-only textOriginal."},"likes":{"type":["number","null"],"description":"Observed comment likes."},"reply_count":{"type":["number","null"],"description":"Observed total reply count; not the number of replies returned."},"author_id":{"type":["string","null"],"description":"Public author account ID."},"author_username":{"type":["string","null"],"description":"Public author handle."},"author_display_name":{"type":["string","null"],"description":"Public display name."},"author_avatar_url":{"type":["string","null"],"description":"Public avatar URL."},"author_profile_url":{"type":["string","null"],"description":"Public author profile URL."},"published_at":{"type":["string","null"],"description":"Comment publication timestamp."},"updated_at":{"type":["string","null"],"description":"Source edit timestamp when available."}}}}}}}}]}}}},"400":{"$ref":"#/components/responses/InvalidInput"},"401":{"$ref":"#/components/responses/InvalidApiKey"},"402":{"$ref":"#/components/responses/InsufficientCredits"},"403":{"$ref":"#/components/responses/SourceRestricted"},"404":{"$ref":"#/components/responses/ResourceNotFound"},"408":{"$ref":"#/components/responses/SourceTimeout"},"422":{"$ref":"#/components/responses/SourceResponseChanged"},"429":{"$ref":"#/components/responses/TemporaryCapacity"},"501":{"$ref":"#/components/responses/SourceNotImplemented"},"503":{"$ref":"#/components/responses/SourceUnavailable"}},"x-availability":"preview","x-identifier-one-of":["id"],"x-credits":2,"x-source-access":"public_json","x-preview":true,"x-codeSamples":[{"lang":"curl","source":"curl 'https://api.socialdatakit.com/v1/tiktok/comments?id=7350000000000000000' \\\n  -H 'x-api-key: YOUR_API_KEY'"},{"lang":"javascript","source":"const response = await fetch(\"https://api.socialdatakit.com/v1/tiktok/comments?id=7350000000000000000\", {\n  headers: { \"x-api-key\": process.env.SOCIALDATAKIT_API_KEY }\n});\nif (!response.ok) throw new Error(await response.text());\nconst result = await response.json();"},{"lang":"python","source":"import os\nimport requests\n\nresponse = requests.get(\n    \"https://api.socialdatakit.com/v1/tiktok/comments?id=7350000000000000000\",\n    headers={\"x-api-key\": os.environ[\"SOCIALDATAKIT_API_KEY\"]},\n    timeout=30,\n)\nresponse.raise_for_status()\nresult = response.json()"}],"x-response-fields":{"id":{"type":"string","description":"Platform comment ID, retained as a string."},"content_id":{"type":"string","description":"Parent video/post ID when known."},"parent_comment_id":{"type":"string","description":"Top-level comment ID for a reply; null for a top-level comment or unknown parent."},"text":{"type":"string","description":"Public comment text. YouTube requests plainText formatting; no owner-only textOriginal."},"likes":{"type":"number","description":"Observed comment likes."},"reply_count":{"type":"number","description":"Observed total reply count; not the number of replies returned."},"author_id":{"type":"string","description":"Public author account ID."},"author_username":{"type":"string","description":"Public author handle."},"author_display_name":{"type":"string","description":"Public display name."},"author_avatar_url":{"type":"string","description":"Public avatar URL."},"author_profile_url":{"type":"string","description":"Public author profile URL."},"published_at":{"type":"string","description":"Comment publication timestamp."},"updated_at":{"type":"string","description":"Source edit timestamp when available."}}}},"/v1/tiktok/comment/replies":{"get":{"operationId":"tiktok_comment_replies","summary":"TikTok comment replies","description":"Get available public replies to a comment. Include the video ID and comment ID. Preview: evaluate live availability and source coverage before customer use.","tags":["tiktok"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"comment_id","in":"query","required":true,"schema":{"type":"string","pattern":"^[0-9]{10,24}$","example":"7350000000000000001"},"description":"Required tiktok comment_id."},{"name":"cache_max_age","in":"query","required":false,"schema":{"type":"string","enum":["1d","3d","7d","14d","30d"]},"description":"Maximum acceptable cache age. Valid cache hits cost zero credits."},{"name":"fields","in":"query","required":false,"schema":{"type":"string","example":"items"},"description":"Comma-separated fields or dot paths, including inside arrays such as items.id. Response identity and pagination are retained."},{"name":"trim","in":"query","required":false,"schema":{"type":"boolean","default":false},"description":"Remove null and empty values. Meaningful empty YouTube region-restriction lists are retained."},{"name":"video_id","in":"query","required":true,"description":"TikTok video ID","schema":{"type":"string","pattern":"^[0-9]{10,24}$","example":"7350000000000000000"}},{"name":"region","in":"query","required":false,"description":"Country code","schema":{"type":"string","pattern":"^[A-Z]{2}$","example":"GB"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":20,"default":3},"description":"Number of items to return."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"},"description":"Opaque pagination value returned as data.pagination.next_cursor. Keep the identifier, filters and limit unchanged."}],"responses":{"200":{"description":"Normalized resource","headers":{"x-request-id":{"schema":{"type":"string"}},"x-data-mode":{"schema":{"type":"string","enum":["live","sandbox"]}},"x-cache":{"schema":{"type":"string","enum":["HIT","MISS"]}},"x-credits-charged":{"schema":{"type":"integer"}},"x-credits-remaining":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"data":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","additionalProperties":true,"properties":{"id":{"type":["string","null"],"description":"Platform comment ID, retained as a string."},"content_id":{"type":["string","null"],"description":"Parent video/post ID when known."},"parent_comment_id":{"type":["string","null"],"description":"Top-level comment ID for a reply; null for a top-level comment or unknown parent."},"text":{"type":["string","null"],"description":"Public comment text. YouTube requests plainText formatting; no owner-only textOriginal."},"likes":{"type":["number","null"],"description":"Observed comment likes."},"reply_count":{"type":["number","null"],"description":"Observed total reply count; not the number of replies returned."},"author_id":{"type":["string","null"],"description":"Public author account ID."},"author_username":{"type":["string","null"],"description":"Public author handle."},"author_display_name":{"type":["string","null"],"description":"Public display name."},"author_avatar_url":{"type":["string","null"],"description":"Public avatar URL."},"author_profile_url":{"type":["string","null"],"description":"Public author profile URL."},"published_at":{"type":["string","null"],"description":"Comment publication timestamp."},"updated_at":{"type":["string","null"],"description":"Source edit timestamp when available."}}}}}}}}]}}}},"400":{"$ref":"#/components/responses/InvalidInput"},"401":{"$ref":"#/components/responses/InvalidApiKey"},"402":{"$ref":"#/components/responses/InsufficientCredits"},"403":{"$ref":"#/components/responses/SourceRestricted"},"404":{"$ref":"#/components/responses/ResourceNotFound"},"408":{"$ref":"#/components/responses/SourceTimeout"},"422":{"$ref":"#/components/responses/SourceResponseChanged"},"429":{"$ref":"#/components/responses/TemporaryCapacity"},"501":{"$ref":"#/components/responses/SourceNotImplemented"},"503":{"$ref":"#/components/responses/SourceUnavailable"}},"x-availability":"preview","x-identifier-one-of":["comment_id"],"x-credits":2,"x-source-access":"public_json","x-preview":true,"x-codeSamples":[{"lang":"curl","source":"curl 'https://api.socialdatakit.com/v1/tiktok/comment/replies?comment_id=7350000000000000001&video_id=7350000000000000000' \\\n  -H 'x-api-key: YOUR_API_KEY'"},{"lang":"javascript","source":"const response = await fetch(\"https://api.socialdatakit.com/v1/tiktok/comment/replies?comment_id=7350000000000000001&video_id=7350000000000000000\", {\n  headers: { \"x-api-key\": process.env.SOCIALDATAKIT_API_KEY }\n});\nif (!response.ok) throw new Error(await response.text());\nconst result = await response.json();"},{"lang":"python","source":"import os\nimport requests\n\nresponse = requests.get(\n    \"https://api.socialdatakit.com/v1/tiktok/comment/replies?comment_id=7350000000000000001&video_id=7350000000000000000\",\n    headers={\"x-api-key\": os.environ[\"SOCIALDATAKIT_API_KEY\"]},\n    timeout=30,\n)\nresponse.raise_for_status()\nresult = response.json()"}],"x-response-fields":{"id":{"type":"string","description":"Platform comment ID, retained as a string."},"content_id":{"type":"string","description":"Parent video/post ID when known."},"parent_comment_id":{"type":"string","description":"Top-level comment ID for a reply; null for a top-level comment or unknown parent."},"text":{"type":"string","description":"Public comment text. YouTube requests plainText formatting; no owner-only textOriginal."},"likes":{"type":"number","description":"Observed comment likes."},"reply_count":{"type":"number","description":"Observed total reply count; not the number of replies returned."},"author_id":{"type":"string","description":"Public author account ID."},"author_username":{"type":"string","description":"Public author handle."},"author_display_name":{"type":"string","description":"Public display name."},"author_avatar_url":{"type":"string","description":"Public avatar URL."},"author_profile_url":{"type":"string","description":"Public author profile URL."},"published_at":{"type":"string","description":"Comment publication timestamp."},"updated_at":{"type":"string","description":"Source edit timestamp when available."}}}},"/v2/instagram/user/posts":{"get":{"operationId":"instagram_v2_user_posts","summary":"Instagram user posts","description":"Get a public profile's posts, including reels. Preview: evaluate live availability and source coverage before customer use.","tags":["instagram"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"handle","in":"query","required":true,"schema":{"type":"string","pattern":"^@?[A-Za-z0-9._]{1,30}$","example":"natgeo"},"description":"Required instagram handle."},{"name":"cache_max_age","in":"query","required":false,"schema":{"type":"string","enum":["1d","3d","7d","14d","30d"]},"description":"Maximum acceptable cache age. Valid cache hits cost zero credits."},{"name":"fields","in":"query","required":false,"schema":{"type":"string","example":"items"},"description":"Comma-separated fields or dot paths, including inside arrays such as items.id. Response identity and pagination are retained."},{"name":"trim","in":"query","required":false,"schema":{"type":"boolean","default":false},"description":"Remove null and empty values. Meaningful empty YouTube region-restriction lists are retained."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":20,"default":3},"description":"Number of items to return."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"},"description":"Opaque pagination value returned as data.pagination.next_cursor. Keep the identifier, filters and limit unchanged."}],"responses":{"200":{"description":"Normalized resource","headers":{"x-request-id":{"schema":{"type":"string"}},"x-data-mode":{"schema":{"type":"string","enum":["live","sandbox"]}},"x-cache":{"schema":{"type":"string","enum":["HIT","MISS"]}},"x-credits-charged":{"schema":{"type":"integer"}},"x-credits-remaining":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"data":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","additionalProperties":true,"properties":{"id":{"type":["string","null"],"description":"Resource identifier used by this endpoint."},"author":{"type":["string","null"],"description":"Public creator name or handle."},"published_at":{"type":["string","null"],"description":"Source publication date or timestamp; null when absent."},"views":{"type":["number","null"],"description":"Observed views, where exposed by this source."},"likes":{"type":["number","null"],"description":"Observed likes."},"comments":{"type":["number","null"],"description":"Observed comment count, not comment rows."},"media_url":{"type":["string","null"],"description":"Preview image URL; not a guaranteed downloadable video."},"permalink":{"type":["string","null"],"description":"Public content URL."},"duration_seconds":{"type":["number","null"],"description":"Duration in seconds when returned."},"hashtags":{"type":["array","null"],"description":"Hashtags with platform or derived_text provenance.","items":{"type":["object","null"],"description":"Entity observed at source or derived from text.","properties":{"name":{"type":["string","null"],"description":"Hashtag or account name."},"id":{"type":["string","null"],"description":"Platform ID when supplied."},"source":{"type":["string","null"],"description":"platform or derived_text."}}}},"mentions":{"type":["array","null"],"description":"Mentions with platform or derived_text provenance; text is not proof of an account relationship.","items":{"type":["object","null"],"description":"Entity observed at source or derived from text.","properties":{"name":{"type":["string","null"],"description":"Hashtag or account name."},"id":{"type":["string","null"],"description":"Platform ID when supplied."},"source":{"type":["string","null"],"description":"platform or derived_text."}}}},"author_id":{"type":["string","null"],"description":"Stable creator ID when returned."},"author_display_name":{"type":["string","null"],"description":"Public display name."},"author_verified":{"type":["boolean","null"],"description":"Explicit creator verification state."},"author_avatar_url":{"type":["string","null"],"description":"Public creator avatar URL."},"platform_content_id":{"type":["string","null"],"description":"Platform media ID, separate from the shortcode."},"caption":{"type":["string","null"],"description":"Public caption."},"media_type":{"type":["string","null"],"description":"image, video, carousel, or null when unknown."},"media_product_type":{"type":["string","null"],"description":"Source product type, kept separate from media type."},"width":{"type":["number","null"],"description":"Media width in pixels."},"height":{"type":["number","null"],"description":"Media height in pixels."},"video_url":{"type":["string","null"],"description":"Source video URL where returned; may expire."},"comments_enabled":{"type":["boolean","null"],"description":"Observed comments setting."},"paid_partnership":{"type":["boolean","null"],"description":"Explicit source partnership flag; null when unavailable."},"accessibility_caption":{"type":["string","null"],"description":"Source alt text or accessibility description."},"location":{"type":["object","null"],"description":"Publicly attached location label.","properties":{"id":{"type":["string","null"],"description":"Location ID."},"name":{"type":["string","null"],"description":"Location name."},"slug":{"type":["string","null"],"description":"Location slug."}}},"tagged_users":{"type":["array","null"],"description":"Accounts explicitly tagged in the media.","items":{"type":["object","null"],"description":"Tagged account.","properties":{"id":{"type":["string","null"],"description":"Platform account ID."},"username":{"type":["string","null"],"description":"Handle."},"display_name":{"type":["string","null"],"description":"Display name."}}}},"media_assets":{"type":["array","null"],"description":"Returned image/video variants with dimensions.","items":{"type":["object","null"],"description":"One source media variant; URLs may expire.","properties":{"url":{"type":["string","null"],"description":"Source URL."},"width":{"type":["number","null"],"description":"Width in pixels."},"height":{"type":["number","null"],"description":"Height in pixels."},"asset_type":{"type":["string","null"],"description":"image, video, thumbnail or avatar."},"variant":{"type":["string","null"],"description":"Source variant when known."},"expires_at":{"type":["string","null"],"description":"Expiry timestamp when known."}}}},"children":{"type":["array","null"],"description":"Ordered carousel children when returned; null for non-carousels.","items":{"type":["object","null"],"description":"One carousel child.","properties":{"id":{"type":["string","null"],"description":"Media ID."},"position":{"type":["number","null"],"description":"Zero-based position."},"media_type":{"type":["string","null"],"description":"image, video or null."},"media_url":{"type":["string","null"],"description":"Preview image URL."},"video_url":{"type":["string","null"],"description":"Source video URL when available."},"width":{"type":["number","null"],"description":"Width in pixels."},"height":{"type":["number","null"],"description":"Height in pixels."}}}}}}}}}}}]}}}},"400":{"$ref":"#/components/responses/InvalidInput"},"401":{"$ref":"#/components/responses/InvalidApiKey"},"402":{"$ref":"#/components/responses/InsufficientCredits"},"403":{"$ref":"#/components/responses/SourceRestricted"},"404":{"$ref":"#/components/responses/ResourceNotFound"},"408":{"$ref":"#/components/responses/SourceTimeout"},"422":{"$ref":"#/components/responses/SourceResponseChanged"},"429":{"$ref":"#/components/responses/TemporaryCapacity"},"501":{"$ref":"#/components/responses/SourceNotImplemented"},"503":{"$ref":"#/components/responses/SourceUnavailable"}},"x-availability":"preview","x-identifier-one-of":["handle"],"x-credits":2,"x-source-access":"public_page","x-preview":true,"x-codeSamples":[{"lang":"curl","source":"curl 'https://api.socialdatakit.com/v2/instagram/user/posts?handle=natgeo' \\\n  -H 'x-api-key: YOUR_API_KEY'"},{"lang":"javascript","source":"const response = await fetch(\"https://api.socialdatakit.com/v2/instagram/user/posts?handle=natgeo\", {\n  headers: { \"x-api-key\": process.env.SOCIALDATAKIT_API_KEY }\n});\nif (!response.ok) throw new Error(await response.text());\nconst result = await response.json();"},{"lang":"python","source":"import os\nimport requests\n\nresponse = requests.get(\n    \"https://api.socialdatakit.com/v2/instagram/user/posts?handle=natgeo\",\n    headers={\"x-api-key\": os.environ[\"SOCIALDATAKIT_API_KEY\"]},\n    timeout=30,\n)\nresponse.raise_for_status()\nresult = response.json()"}],"x-response-fields":{"id":{"type":"string","description":"Resource identifier used by this endpoint."},"author":{"type":"string","description":"Public creator name or handle."},"published_at":{"type":"string","description":"Source publication date or timestamp; null when absent."},"views":{"type":"number","description":"Observed views, where exposed by this source."},"likes":{"type":"number","description":"Observed likes."},"comments":{"type":"number","description":"Observed comment count, not comment rows."},"media_url":{"type":"string","description":"Preview image URL; not a guaranteed downloadable video."},"permalink":{"type":"string","description":"Public content URL."},"duration_seconds":{"type":"number","description":"Duration in seconds when returned."},"hashtags":{"type":"array","description":"Hashtags with platform or derived_text provenance.","items":{"type":"object","description":"Entity observed at source or derived from text.","properties":{"name":{"type":"string","description":"Hashtag or account name."},"id":{"type":"string","description":"Platform ID when supplied."},"source":{"type":"string","description":"platform or derived_text."}}}},"mentions":{"type":"array","description":"Mentions with platform or derived_text provenance; text is not proof of an account relationship.","items":{"type":"object","description":"Entity observed at source or derived from text.","properties":{"name":{"type":"string","description":"Hashtag or account name."},"id":{"type":"string","description":"Platform ID when supplied."},"source":{"type":"string","description":"platform or derived_text."}}}},"author_id":{"type":"string","description":"Stable creator ID when returned."},"author_display_name":{"type":"string","description":"Public display name."},"author_verified":{"type":"boolean","description":"Explicit creator verification state."},"author_avatar_url":{"type":"string","description":"Public creator avatar URL."},"platform_content_id":{"type":"string","description":"Platform media ID, separate from the shortcode."},"caption":{"type":"string","description":"Public caption."},"media_type":{"type":"string","description":"image, video, carousel, or null when unknown."},"media_product_type":{"type":"string","description":"Source product type, kept separate from media type."},"width":{"type":"number","description":"Media width in pixels."},"height":{"type":"number","description":"Media height in pixels."},"video_url":{"type":"string","description":"Source video URL where returned; may expire."},"comments_enabled":{"type":"boolean","description":"Observed comments setting."},"paid_partnership":{"type":"boolean","description":"Explicit source partnership flag; null when unavailable."},"accessibility_caption":{"type":"string","description":"Source alt text or accessibility description."},"location":{"type":"object","description":"Publicly attached location label.","properties":{"id":{"type":"string","description":"Location ID."},"name":{"type":"string","description":"Location name."},"slug":{"type":"string","description":"Location slug."}}},"tagged_users":{"type":"array","description":"Accounts explicitly tagged in the media.","items":{"type":"object","description":"Tagged account.","properties":{"id":{"type":"string","description":"Platform account ID."},"username":{"type":"string","description":"Handle."},"display_name":{"type":"string","description":"Display name."}}}},"media_assets":{"type":"array","description":"Returned image/video variants with dimensions.","items":{"type":"object","description":"One source media variant; URLs may expire.","properties":{"url":{"type":"string","description":"Source URL."},"width":{"type":"number","description":"Width in pixels."},"height":{"type":"number","description":"Height in pixels."},"asset_type":{"type":"string","description":"image, video, thumbnail or avatar."},"variant":{"type":"string","description":"Source variant when known."},"expires_at":{"type":"string","description":"Expiry timestamp when known."}}}},"children":{"type":"array","description":"Ordered carousel children when returned; null for non-carousels.","items":{"type":"object","description":"One carousel child.","properties":{"id":{"type":"string","description":"Media ID."},"position":{"type":"number","description":"Zero-based position."},"media_type":{"type":"string","description":"image, video or null."},"media_url":{"type":"string","description":"Preview image URL."},"video_url":{"type":"string","description":"Source video URL when available."},"width":{"type":"number","description":"Width in pixels."},"height":{"type":"number","description":"Height in pixels."}}}}}}},"/v1/instagram/user/reels":{"get":{"operationId":"instagram_v1_user_reels","summary":"Instagram user reels","description":"Get the public reels exposed by the source for a profile. Live collection for this Instagram resource is unavailable while direct source access is being resolved. Profiles, visible profile posts, individual posts and carousel items are supported separately. Fresh production requests return 503 SOURCE_UNAVAILABLE without credit charges. Valid requested cache hits are free.","tags":["instagram"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"handle","in":"query","required":true,"schema":{"type":"string","pattern":"^@?[A-Za-z0-9._]{1,30}$","example":"natgeo"},"description":"Required instagram handle."},{"name":"cache_max_age","in":"query","required":false,"schema":{"type":"string","enum":["1d","3d","7d","14d","30d"]},"description":"Maximum acceptable cache age. Valid cache hits cost zero credits."},{"name":"fields","in":"query","required":false,"schema":{"type":"string","example":"items"},"description":"Comma-separated fields or dot paths, including inside arrays such as items.id. Response identity and pagination are retained."},{"name":"trim","in":"query","required":false,"schema":{"type":"boolean","default":false},"description":"Remove null and empty values. Meaningful empty YouTube region-restriction lists are retained."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":20,"default":3},"description":"Number of items to return."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"},"description":"Opaque pagination value returned as data.pagination.next_cursor. Keep the identifier, filters and limit unchanged."}],"responses":{"200":{"description":"Normalized resource","headers":{"x-request-id":{"schema":{"type":"string"}},"x-data-mode":{"schema":{"type":"string","enum":["live","sandbox"]}},"x-cache":{"schema":{"type":"string","enum":["HIT","MISS"]}},"x-credits-charged":{"schema":{"type":"integer"}},"x-credits-remaining":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"data":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","additionalProperties":true,"properties":{"id":{"type":["string","null"],"description":"Resource identifier used by this endpoint."},"author":{"type":["string","null"],"description":"Public creator name or handle."},"published_at":{"type":["string","null"],"description":"Source publication date or timestamp; null when absent."},"views":{"type":["number","null"],"description":"Observed views, where exposed by this source."},"likes":{"type":["number","null"],"description":"Observed likes."},"comments":{"type":["number","null"],"description":"Observed comment count, not comment rows."},"media_url":{"type":["string","null"],"description":"Preview image URL; not a guaranteed downloadable video."},"permalink":{"type":["string","null"],"description":"Public content URL."},"duration_seconds":{"type":["number","null"],"description":"Duration in seconds when returned."},"hashtags":{"type":["array","null"],"description":"Hashtags with platform or derived_text provenance.","items":{"type":["object","null"],"description":"Entity observed at source or derived from text.","properties":{"name":{"type":["string","null"],"description":"Hashtag or account name."},"id":{"type":["string","null"],"description":"Platform ID when supplied."},"source":{"type":["string","null"],"description":"platform or derived_text."}}}},"mentions":{"type":["array","null"],"description":"Mentions with platform or derived_text provenance; text is not proof of an account relationship.","items":{"type":["object","null"],"description":"Entity observed at source or derived from text.","properties":{"name":{"type":["string","null"],"description":"Hashtag or account name."},"id":{"type":["string","null"],"description":"Platform ID when supplied."},"source":{"type":["string","null"],"description":"platform or derived_text."}}}},"author_id":{"type":["string","null"],"description":"Stable creator ID when returned."},"author_display_name":{"type":["string","null"],"description":"Public display name."},"author_verified":{"type":["boolean","null"],"description":"Explicit creator verification state."},"author_avatar_url":{"type":["string","null"],"description":"Public creator avatar URL."},"platform_content_id":{"type":["string","null"],"description":"Platform media ID, separate from the shortcode."},"caption":{"type":["string","null"],"description":"Public caption."},"media_type":{"type":["string","null"],"description":"image, video, carousel, or null when unknown."},"media_product_type":{"type":["string","null"],"description":"Source product type, kept separate from media type."},"width":{"type":["number","null"],"description":"Media width in pixels."},"height":{"type":["number","null"],"description":"Media height in pixels."},"video_url":{"type":["string","null"],"description":"Source video URL where returned; may expire."},"comments_enabled":{"type":["boolean","null"],"description":"Observed comments setting."},"paid_partnership":{"type":["boolean","null"],"description":"Explicit source partnership flag; null when unavailable."},"accessibility_caption":{"type":["string","null"],"description":"Source alt text or accessibility description."},"location":{"type":["object","null"],"description":"Publicly attached location label.","properties":{"id":{"type":["string","null"],"description":"Location ID."},"name":{"type":["string","null"],"description":"Location name."},"slug":{"type":["string","null"],"description":"Location slug."}}},"tagged_users":{"type":["array","null"],"description":"Accounts explicitly tagged in the media.","items":{"type":["object","null"],"description":"Tagged account.","properties":{"id":{"type":["string","null"],"description":"Platform account ID."},"username":{"type":["string","null"],"description":"Handle."},"display_name":{"type":["string","null"],"description":"Display name."}}}},"media_assets":{"type":["array","null"],"description":"Returned image/video variants with dimensions.","items":{"type":["object","null"],"description":"One source media variant; URLs may expire.","properties":{"url":{"type":["string","null"],"description":"Source URL."},"width":{"type":["number","null"],"description":"Width in pixels."},"height":{"type":["number","null"],"description":"Height in pixels."},"asset_type":{"type":["string","null"],"description":"image, video, thumbnail or avatar."},"variant":{"type":["string","null"],"description":"Source variant when known."},"expires_at":{"type":["string","null"],"description":"Expiry timestamp when known."}}}},"children":{"type":["array","null"],"description":"Ordered carousel children when returned; null for non-carousels.","items":{"type":["object","null"],"description":"One carousel child.","properties":{"id":{"type":["string","null"],"description":"Media ID."},"position":{"type":["number","null"],"description":"Zero-based position."},"media_type":{"type":["string","null"],"description":"image, video or null."},"media_url":{"type":["string","null"],"description":"Preview image URL."},"video_url":{"type":["string","null"],"description":"Source video URL when available."},"width":{"type":["number","null"],"description":"Width in pixels."},"height":{"type":["number","null"],"description":"Height in pixels."}}}}}}}}}}}]}}}},"400":{"$ref":"#/components/responses/InvalidInput"},"401":{"$ref":"#/components/responses/InvalidApiKey"},"402":{"$ref":"#/components/responses/InsufficientCredits"},"403":{"$ref":"#/components/responses/SourceRestricted"},"404":{"$ref":"#/components/responses/ResourceNotFound"},"408":{"$ref":"#/components/responses/SourceTimeout"},"422":{"$ref":"#/components/responses/SourceResponseChanged"},"429":{"$ref":"#/components/responses/TemporaryCapacity"},"501":{"$ref":"#/components/responses/SourceNotImplemented"},"503":{"$ref":"#/components/responses/SourceUnavailable"}},"x-availability":"unavailable","x-identifier-one-of":["handle"],"x-credits":2,"x-source-access":"public_page","x-preview":true,"x-codeSamples":[{"lang":"curl","source":"curl 'https://api.socialdatakit.com/v1/instagram/user/reels?handle=natgeo' \\\n  -H 'x-api-key: YOUR_API_KEY'"},{"lang":"javascript","source":"const response = await fetch(\"https://api.socialdatakit.com/v1/instagram/user/reels?handle=natgeo\", {\n  headers: { \"x-api-key\": process.env.SOCIALDATAKIT_API_KEY }\n});\nif (!response.ok) throw new Error(await response.text());\nconst result = await response.json();"},{"lang":"python","source":"import os\nimport requests\n\nresponse = requests.get(\n    \"https://api.socialdatakit.com/v1/instagram/user/reels?handle=natgeo\",\n    headers={\"x-api-key\": os.environ[\"SOCIALDATAKIT_API_KEY\"]},\n    timeout=30,\n)\nresponse.raise_for_status()\nresult = response.json()"}],"x-response-fields":{"id":{"type":"string","description":"Resource identifier used by this endpoint."},"author":{"type":"string","description":"Public creator name or handle."},"published_at":{"type":"string","description":"Source publication date or timestamp; null when absent."},"views":{"type":"number","description":"Observed views, where exposed by this source."},"likes":{"type":"number","description":"Observed likes."},"comments":{"type":"number","description":"Observed comment count, not comment rows."},"media_url":{"type":"string","description":"Preview image URL; not a guaranteed downloadable video."},"permalink":{"type":"string","description":"Public content URL."},"duration_seconds":{"type":"number","description":"Duration in seconds when returned."},"hashtags":{"type":"array","description":"Hashtags with platform or derived_text provenance.","items":{"type":"object","description":"Entity observed at source or derived from text.","properties":{"name":{"type":"string","description":"Hashtag or account name."},"id":{"type":"string","description":"Platform ID when supplied."},"source":{"type":"string","description":"platform or derived_text."}}}},"mentions":{"type":"array","description":"Mentions with platform or derived_text provenance; text is not proof of an account relationship.","items":{"type":"object","description":"Entity observed at source or derived from text.","properties":{"name":{"type":"string","description":"Hashtag or account name."},"id":{"type":"string","description":"Platform ID when supplied."},"source":{"type":"string","description":"platform or derived_text."}}}},"author_id":{"type":"string","description":"Stable creator ID when returned."},"author_display_name":{"type":"string","description":"Public display name."},"author_verified":{"type":"boolean","description":"Explicit creator verification state."},"author_avatar_url":{"type":"string","description":"Public creator avatar URL."},"platform_content_id":{"type":"string","description":"Platform media ID, separate from the shortcode."},"caption":{"type":"string","description":"Public caption."},"media_type":{"type":"string","description":"image, video, carousel, or null when unknown."},"media_product_type":{"type":"string","description":"Source product type, kept separate from media type."},"width":{"type":"number","description":"Media width in pixels."},"height":{"type":"number","description":"Media height in pixels."},"video_url":{"type":"string","description":"Source video URL where returned; may expire."},"comments_enabled":{"type":"boolean","description":"Observed comments setting."},"paid_partnership":{"type":"boolean","description":"Explicit source partnership flag; null when unavailable."},"accessibility_caption":{"type":"string","description":"Source alt text or accessibility description."},"location":{"type":"object","description":"Publicly attached location label.","properties":{"id":{"type":"string","description":"Location ID."},"name":{"type":"string","description":"Location name."},"slug":{"type":"string","description":"Location slug."}}},"tagged_users":{"type":"array","description":"Accounts explicitly tagged in the media.","items":{"type":"object","description":"Tagged account.","properties":{"id":{"type":"string","description":"Platform account ID."},"username":{"type":"string","description":"Handle."},"display_name":{"type":"string","description":"Display name."}}}},"media_assets":{"type":"array","description":"Returned image/video variants with dimensions.","items":{"type":"object","description":"One source media variant; URLs may expire.","properties":{"url":{"type":"string","description":"Source URL."},"width":{"type":"number","description":"Width in pixels."},"height":{"type":"number","description":"Height in pixels."},"asset_type":{"type":"string","description":"image, video, thumbnail or avatar."},"variant":{"type":"string","description":"Source variant when known."},"expires_at":{"type":"string","description":"Expiry timestamp when known."}}}},"children":{"type":"array","description":"Ordered carousel children when returned; null for non-carousels.","items":{"type":"object","description":"One carousel child.","properties":{"id":{"type":"string","description":"Media ID."},"position":{"type":"number","description":"Zero-based position."},"media_type":{"type":"string","description":"image, video or null."},"media_url":{"type":"string","description":"Preview image URL."},"video_url":{"type":"string","description":"Source video URL when available."},"width":{"type":"number","description":"Width in pixels."},"height":{"type":"number","description":"Height in pixels."}}}}}}},"/v2/instagram/post/comments":{"get":{"operationId":"instagram_v2_post_comments","summary":"Instagram post comments","description":"Get comments from a public post or reel. Live collection for this Instagram resource is unavailable while direct source access is being resolved. Profiles, visible profile posts, individual posts and carousel items are supported separately. Fresh production requests return 503 SOURCE_UNAVAILABLE without credit charges. Valid requested cache hits are free.","tags":["instagram"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"url","in":"query","required":true,"schema":{"type":"string","pattern":"^https?://[^\\s]{5,400}$","example":"https://www.instagram.com/p/CxDemo123/"},"description":"Required instagram url."},{"name":"cache_max_age","in":"query","required":false,"schema":{"type":"string","enum":["1d","3d","7d","14d","30d"]},"description":"Maximum acceptable cache age. Valid cache hits cost zero credits."},{"name":"fields","in":"query","required":false,"schema":{"type":"string","example":"items"},"description":"Comma-separated fields or dot paths, including inside arrays such as items.id. Response identity and pagination are retained."},{"name":"trim","in":"query","required":false,"schema":{"type":"boolean","default":false},"description":"Remove null and empty values. Meaningful empty YouTube region-restriction lists are retained."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":20,"default":3},"description":"Number of items to return."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"},"description":"Opaque pagination value returned as data.pagination.next_cursor. Keep the identifier, filters and limit unchanged."}],"responses":{"200":{"description":"Normalized resource","headers":{"x-request-id":{"schema":{"type":"string"}},"x-data-mode":{"schema":{"type":"string","enum":["live","sandbox"]}},"x-cache":{"schema":{"type":"string","enum":["HIT","MISS"]}},"x-credits-charged":{"schema":{"type":"integer"}},"x-credits-remaining":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"data":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","additionalProperties":true,"properties":{"id":{"type":["string","null"],"description":"Platform comment ID, retained as a string."},"content_id":{"type":["string","null"],"description":"Parent video/post ID when known."},"parent_comment_id":{"type":["string","null"],"description":"Top-level comment ID for a reply; null for a top-level comment or unknown parent."},"text":{"type":["string","null"],"description":"Public comment text. YouTube requests plainText formatting; no owner-only textOriginal."},"likes":{"type":["number","null"],"description":"Observed comment likes."},"reply_count":{"type":["number","null"],"description":"Observed total reply count; not the number of replies returned."},"author_id":{"type":["string","null"],"description":"Public author account ID."},"author_username":{"type":["string","null"],"description":"Public author handle."},"author_display_name":{"type":["string","null"],"description":"Public display name."},"author_avatar_url":{"type":["string","null"],"description":"Public avatar URL."},"author_profile_url":{"type":["string","null"],"description":"Public author profile URL."},"published_at":{"type":["string","null"],"description":"Comment publication timestamp."},"updated_at":{"type":["string","null"],"description":"Source edit timestamp when available."}}}}}}}}]}}}},"400":{"$ref":"#/components/responses/InvalidInput"},"401":{"$ref":"#/components/responses/InvalidApiKey"},"402":{"$ref":"#/components/responses/InsufficientCredits"},"403":{"$ref":"#/components/responses/SourceRestricted"},"404":{"$ref":"#/components/responses/ResourceNotFound"},"408":{"$ref":"#/components/responses/SourceTimeout"},"422":{"$ref":"#/components/responses/SourceResponseChanged"},"429":{"$ref":"#/components/responses/TemporaryCapacity"},"501":{"$ref":"#/components/responses/SourceNotImplemented"},"503":{"$ref":"#/components/responses/SourceUnavailable"}},"x-availability":"unavailable","x-identifier-one-of":["url"],"x-credits":2,"x-source-access":"public_page","x-preview":true,"x-codeSamples":[{"lang":"curl","source":"curl 'https://api.socialdatakit.com/v2/instagram/post/comments?url=https%3A%2F%2Fwww.instagram.com%2Fp%2FCxDemo123%2F' \\\n  -H 'x-api-key: YOUR_API_KEY'"},{"lang":"javascript","source":"const response = await fetch(\"https://api.socialdatakit.com/v2/instagram/post/comments?url=https%3A%2F%2Fwww.instagram.com%2Fp%2FCxDemo123%2F\", {\n  headers: { \"x-api-key\": process.env.SOCIALDATAKIT_API_KEY }\n});\nif (!response.ok) throw new Error(await response.text());\nconst result = await response.json();"},{"lang":"python","source":"import os\nimport requests\n\nresponse = requests.get(\n    \"https://api.socialdatakit.com/v2/instagram/post/comments?url=https%3A%2F%2Fwww.instagram.com%2Fp%2FCxDemo123%2F\",\n    headers={\"x-api-key\": os.environ[\"SOCIALDATAKIT_API_KEY\"]},\n    timeout=30,\n)\nresponse.raise_for_status()\nresult = response.json()"}],"x-response-fields":{"id":{"type":"string","description":"Platform comment ID, retained as a string."},"content_id":{"type":"string","description":"Parent video/post ID when known."},"parent_comment_id":{"type":"string","description":"Top-level comment ID for a reply; null for a top-level comment or unknown parent."},"text":{"type":"string","description":"Public comment text. YouTube requests plainText formatting; no owner-only textOriginal."},"likes":{"type":"number","description":"Observed comment likes."},"reply_count":{"type":"number","description":"Observed total reply count; not the number of replies returned."},"author_id":{"type":"string","description":"Public author account ID."},"author_username":{"type":"string","description":"Public author handle."},"author_display_name":{"type":"string","description":"Public display name."},"author_avatar_url":{"type":"string","description":"Public avatar URL."},"author_profile_url":{"type":"string","description":"Public author profile URL."},"published_at":{"type":"string","description":"Comment publication timestamp."},"updated_at":{"type":"string","description":"Source edit timestamp when available."}}}},"/v1/instagram/user/highlights":{"get":{"operationId":"instagram_v1_user_highlights","summary":"Instagram highlights","description":"Get a public profile's story highlight covers. Planned: returns 501 SOURCE_NOT_IMPLEMENTED; no collector or sample response is available and no credits are charged.","tags":["instagram"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"handle","in":"query","required":true,"schema":{"type":"string","pattern":"^@?[A-Za-z0-9._]{1,30}$","example":"natgeo"},"description":"Required instagram handle."},{"name":"cache_max_age","in":"query","required":false,"schema":{"type":"string","enum":["1d","3d","7d","14d","30d"]},"description":"Maximum acceptable cache age. Valid cache hits cost zero credits."},{"name":"fields","in":"query","required":false,"schema":{"type":"string","example":"item"},"description":"Comma-separated fields or dot paths, including inside arrays such as items.id. Response identity and pagination are retained."},{"name":"trim","in":"query","required":false,"schema":{"type":"boolean","default":false},"description":"Remove null and empty values. Meaningful empty YouTube region-restriction lists are retained."}],"responses":{"200":{"description":"Normalized resource","headers":{"x-request-id":{"schema":{"type":"string"}},"x-data-mode":{"schema":{"type":"string","enum":["live","sandbox"]}},"x-cache":{"schema":{"type":"string","enum":["HIT","MISS"]}},"x-credits-charged":{"schema":{"type":"integer"}},"x-credits-remaining":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"data":{"type":"object","properties":{"item":{"type":"object","additionalProperties":true,"properties":{"id":{"type":["string","null"],"description":"Resource identifier used by this endpoint."},"author":{"type":["string","null"],"description":"Public creator name or handle."},"published_at":{"type":["string","null"],"description":"Source publication date or timestamp; null when absent."},"views":{"type":["number","null"],"description":"Observed views, where exposed by this source."},"likes":{"type":["number","null"],"description":"Observed likes."},"comments":{"type":["number","null"],"description":"Observed comment count, not comment rows."},"media_url":{"type":["string","null"],"description":"Preview image URL; not a guaranteed downloadable video."},"permalink":{"type":["string","null"],"description":"Public content URL."},"duration_seconds":{"type":["number","null"],"description":"Duration in seconds when returned."},"hashtags":{"type":["array","null"],"description":"Hashtags with platform or derived_text provenance.","items":{"type":["object","null"],"description":"Entity observed at source or derived from text.","properties":{"name":{"type":["string","null"],"description":"Hashtag or account name."},"id":{"type":["string","null"],"description":"Platform ID when supplied."},"source":{"type":["string","null"],"description":"platform or derived_text."}}}},"mentions":{"type":["array","null"],"description":"Mentions with platform or derived_text provenance; text is not proof of an account relationship.","items":{"type":["object","null"],"description":"Entity observed at source or derived from text.","properties":{"name":{"type":["string","null"],"description":"Hashtag or account name."},"id":{"type":["string","null"],"description":"Platform ID when supplied."},"source":{"type":["string","null"],"description":"platform or derived_text."}}}},"author_id":{"type":["string","null"],"description":"Stable creator ID when returned."},"author_display_name":{"type":["string","null"],"description":"Public display name."},"author_verified":{"type":["boolean","null"],"description":"Explicit creator verification state."},"author_avatar_url":{"type":["string","null"],"description":"Public creator avatar URL."},"platform_content_id":{"type":["string","null"],"description":"Platform media ID, separate from the shortcode."},"caption":{"type":["string","null"],"description":"Public caption."},"media_type":{"type":["string","null"],"description":"image, video, carousel, or null when unknown."},"media_product_type":{"type":["string","null"],"description":"Source product type, kept separate from media type."},"width":{"type":["number","null"],"description":"Media width in pixels."},"height":{"type":["number","null"],"description":"Media height in pixels."},"video_url":{"type":["string","null"],"description":"Source video URL where returned; may expire."},"comments_enabled":{"type":["boolean","null"],"description":"Observed comments setting."},"paid_partnership":{"type":["boolean","null"],"description":"Explicit source partnership flag; null when unavailable."},"accessibility_caption":{"type":["string","null"],"description":"Source alt text or accessibility description."},"location":{"type":["object","null"],"description":"Publicly attached location label.","properties":{"id":{"type":["string","null"],"description":"Location ID."},"name":{"type":["string","null"],"description":"Location name."},"slug":{"type":["string","null"],"description":"Location slug."}}},"tagged_users":{"type":["array","null"],"description":"Accounts explicitly tagged in the media.","items":{"type":["object","null"],"description":"Tagged account.","properties":{"id":{"type":["string","null"],"description":"Platform account ID."},"username":{"type":["string","null"],"description":"Handle."},"display_name":{"type":["string","null"],"description":"Display name."}}}},"media_assets":{"type":["array","null"],"description":"Returned image/video variants with dimensions.","items":{"type":["object","null"],"description":"One source media variant; URLs may expire.","properties":{"url":{"type":["string","null"],"description":"Source URL."},"width":{"type":["number","null"],"description":"Width in pixels."},"height":{"type":["number","null"],"description":"Height in pixels."},"asset_type":{"type":["string","null"],"description":"image, video, thumbnail or avatar."},"variant":{"type":["string","null"],"description":"Source variant when known."},"expires_at":{"type":["string","null"],"description":"Expiry timestamp when known."}}}},"children":{"type":["array","null"],"description":"Ordered carousel children when returned; null for non-carousels.","items":{"type":["object","null"],"description":"One carousel child.","properties":{"id":{"type":["string","null"],"description":"Media ID."},"position":{"type":["number","null"],"description":"Zero-based position."},"media_type":{"type":["string","null"],"description":"image, video or null."},"media_url":{"type":["string","null"],"description":"Preview image URL."},"video_url":{"type":["string","null"],"description":"Source video URL when available."},"width":{"type":["number","null"],"description":"Width in pixels."},"height":{"type":["number","null"],"description":"Height in pixels."}}}}}}}}}}]}}}},"400":{"$ref":"#/components/responses/InvalidInput"},"401":{"$ref":"#/components/responses/InvalidApiKey"},"402":{"$ref":"#/components/responses/InsufficientCredits"},"403":{"$ref":"#/components/responses/SourceRestricted"},"404":{"$ref":"#/components/responses/ResourceNotFound"},"408":{"$ref":"#/components/responses/SourceTimeout"},"422":{"$ref":"#/components/responses/SourceResponseChanged"},"429":{"$ref":"#/components/responses/TemporaryCapacity"},"501":{"$ref":"#/components/responses/SourceNotImplemented"},"503":{"$ref":"#/components/responses/SourceUnavailable"}},"x-availability":"planned","x-identifier-one-of":["handle"],"x-credits":1,"x-source-access":"public_page","x-preview":true,"x-codeSamples":[{"lang":"curl","source":"curl 'https://api.socialdatakit.com/v1/instagram/user/highlights?handle=natgeo' \\\n  -H 'x-api-key: YOUR_API_KEY'"},{"lang":"javascript","source":"const response = await fetch(\"https://api.socialdatakit.com/v1/instagram/user/highlights?handle=natgeo\", {\n  headers: { \"x-api-key\": process.env.SOCIALDATAKIT_API_KEY }\n});\nif (!response.ok) throw new Error(await response.text());\nconst result = await response.json();"},{"lang":"python","source":"import os\nimport requests\n\nresponse = requests.get(\n    \"https://api.socialdatakit.com/v1/instagram/user/highlights?handle=natgeo\",\n    headers={\"x-api-key\": os.environ[\"SOCIALDATAKIT_API_KEY\"]},\n    timeout=30,\n)\nresponse.raise_for_status()\nresult = response.json()"}],"x-response-fields":{"id":{"type":"string","description":"Resource identifier used by this endpoint."},"author":{"type":"string","description":"Public creator name or handle."},"published_at":{"type":"string","description":"Source publication date or timestamp; null when absent."},"views":{"type":"number","description":"Observed views, where exposed by this source."},"likes":{"type":"number","description":"Observed likes."},"comments":{"type":"number","description":"Observed comment count, not comment rows."},"media_url":{"type":"string","description":"Preview image URL; not a guaranteed downloadable video."},"permalink":{"type":"string","description":"Public content URL."},"duration_seconds":{"type":"number","description":"Duration in seconds when returned."},"hashtags":{"type":"array","description":"Hashtags with platform or derived_text provenance.","items":{"type":"object","description":"Entity observed at source or derived from text.","properties":{"name":{"type":"string","description":"Hashtag or account name."},"id":{"type":"string","description":"Platform ID when supplied."},"source":{"type":"string","description":"platform or derived_text."}}}},"mentions":{"type":"array","description":"Mentions with platform or derived_text provenance; text is not proof of an account relationship.","items":{"type":"object","description":"Entity observed at source or derived from text.","properties":{"name":{"type":"string","description":"Hashtag or account name."},"id":{"type":"string","description":"Platform ID when supplied."},"source":{"type":"string","description":"platform or derived_text."}}}},"author_id":{"type":"string","description":"Stable creator ID when returned."},"author_display_name":{"type":"string","description":"Public display name."},"author_verified":{"type":"boolean","description":"Explicit creator verification state."},"author_avatar_url":{"type":"string","description":"Public creator avatar URL."},"platform_content_id":{"type":"string","description":"Platform media ID, separate from the shortcode."},"caption":{"type":"string","description":"Public caption."},"media_type":{"type":"string","description":"image, video, carousel, or null when unknown."},"media_product_type":{"type":"string","description":"Source product type, kept separate from media type."},"width":{"type":"number","description":"Media width in pixels."},"height":{"type":"number","description":"Media height in pixels."},"video_url":{"type":"string","description":"Source video URL where returned; may expire."},"comments_enabled":{"type":"boolean","description":"Observed comments setting."},"paid_partnership":{"type":"boolean","description":"Explicit source partnership flag; null when unavailable."},"accessibility_caption":{"type":"string","description":"Source alt text or accessibility description."},"location":{"type":"object","description":"Publicly attached location label.","properties":{"id":{"type":"string","description":"Location ID."},"name":{"type":"string","description":"Location name."},"slug":{"type":"string","description":"Location slug."}}},"tagged_users":{"type":"array","description":"Accounts explicitly tagged in the media.","items":{"type":"object","description":"Tagged account.","properties":{"id":{"type":"string","description":"Platform account ID."},"username":{"type":"string","description":"Handle."},"display_name":{"type":"string","description":"Display name."}}}},"media_assets":{"type":"array","description":"Returned image/video variants with dimensions.","items":{"type":"object","description":"One source media variant; URLs may expire.","properties":{"url":{"type":"string","description":"Source URL."},"width":{"type":"number","description":"Width in pixels."},"height":{"type":"number","description":"Height in pixels."},"asset_type":{"type":"string","description":"image, video, thumbnail or avatar."},"variant":{"type":"string","description":"Source variant when known."},"expires_at":{"type":"string","description":"Expiry timestamp when known."}}}},"children":{"type":"array","description":"Ordered carousel children when returned; null for non-carousels.","items":{"type":"object","description":"One carousel child.","properties":{"id":{"type":"string","description":"Media ID."},"position":{"type":"number","description":"Zero-based position."},"media_type":{"type":"string","description":"image, video or null."},"media_url":{"type":"string","description":"Preview image URL."},"video_url":{"type":"string","description":"Source video URL when available."},"width":{"type":"number","description":"Width in pixels."},"height":{"type":"number","description":"Height in pixels."}}}}}}},"/v1/instagram/user/highlight/detail":{"get":{"operationId":"instagram_v1_user_highlight_detail","summary":"Instagram highlight detail","description":"Get the items inside a public story highlight. Planned: returns 501 SOURCE_NOT_IMPLEMENTED; no collector or sample response is available and no credits are charged.","tags":["instagram"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"id","in":"query","required":true,"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{5,32}$","example":"17912345678901234"},"description":"Required instagram id."},{"name":"cache_max_age","in":"query","required":false,"schema":{"type":"string","enum":["1d","3d","7d","14d","30d"]},"description":"Maximum acceptable cache age. Valid cache hits cost zero credits."},{"name":"fields","in":"query","required":false,"schema":{"type":"string","example":"item"},"description":"Comma-separated fields or dot paths, including inside arrays such as items.id. Response identity and pagination are retained."},{"name":"trim","in":"query","required":false,"schema":{"type":"boolean","default":false},"description":"Remove null and empty values. Meaningful empty YouTube region-restriction lists are retained."}],"responses":{"200":{"description":"Normalized resource","headers":{"x-request-id":{"schema":{"type":"string"}},"x-data-mode":{"schema":{"type":"string","enum":["live","sandbox"]}},"x-cache":{"schema":{"type":"string","enum":["HIT","MISS"]}},"x-credits-charged":{"schema":{"type":"integer"}},"x-credits-remaining":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"data":{"type":"object","properties":{"item":{"type":"object","additionalProperties":true,"properties":{"id":{"type":["string","null"],"description":"Resource identifier used by this endpoint."},"author":{"type":["string","null"],"description":"Public creator name or handle."},"published_at":{"type":["string","null"],"description":"Source publication date or timestamp; null when absent."},"views":{"type":["number","null"],"description":"Observed views, where exposed by this source."},"likes":{"type":["number","null"],"description":"Observed likes."},"comments":{"type":["number","null"],"description":"Observed comment count, not comment rows."},"media_url":{"type":["string","null"],"description":"Preview image URL; not a guaranteed downloadable video."},"permalink":{"type":["string","null"],"description":"Public content URL."},"duration_seconds":{"type":["number","null"],"description":"Duration in seconds when returned."},"hashtags":{"type":["array","null"],"description":"Hashtags with platform or derived_text provenance.","items":{"type":["object","null"],"description":"Entity observed at source or derived from text.","properties":{"name":{"type":["string","null"],"description":"Hashtag or account name."},"id":{"type":["string","null"],"description":"Platform ID when supplied."},"source":{"type":["string","null"],"description":"platform or derived_text."}}}},"mentions":{"type":["array","null"],"description":"Mentions with platform or derived_text provenance; text is not proof of an account relationship.","items":{"type":["object","null"],"description":"Entity observed at source or derived from text.","properties":{"name":{"type":["string","null"],"description":"Hashtag or account name."},"id":{"type":["string","null"],"description":"Platform ID when supplied."},"source":{"type":["string","null"],"description":"platform or derived_text."}}}},"author_id":{"type":["string","null"],"description":"Stable creator ID when returned."},"author_display_name":{"type":["string","null"],"description":"Public display name."},"author_verified":{"type":["boolean","null"],"description":"Explicit creator verification state."},"author_avatar_url":{"type":["string","null"],"description":"Public creator avatar URL."},"platform_content_id":{"type":["string","null"],"description":"Platform media ID, separate from the shortcode."},"caption":{"type":["string","null"],"description":"Public caption."},"media_type":{"type":["string","null"],"description":"image, video, carousel, or null when unknown."},"media_product_type":{"type":["string","null"],"description":"Source product type, kept separate from media type."},"width":{"type":["number","null"],"description":"Media width in pixels."},"height":{"type":["number","null"],"description":"Media height in pixels."},"video_url":{"type":["string","null"],"description":"Source video URL where returned; may expire."},"comments_enabled":{"type":["boolean","null"],"description":"Observed comments setting."},"paid_partnership":{"type":["boolean","null"],"description":"Explicit source partnership flag; null when unavailable."},"accessibility_caption":{"type":["string","null"],"description":"Source alt text or accessibility description."},"location":{"type":["object","null"],"description":"Publicly attached location label.","properties":{"id":{"type":["string","null"],"description":"Location ID."},"name":{"type":["string","null"],"description":"Location name."},"slug":{"type":["string","null"],"description":"Location slug."}}},"tagged_users":{"type":["array","null"],"description":"Accounts explicitly tagged in the media.","items":{"type":["object","null"],"description":"Tagged account.","properties":{"id":{"type":["string","null"],"description":"Platform account ID."},"username":{"type":["string","null"],"description":"Handle."},"display_name":{"type":["string","null"],"description":"Display name."}}}},"media_assets":{"type":["array","null"],"description":"Returned image/video variants with dimensions.","items":{"type":["object","null"],"description":"One source media variant; URLs may expire.","properties":{"url":{"type":["string","null"],"description":"Source URL."},"width":{"type":["number","null"],"description":"Width in pixels."},"height":{"type":["number","null"],"description":"Height in pixels."},"asset_type":{"type":["string","null"],"description":"image, video, thumbnail or avatar."},"variant":{"type":["string","null"],"description":"Source variant when known."},"expires_at":{"type":["string","null"],"description":"Expiry timestamp when known."}}}},"children":{"type":["array","null"],"description":"Ordered carousel children when returned; null for non-carousels.","items":{"type":["object","null"],"description":"One carousel child.","properties":{"id":{"type":["string","null"],"description":"Media ID."},"position":{"type":["number","null"],"description":"Zero-based position."},"media_type":{"type":["string","null"],"description":"image, video or null."},"media_url":{"type":["string","null"],"description":"Preview image URL."},"video_url":{"type":["string","null"],"description":"Source video URL when available."},"width":{"type":["number","null"],"description":"Width in pixels."},"height":{"type":["number","null"],"description":"Height in pixels."}}}}}}}}}}]}}}},"400":{"$ref":"#/components/responses/InvalidInput"},"401":{"$ref":"#/components/responses/InvalidApiKey"},"402":{"$ref":"#/components/responses/InsufficientCredits"},"403":{"$ref":"#/components/responses/SourceRestricted"},"404":{"$ref":"#/components/responses/ResourceNotFound"},"408":{"$ref":"#/components/responses/SourceTimeout"},"422":{"$ref":"#/components/responses/SourceResponseChanged"},"429":{"$ref":"#/components/responses/TemporaryCapacity"},"501":{"$ref":"#/components/responses/SourceNotImplemented"},"503":{"$ref":"#/components/responses/SourceUnavailable"}},"x-availability":"planned","x-identifier-one-of":["id"],"x-credits":1,"x-source-access":"public_page","x-preview":true,"x-codeSamples":[{"lang":"curl","source":"curl 'https://api.socialdatakit.com/v1/instagram/user/highlight/detail?id=17912345678901234' \\\n  -H 'x-api-key: YOUR_API_KEY'"},{"lang":"javascript","source":"const response = await fetch(\"https://api.socialdatakit.com/v1/instagram/user/highlight/detail?id=17912345678901234\", {\n  headers: { \"x-api-key\": process.env.SOCIALDATAKIT_API_KEY }\n});\nif (!response.ok) throw new Error(await response.text());\nconst result = await response.json();"},{"lang":"python","source":"import os\nimport requests\n\nresponse = requests.get(\n    \"https://api.socialdatakit.com/v1/instagram/user/highlight/detail?id=17912345678901234\",\n    headers={\"x-api-key\": os.environ[\"SOCIALDATAKIT_API_KEY\"]},\n    timeout=30,\n)\nresponse.raise_for_status()\nresult = response.json()"}],"x-response-fields":{"id":{"type":"string","description":"Resource identifier used by this endpoint."},"author":{"type":"string","description":"Public creator name or handle."},"published_at":{"type":"string","description":"Source publication date or timestamp; null when absent."},"views":{"type":"number","description":"Observed views, where exposed by this source."},"likes":{"type":"number","description":"Observed likes."},"comments":{"type":"number","description":"Observed comment count, not comment rows."},"media_url":{"type":"string","description":"Preview image URL; not a guaranteed downloadable video."},"permalink":{"type":"string","description":"Public content URL."},"duration_seconds":{"type":"number","description":"Duration in seconds when returned."},"hashtags":{"type":"array","description":"Hashtags with platform or derived_text provenance.","items":{"type":"object","description":"Entity observed at source or derived from text.","properties":{"name":{"type":"string","description":"Hashtag or account name."},"id":{"type":"string","description":"Platform ID when supplied."},"source":{"type":"string","description":"platform or derived_text."}}}},"mentions":{"type":"array","description":"Mentions with platform or derived_text provenance; text is not proof of an account relationship.","items":{"type":"object","description":"Entity observed at source or derived from text.","properties":{"name":{"type":"string","description":"Hashtag or account name."},"id":{"type":"string","description":"Platform ID when supplied."},"source":{"type":"string","description":"platform or derived_text."}}}},"author_id":{"type":"string","description":"Stable creator ID when returned."},"author_display_name":{"type":"string","description":"Public display name."},"author_verified":{"type":"boolean","description":"Explicit creator verification state."},"author_avatar_url":{"type":"string","description":"Public creator avatar URL."},"platform_content_id":{"type":"string","description":"Platform media ID, separate from the shortcode."},"caption":{"type":"string","description":"Public caption."},"media_type":{"type":"string","description":"image, video, carousel, or null when unknown."},"media_product_type":{"type":"string","description":"Source product type, kept separate from media type."},"width":{"type":"number","description":"Media width in pixels."},"height":{"type":"number","description":"Media height in pixels."},"video_url":{"type":"string","description":"Source video URL where returned; may expire."},"comments_enabled":{"type":"boolean","description":"Observed comments setting."},"paid_partnership":{"type":"boolean","description":"Explicit source partnership flag; null when unavailable."},"accessibility_caption":{"type":"string","description":"Source alt text or accessibility description."},"location":{"type":"object","description":"Publicly attached location label.","properties":{"id":{"type":"string","description":"Location ID."},"name":{"type":"string","description":"Location name."},"slug":{"type":"string","description":"Location slug."}}},"tagged_users":{"type":"array","description":"Accounts explicitly tagged in the media.","items":{"type":"object","description":"Tagged account.","properties":{"id":{"type":"string","description":"Platform account ID."},"username":{"type":"string","description":"Handle."},"display_name":{"type":"string","description":"Display name."}}}},"media_assets":{"type":"array","description":"Returned image/video variants with dimensions.","items":{"type":"object","description":"One source media variant; URLs may expire.","properties":{"url":{"type":"string","description":"Source URL."},"width":{"type":"number","description":"Width in pixels."},"height":{"type":"number","description":"Height in pixels."},"asset_type":{"type":"string","description":"image, video, thumbnail or avatar."},"variant":{"type":"string","description":"Source variant when known."},"expires_at":{"type":"string","description":"Expiry timestamp when known."}}}},"children":{"type":"array","description":"Ordered carousel children when returned; null for non-carousels.","items":{"type":"object","description":"One carousel child.","properties":{"id":{"type":"string","description":"Media ID."},"position":{"type":"number","description":"Zero-based position."},"media_type":{"type":"string","description":"image, video or null."},"media_url":{"type":"string","description":"Preview image URL."},"video_url":{"type":"string","description":"Source video URL when available."},"width":{"type":"number","description":"Width in pixels."},"height":{"type":"number","description":"Height in pixels."}}}}}}},"/v2/instagram/media/transcript":{"get":{"operationId":"instagram_v2_media_transcript","summary":"Instagram media transcript","description":"Get a transcript for a public reel or video. Planned: returns 501 SOURCE_NOT_IMPLEMENTED; no collector or sample response is available and no credits are charged.","tags":["instagram"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"url","in":"query","required":true,"schema":{"type":"string","pattern":"^https?://[^\\s]{5,400}$","example":"https://www.instagram.com/reel/CxDemo123/"},"description":"Required instagram url."},{"name":"cache_max_age","in":"query","required":false,"schema":{"type":"string","enum":["1d","3d","7d","14d","30d"]},"description":"Maximum acceptable cache age. Valid cache hits cost zero credits."},{"name":"fields","in":"query","required":false,"schema":{"type":"string","example":"item"},"description":"Comma-separated fields or dot paths, including inside arrays such as items.id. Response identity and pagination are retained."},{"name":"trim","in":"query","required":false,"schema":{"type":"boolean","default":false},"description":"Remove null and empty values. Meaningful empty YouTube region-restriction lists are retained."}],"responses":{"200":{"description":"Normalized resource","headers":{"x-request-id":{"schema":{"type":"string"}},"x-data-mode":{"schema":{"type":"string","enum":["live","sandbox"]}},"x-cache":{"schema":{"type":"string","enum":["HIT","MISS"]}},"x-credits-charged":{"schema":{"type":"integer"}},"x-credits-remaining":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"data":{"type":"object","properties":{"item":{"type":"object","additionalProperties":true,"properties":{"id":{"type":["string","null"],"description":"Resource identifier used by this endpoint."},"author":{"type":["string","null"],"description":"Public creator name or handle."},"published_at":{"type":["string","null"],"description":"Source publication date or timestamp; null when absent."},"views":{"type":["number","null"],"description":"Observed views, where exposed by this source."},"likes":{"type":["number","null"],"description":"Observed likes."},"comments":{"type":["number","null"],"description":"Observed comment count, not comment rows."},"media_url":{"type":["string","null"],"description":"Preview image URL; not a guaranteed downloadable video."},"permalink":{"type":["string","null"],"description":"Public content URL."},"duration_seconds":{"type":["number","null"],"description":"Duration in seconds when returned."},"hashtags":{"type":["array","null"],"description":"Hashtags with platform or derived_text provenance.","items":{"type":["object","null"],"description":"Entity observed at source or derived from text.","properties":{"name":{"type":["string","null"],"description":"Hashtag or account name."},"id":{"type":["string","null"],"description":"Platform ID when supplied."},"source":{"type":["string","null"],"description":"platform or derived_text."}}}},"mentions":{"type":["array","null"],"description":"Mentions with platform or derived_text provenance; text is not proof of an account relationship.","items":{"type":["object","null"],"description":"Entity observed at source or derived from text.","properties":{"name":{"type":["string","null"],"description":"Hashtag or account name."},"id":{"type":["string","null"],"description":"Platform ID when supplied."},"source":{"type":["string","null"],"description":"platform or derived_text."}}}},"author_id":{"type":["string","null"],"description":"Stable creator ID when returned."},"author_display_name":{"type":["string","null"],"description":"Public display name."},"author_verified":{"type":["boolean","null"],"description":"Explicit creator verification state."},"author_avatar_url":{"type":["string","null"],"description":"Public creator avatar URL."},"platform_content_id":{"type":["string","null"],"description":"Platform media ID, separate from the shortcode."},"caption":{"type":["string","null"],"description":"Public caption."},"media_type":{"type":["string","null"],"description":"image, video, carousel, or null when unknown."},"media_product_type":{"type":["string","null"],"description":"Source product type, kept separate from media type."},"width":{"type":["number","null"],"description":"Media width in pixels."},"height":{"type":["number","null"],"description":"Media height in pixels."},"video_url":{"type":["string","null"],"description":"Source video URL where returned; may expire."},"comments_enabled":{"type":["boolean","null"],"description":"Observed comments setting."},"paid_partnership":{"type":["boolean","null"],"description":"Explicit source partnership flag; null when unavailable."},"accessibility_caption":{"type":["string","null"],"description":"Source alt text or accessibility description."},"location":{"type":["object","null"],"description":"Publicly attached location label.","properties":{"id":{"type":["string","null"],"description":"Location ID."},"name":{"type":["string","null"],"description":"Location name."},"slug":{"type":["string","null"],"description":"Location slug."}}},"tagged_users":{"type":["array","null"],"description":"Accounts explicitly tagged in the media.","items":{"type":["object","null"],"description":"Tagged account.","properties":{"id":{"type":["string","null"],"description":"Platform account ID."},"username":{"type":["string","null"],"description":"Handle."},"display_name":{"type":["string","null"],"description":"Display name."}}}},"media_assets":{"type":["array","null"],"description":"Returned image/video variants with dimensions.","items":{"type":["object","null"],"description":"One source media variant; URLs may expire.","properties":{"url":{"type":["string","null"],"description":"Source URL."},"width":{"type":["number","null"],"description":"Width in pixels."},"height":{"type":["number","null"],"description":"Height in pixels."},"asset_type":{"type":["string","null"],"description":"image, video, thumbnail or avatar."},"variant":{"type":["string","null"],"description":"Source variant when known."},"expires_at":{"type":["string","null"],"description":"Expiry timestamp when known."}}}},"children":{"type":["array","null"],"description":"Ordered carousel children when returned; null for non-carousels.","items":{"type":["object","null"],"description":"One carousel child.","properties":{"id":{"type":["string","null"],"description":"Media ID."},"position":{"type":["number","null"],"description":"Zero-based position."},"media_type":{"type":["string","null"],"description":"image, video or null."},"media_url":{"type":["string","null"],"description":"Preview image URL."},"video_url":{"type":["string","null"],"description":"Source video URL when available."},"width":{"type":["number","null"],"description":"Width in pixels."},"height":{"type":["number","null"],"description":"Height in pixels."}}}}}}}}}}]}}}},"400":{"$ref":"#/components/responses/InvalidInput"},"401":{"$ref":"#/components/responses/InvalidApiKey"},"402":{"$ref":"#/components/responses/InsufficientCredits"},"403":{"$ref":"#/components/responses/SourceRestricted"},"404":{"$ref":"#/components/responses/ResourceNotFound"},"408":{"$ref":"#/components/responses/SourceTimeout"},"422":{"$ref":"#/components/responses/SourceResponseChanged"},"429":{"$ref":"#/components/responses/TemporaryCapacity"},"501":{"$ref":"#/components/responses/SourceNotImplemented"},"503":{"$ref":"#/components/responses/SourceUnavailable"}},"x-availability":"planned","x-identifier-one-of":["url"],"x-credits":4,"x-source-access":"public_page","x-preview":true,"x-codeSamples":[{"lang":"curl","source":"curl 'https://api.socialdatakit.com/v2/instagram/media/transcript?url=https%3A%2F%2Fwww.instagram.com%2Freel%2FCxDemo123%2F' \\\n  -H 'x-api-key: YOUR_API_KEY'"},{"lang":"javascript","source":"const response = await fetch(\"https://api.socialdatakit.com/v2/instagram/media/transcript?url=https%3A%2F%2Fwww.instagram.com%2Freel%2FCxDemo123%2F\", {\n  headers: { \"x-api-key\": process.env.SOCIALDATAKIT_API_KEY }\n});\nif (!response.ok) throw new Error(await response.text());\nconst result = await response.json();"},{"lang":"python","source":"import os\nimport requests\n\nresponse = requests.get(\n    \"https://api.socialdatakit.com/v2/instagram/media/transcript?url=https%3A%2F%2Fwww.instagram.com%2Freel%2FCxDemo123%2F\",\n    headers={\"x-api-key\": os.environ[\"SOCIALDATAKIT_API_KEY\"]},\n    timeout=30,\n)\nresponse.raise_for_status()\nresult = response.json()"}],"x-response-fields":{"id":{"type":"string","description":"Resource identifier used by this endpoint."},"author":{"type":"string","description":"Public creator name or handle."},"published_at":{"type":"string","description":"Source publication date or timestamp; null when absent."},"views":{"type":"number","description":"Observed views, where exposed by this source."},"likes":{"type":"number","description":"Observed likes."},"comments":{"type":"number","description":"Observed comment count, not comment rows."},"media_url":{"type":"string","description":"Preview image URL; not a guaranteed downloadable video."},"permalink":{"type":"string","description":"Public content URL."},"duration_seconds":{"type":"number","description":"Duration in seconds when returned."},"hashtags":{"type":"array","description":"Hashtags with platform or derived_text provenance.","items":{"type":"object","description":"Entity observed at source or derived from text.","properties":{"name":{"type":"string","description":"Hashtag or account name."},"id":{"type":"string","description":"Platform ID when supplied."},"source":{"type":"string","description":"platform or derived_text."}}}},"mentions":{"type":"array","description":"Mentions with platform or derived_text provenance; text is not proof of an account relationship.","items":{"type":"object","description":"Entity observed at source or derived from text.","properties":{"name":{"type":"string","description":"Hashtag or account name."},"id":{"type":"string","description":"Platform ID when supplied."},"source":{"type":"string","description":"platform or derived_text."}}}},"author_id":{"type":"string","description":"Stable creator ID when returned."},"author_display_name":{"type":"string","description":"Public display name."},"author_verified":{"type":"boolean","description":"Explicit creator verification state."},"author_avatar_url":{"type":"string","description":"Public creator avatar URL."},"platform_content_id":{"type":"string","description":"Platform media ID, separate from the shortcode."},"caption":{"type":"string","description":"Public caption."},"media_type":{"type":"string","description":"image, video, carousel, or null when unknown."},"media_product_type":{"type":"string","description":"Source product type, kept separate from media type."},"width":{"type":"number","description":"Media width in pixels."},"height":{"type":"number","description":"Media height in pixels."},"video_url":{"type":"string","description":"Source video URL where returned; may expire."},"comments_enabled":{"type":"boolean","description":"Observed comments setting."},"paid_partnership":{"type":"boolean","description":"Explicit source partnership flag; null when unavailable."},"accessibility_caption":{"type":"string","description":"Source alt text or accessibility description."},"location":{"type":"object","description":"Publicly attached location label.","properties":{"id":{"type":"string","description":"Location ID."},"name":{"type":"string","description":"Location name."},"slug":{"type":"string","description":"Location slug."}}},"tagged_users":{"type":"array","description":"Accounts explicitly tagged in the media.","items":{"type":"object","description":"Tagged account.","properties":{"id":{"type":"string","description":"Platform account ID."},"username":{"type":"string","description":"Handle."},"display_name":{"type":"string","description":"Display name."}}}},"media_assets":{"type":"array","description":"Returned image/video variants with dimensions.","items":{"type":"object","description":"One source media variant; URLs may expire.","properties":{"url":{"type":"string","description":"Source URL."},"width":{"type":"number","description":"Width in pixels."},"height":{"type":"number","description":"Height in pixels."},"asset_type":{"type":"string","description":"image, video, thumbnail or avatar."},"variant":{"type":"string","description":"Source variant when known."},"expires_at":{"type":"string","description":"Expiry timestamp when known."}}}},"children":{"type":"array","description":"Ordered carousel children when returned; null for non-carousels.","items":{"type":"object","description":"One carousel child.","properties":{"id":{"type":"string","description":"Media ID."},"position":{"type":"number","description":"Zero-based position."},"media_type":{"type":"string","description":"image, video or null."},"media_url":{"type":"string","description":"Preview image URL."},"video_url":{"type":"string","description":"Source video URL when available."},"width":{"type":"number","description":"Width in pixels."},"height":{"type":"number","description":"Height in pixels."}}}}}}},"/v2/instagram/reels/search":{"get":{"operationId":"instagram_v2_reels_search","summary":"Instagram reel search","description":"Search public reels by keyword. Planned: returns 501 SOURCE_NOT_IMPLEMENTED; no collector or sample response is available and no credits are charged.","tags":["instagram"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"query","in":"query","required":true,"schema":{"type":"string","pattern":"^.{1,180}$","example":"travel"},"description":"Required instagram query."},{"name":"cache_max_age","in":"query","required":false,"schema":{"type":"string","enum":["1d","3d","7d","14d","30d"]},"description":"Maximum acceptable cache age. Valid cache hits cost zero credits."},{"name":"fields","in":"query","required":false,"schema":{"type":"string","example":"items"},"description":"Comma-separated fields or dot paths, including inside arrays such as items.id. Response identity and pagination are retained."},{"name":"trim","in":"query","required":false,"schema":{"type":"boolean","default":false},"description":"Remove null and empty values. Meaningful empty YouTube region-restriction lists are retained."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":20,"default":3},"description":"Number of items to return."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"},"description":"Opaque pagination value returned as data.pagination.next_cursor. Keep the identifier, filters and limit unchanged."}],"responses":{"200":{"description":"Normalized resource","headers":{"x-request-id":{"schema":{"type":"string"}},"x-data-mode":{"schema":{"type":"string","enum":["live","sandbox"]}},"x-cache":{"schema":{"type":"string","enum":["HIT","MISS"]}},"x-credits-charged":{"schema":{"type":"integer"}},"x-credits-remaining":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"data":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","additionalProperties":true,"properties":{"id":{"type":["string","null"],"description":"Matched platform object ID."},"result_type":{"type":["string","null"],"description":"video, channel or playlist."},"title":{"type":["string","null"],"description":"Source title."},"description":{"type":["string","null"],"description":"Search snippet."},"channel_id":{"type":["string","null"],"description":"Owning channel ID."},"author":{"type":["string","null"],"description":"Channel name."},"published_at":{"type":["string","null"],"description":"Source publish time."},"thumbnails":{"type":["array","null"],"description":"All returned thumbnail variants; dimensions are source values.","items":{"type":["object","null"],"description":"Thumbnail.","properties":{"url":{"type":["string","null"],"description":"Source URL."},"variant":{"type":["string","null"],"description":"Source variant."},"width":{"type":["number","null"],"description":"Width."},"height":{"type":["number","null"],"description":"Height."},"asset_type":{"type":["string","null"],"description":"thumbnail."},"expires_at":{"type":["string","null"],"description":"Expiry when known."}}}},"live_status":{"type":["string","null"],"description":"Broadcast status."},"permalink":{"type":["string","null"],"description":"Public result URL."},"query":{"type":["string","null"],"description":"Query submitted."},"position":{"type":["number","null"],"description":"One-based position in this API result traversal, not personalized website ranking."},"region_code":{"type":["string","null"],"description":"Requested region, if specified."},"language":{"type":["string","null"],"description":"Requested relevance language, if specified."},"order":{"type":["string","null"],"description":"Requested sorting order."}}}}}}}}]}}}},"400":{"$ref":"#/components/responses/InvalidInput"},"401":{"$ref":"#/components/responses/InvalidApiKey"},"402":{"$ref":"#/components/responses/InsufficientCredits"},"403":{"$ref":"#/components/responses/SourceRestricted"},"404":{"$ref":"#/components/responses/ResourceNotFound"},"408":{"$ref":"#/components/responses/SourceTimeout"},"422":{"$ref":"#/components/responses/SourceResponseChanged"},"429":{"$ref":"#/components/responses/TemporaryCapacity"},"501":{"$ref":"#/components/responses/SourceNotImplemented"},"503":{"$ref":"#/components/responses/SourceUnavailable"}},"x-availability":"planned","x-identifier-one-of":["query"],"x-credits":3,"x-source-access":"public_page","x-preview":true,"x-codeSamples":[{"lang":"curl","source":"curl 'https://api.socialdatakit.com/v2/instagram/reels/search?query=travel' \\\n  -H 'x-api-key: YOUR_API_KEY'"},{"lang":"javascript","source":"const response = await fetch(\"https://api.socialdatakit.com/v2/instagram/reels/search?query=travel\", {\n  headers: { \"x-api-key\": process.env.SOCIALDATAKIT_API_KEY }\n});\nif (!response.ok) throw new Error(await response.text());\nconst result = await response.json();"},{"lang":"python","source":"import os\nimport requests\n\nresponse = requests.get(\n    \"https://api.socialdatakit.com/v2/instagram/reels/search?query=travel\",\n    headers={\"x-api-key\": os.environ[\"SOCIALDATAKIT_API_KEY\"]},\n    timeout=30,\n)\nresponse.raise_for_status()\nresult = response.json()"}],"x-response-fields":{"id":{"type":"string","description":"Matched platform object ID."},"result_type":{"type":"string","description":"video, channel or playlist."},"title":{"type":"string","description":"Source title."},"description":{"type":"string","description":"Search snippet."},"channel_id":{"type":"string","description":"Owning channel ID."},"author":{"type":"string","description":"Channel name."},"published_at":{"type":"string","description":"Source publish time."},"thumbnails":{"type":"array","description":"All returned thumbnail variants; dimensions are source values.","items":{"type":"object","description":"Thumbnail.","properties":{"url":{"type":"string","description":"Source URL."},"variant":{"type":"string","description":"Source variant."},"width":{"type":"number","description":"Width."},"height":{"type":"number","description":"Height."},"asset_type":{"type":"string","description":"thumbnail."},"expires_at":{"type":"string","description":"Expiry when known."}}}},"live_status":{"type":"string","description":"Broadcast status."},"permalink":{"type":"string","description":"Public result URL."},"query":{"type":"string","description":"Query submitted."},"position":{"type":"number","description":"One-based position in this API result traversal, not personalized website ranking."},"region_code":{"type":"string","description":"Requested region, if specified."},"language":{"type":"string","description":"Requested relevance language, if specified."},"order":{"type":"string","description":"Requested sorting order."}}}},"/v1/instagram/basic/profile":{"get":{"operationId":"instagram_v1_basic_profile","summary":"Instagram profile by ID","description":"Get a public profile using its numeric account ID. Planned: returns 501 SOURCE_NOT_IMPLEMENTED; no collector or sample response is available and no credits are charged.","tags":["instagram"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"userId","in":"query","required":true,"schema":{"type":"string","pattern":"^[0-9]{1,24}$","example":"787132"},"description":"Required instagram userId."},{"name":"cache_max_age","in":"query","required":false,"schema":{"type":"string","enum":["1d","3d","7d","14d","30d"]},"description":"Maximum acceptable cache age. Valid cache hits cost zero credits."},{"name":"fields","in":"query","required":false,"schema":{"type":"string","example":"profile.username,profile.followers"},"description":"Comma-separated fields or dot paths, including inside arrays such as items.id. Response identity and pagination are retained."},{"name":"trim","in":"query","required":false,"schema":{"type":"boolean","default":false},"description":"Remove null and empty values. Meaningful empty YouTube region-restriction lists are retained."}],"responses":{"200":{"description":"Normalized resource","headers":{"x-request-id":{"schema":{"type":"string"}},"x-data-mode":{"schema":{"type":"string","enum":["live","sandbox"]}},"x-cache":{"schema":{"type":"string","enum":["HIT","MISS"]}},"x-credits-charged":{"schema":{"type":"integer"}},"x-credits-remaining":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"data":{"type":"object","properties":{"profile":{"type":"object","additionalProperties":true,"properties":{"id":{"type":["string","null"],"description":"Resource identifier used by this endpoint."},"author":{"type":["string","null"],"description":"Public creator name or handle."},"published_at":{"type":["string","null"],"description":"Source publication date or timestamp; null when absent."},"views":{"type":["number","null"],"description":"Observed views, where exposed by this source."},"likes":{"type":["number","null"],"description":"Observed likes."},"comments":{"type":["number","null"],"description":"Observed comment count, not comment rows."},"media_url":{"type":["string","null"],"description":"Preview image URL; not a guaranteed downloadable video."},"permalink":{"type":["string","null"],"description":"Public content URL."},"duration_seconds":{"type":["number","null"],"description":"Duration in seconds when returned."},"hashtags":{"type":["array","null"],"description":"Hashtags with platform or derived_text provenance.","items":{"type":["object","null"],"description":"Entity observed at source or derived from text.","properties":{"name":{"type":["string","null"],"description":"Hashtag or account name."},"id":{"type":["string","null"],"description":"Platform ID when supplied."},"source":{"type":["string","null"],"description":"platform or derived_text."}}}},"mentions":{"type":["array","null"],"description":"Mentions with platform or derived_text provenance; text is not proof of an account relationship.","items":{"type":["object","null"],"description":"Entity observed at source or derived from text.","properties":{"name":{"type":["string","null"],"description":"Hashtag or account name."},"id":{"type":["string","null"],"description":"Platform ID when supplied."},"source":{"type":["string","null"],"description":"platform or derived_text."}}}},"author_id":{"type":["string","null"],"description":"Stable creator ID when returned."},"author_display_name":{"type":["string","null"],"description":"Public display name."},"author_verified":{"type":["boolean","null"],"description":"Explicit creator verification state."},"author_avatar_url":{"type":["string","null"],"description":"Public creator avatar URL."},"platform_content_id":{"type":["string","null"],"description":"Platform media ID, separate from the shortcode."},"caption":{"type":["string","null"],"description":"Public caption."},"media_type":{"type":["string","null"],"description":"image, video, carousel, or null when unknown."},"media_product_type":{"type":["string","null"],"description":"Source product type, kept separate from media type."},"width":{"type":["number","null"],"description":"Media width in pixels."},"height":{"type":["number","null"],"description":"Media height in pixels."},"video_url":{"type":["string","null"],"description":"Source video URL where returned; may expire."},"comments_enabled":{"type":["boolean","null"],"description":"Observed comments setting."},"paid_partnership":{"type":["boolean","null"],"description":"Explicit source partnership flag; null when unavailable."},"accessibility_caption":{"type":["string","null"],"description":"Source alt text or accessibility description."},"location":{"type":["object","null"],"description":"Publicly attached location label.","properties":{"id":{"type":["string","null"],"description":"Location ID."},"name":{"type":["string","null"],"description":"Location name."},"slug":{"type":["string","null"],"description":"Location slug."}}},"tagged_users":{"type":["array","null"],"description":"Accounts explicitly tagged in the media.","items":{"type":["object","null"],"description":"Tagged account.","properties":{"id":{"type":["string","null"],"description":"Platform account ID."},"username":{"type":["string","null"],"description":"Handle."},"display_name":{"type":["string","null"],"description":"Display name."}}}},"media_assets":{"type":["array","null"],"description":"Returned image/video variants with dimensions.","items":{"type":["object","null"],"description":"One source media variant; URLs may expire.","properties":{"url":{"type":["string","null"],"description":"Source URL."},"width":{"type":["number","null"],"description":"Width in pixels."},"height":{"type":["number","null"],"description":"Height in pixels."},"asset_type":{"type":["string","null"],"description":"image, video, thumbnail or avatar."},"variant":{"type":["string","null"],"description":"Source variant when known."},"expires_at":{"type":["string","null"],"description":"Expiry timestamp when known."}}}},"children":{"type":["array","null"],"description":"Ordered carousel children when returned; null for non-carousels.","items":{"type":["object","null"],"description":"One carousel child.","properties":{"id":{"type":["string","null"],"description":"Media ID."},"position":{"type":["number","null"],"description":"Zero-based position."},"media_type":{"type":["string","null"],"description":"image, video or null."},"media_url":{"type":["string","null"],"description":"Preview image URL."},"video_url":{"type":["string","null"],"description":"Source video URL when available."},"width":{"type":["number","null"],"description":"Width in pixels."},"height":{"type":["number","null"],"description":"Height in pixels."}}}}}}}}}}]}}}},"400":{"$ref":"#/components/responses/InvalidInput"},"401":{"$ref":"#/components/responses/InvalidApiKey"},"402":{"$ref":"#/components/responses/InsufficientCredits"},"403":{"$ref":"#/components/responses/SourceRestricted"},"404":{"$ref":"#/components/responses/ResourceNotFound"},"408":{"$ref":"#/components/responses/SourceTimeout"},"422":{"$ref":"#/components/responses/SourceResponseChanged"},"429":{"$ref":"#/components/responses/TemporaryCapacity"},"501":{"$ref":"#/components/responses/SourceNotImplemented"},"503":{"$ref":"#/components/responses/SourceUnavailable"}},"x-availability":"planned","x-identifier-one-of":["userId"],"x-credits":1,"x-source-access":"public_page","x-preview":true,"x-codeSamples":[{"lang":"curl","source":"curl 'https://api.socialdatakit.com/v1/instagram/basic/profile?userId=787132' \\\n  -H 'x-api-key: YOUR_API_KEY'"},{"lang":"javascript","source":"const response = await fetch(\"https://api.socialdatakit.com/v1/instagram/basic/profile?userId=787132\", {\n  headers: { \"x-api-key\": process.env.SOCIALDATAKIT_API_KEY }\n});\nif (!response.ok) throw new Error(await response.text());\nconst result = await response.json();"},{"lang":"python","source":"import os\nimport requests\n\nresponse = requests.get(\n    \"https://api.socialdatakit.com/v1/instagram/basic/profile?userId=787132\",\n    headers={\"x-api-key\": os.environ[\"SOCIALDATAKIT_API_KEY\"]},\n    timeout=30,\n)\nresponse.raise_for_status()\nresult = response.json()"}],"x-response-fields":{"id":{"type":"string","description":"Resource identifier used by this endpoint."},"author":{"type":"string","description":"Public creator name or handle."},"published_at":{"type":"string","description":"Source publication date or timestamp; null when absent."},"views":{"type":"number","description":"Observed views, where exposed by this source."},"likes":{"type":"number","description":"Observed likes."},"comments":{"type":"number","description":"Observed comment count, not comment rows."},"media_url":{"type":"string","description":"Preview image URL; not a guaranteed downloadable video."},"permalink":{"type":"string","description":"Public content URL."},"duration_seconds":{"type":"number","description":"Duration in seconds when returned."},"hashtags":{"type":"array","description":"Hashtags with platform or derived_text provenance.","items":{"type":"object","description":"Entity observed at source or derived from text.","properties":{"name":{"type":"string","description":"Hashtag or account name."},"id":{"type":"string","description":"Platform ID when supplied."},"source":{"type":"string","description":"platform or derived_text."}}}},"mentions":{"type":"array","description":"Mentions with platform or derived_text provenance; text is not proof of an account relationship.","items":{"type":"object","description":"Entity observed at source or derived from text.","properties":{"name":{"type":"string","description":"Hashtag or account name."},"id":{"type":"string","description":"Platform ID when supplied."},"source":{"type":"string","description":"platform or derived_text."}}}},"author_id":{"type":"string","description":"Stable creator ID when returned."},"author_display_name":{"type":"string","description":"Public display name."},"author_verified":{"type":"boolean","description":"Explicit creator verification state."},"author_avatar_url":{"type":"string","description":"Public creator avatar URL."},"platform_content_id":{"type":"string","description":"Platform media ID, separate from the shortcode."},"caption":{"type":"string","description":"Public caption."},"media_type":{"type":"string","description":"image, video, carousel, or null when unknown."},"media_product_type":{"type":"string","description":"Source product type, kept separate from media type."},"width":{"type":"number","description":"Media width in pixels."},"height":{"type":"number","description":"Media height in pixels."},"video_url":{"type":"string","description":"Source video URL where returned; may expire."},"comments_enabled":{"type":"boolean","description":"Observed comments setting."},"paid_partnership":{"type":"boolean","description":"Explicit source partnership flag; null when unavailable."},"accessibility_caption":{"type":"string","description":"Source alt text or accessibility description."},"location":{"type":"object","description":"Publicly attached location label.","properties":{"id":{"type":"string","description":"Location ID."},"name":{"type":"string","description":"Location name."},"slug":{"type":"string","description":"Location slug."}}},"tagged_users":{"type":"array","description":"Accounts explicitly tagged in the media.","items":{"type":"object","description":"Tagged account.","properties":{"id":{"type":"string","description":"Platform account ID."},"username":{"type":"string","description":"Handle."},"display_name":{"type":"string","description":"Display name."}}}},"media_assets":{"type":"array","description":"Returned image/video variants with dimensions.","items":{"type":"object","description":"One source media variant; URLs may expire.","properties":{"url":{"type":"string","description":"Source URL."},"width":{"type":"number","description":"Width in pixels."},"height":{"type":"number","description":"Height in pixels."},"asset_type":{"type":"string","description":"image, video, thumbnail or avatar."},"variant":{"type":"string","description":"Source variant when known."},"expires_at":{"type":"string","description":"Expiry timestamp when known."}}}},"children":{"type":"array","description":"Ordered carousel children when returned; null for non-carousels.","items":{"type":"object","description":"One carousel child.","properties":{"id":{"type":"string","description":"Media ID."},"position":{"type":"number","description":"Zero-based position."},"media_type":{"type":"string","description":"image, video or null."},"media_url":{"type":"string","description":"Preview image URL."},"video_url":{"type":"string","description":"Source video URL when available."},"width":{"type":"number","description":"Width in pixels."},"height":{"type":"number","description":"Height in pixels."}}}}}}},"/v1/instagram/user/embed":{"get":{"operationId":"instagram_v1_user_embed","summary":"Instagram embed HTML","description":"Get the public embed markup for a profile. Planned: returns 501 SOURCE_NOT_IMPLEMENTED; no collector or sample response is available and no credits are charged.","tags":["instagram"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"handle","in":"query","required":true,"schema":{"type":"string","pattern":"^@?[A-Za-z0-9._]{1,30}$","example":"natgeo"},"description":"Required instagram handle."},{"name":"cache_max_age","in":"query","required":false,"schema":{"type":"string","enum":["1d","3d","7d","14d","30d"]},"description":"Maximum acceptable cache age. Valid cache hits cost zero credits."},{"name":"fields","in":"query","required":false,"schema":{"type":"string","example":"item"},"description":"Comma-separated fields or dot paths, including inside arrays such as items.id. Response identity and pagination are retained."},{"name":"trim","in":"query","required":false,"schema":{"type":"boolean","default":false},"description":"Remove null and empty values. Meaningful empty YouTube region-restriction lists are retained."}],"responses":{"200":{"description":"Normalized resource","headers":{"x-request-id":{"schema":{"type":"string"}},"x-data-mode":{"schema":{"type":"string","enum":["live","sandbox"]}},"x-cache":{"schema":{"type":"string","enum":["HIT","MISS"]}},"x-credits-charged":{"schema":{"type":"integer"}},"x-credits-remaining":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"data":{"type":"object","properties":{"item":{"type":"object","additionalProperties":true,"properties":{"id":{"type":["string","null"],"description":"Resource identifier used by this endpoint."},"author":{"type":["string","null"],"description":"Public creator name or handle."},"published_at":{"type":["string","null"],"description":"Source publication date or timestamp; null when absent."},"views":{"type":["number","null"],"description":"Observed views, where exposed by this source."},"likes":{"type":["number","null"],"description":"Observed likes."},"comments":{"type":["number","null"],"description":"Observed comment count, not comment rows."},"media_url":{"type":["string","null"],"description":"Preview image URL; not a guaranteed downloadable video."},"permalink":{"type":["string","null"],"description":"Public content URL."},"duration_seconds":{"type":["number","null"],"description":"Duration in seconds when returned."},"hashtags":{"type":["array","null"],"description":"Hashtags with platform or derived_text provenance.","items":{"type":["object","null"],"description":"Entity observed at source or derived from text.","properties":{"name":{"type":["string","null"],"description":"Hashtag or account name."},"id":{"type":["string","null"],"description":"Platform ID when supplied."},"source":{"type":["string","null"],"description":"platform or derived_text."}}}},"mentions":{"type":["array","null"],"description":"Mentions with platform or derived_text provenance; text is not proof of an account relationship.","items":{"type":["object","null"],"description":"Entity observed at source or derived from text.","properties":{"name":{"type":["string","null"],"description":"Hashtag or account name."},"id":{"type":["string","null"],"description":"Platform ID when supplied."},"source":{"type":["string","null"],"description":"platform or derived_text."}}}},"author_id":{"type":["string","null"],"description":"Stable creator ID when returned."},"author_display_name":{"type":["string","null"],"description":"Public display name."},"author_verified":{"type":["boolean","null"],"description":"Explicit creator verification state."},"author_avatar_url":{"type":["string","null"],"description":"Public creator avatar URL."},"platform_content_id":{"type":["string","null"],"description":"Platform media ID, separate from the shortcode."},"caption":{"type":["string","null"],"description":"Public caption."},"media_type":{"type":["string","null"],"description":"image, video, carousel, or null when unknown."},"media_product_type":{"type":["string","null"],"description":"Source product type, kept separate from media type."},"width":{"type":["number","null"],"description":"Media width in pixels."},"height":{"type":["number","null"],"description":"Media height in pixels."},"video_url":{"type":["string","null"],"description":"Source video URL where returned; may expire."},"comments_enabled":{"type":["boolean","null"],"description":"Observed comments setting."},"paid_partnership":{"type":["boolean","null"],"description":"Explicit source partnership flag; null when unavailable."},"accessibility_caption":{"type":["string","null"],"description":"Source alt text or accessibility description."},"location":{"type":["object","null"],"description":"Publicly attached location label.","properties":{"id":{"type":["string","null"],"description":"Location ID."},"name":{"type":["string","null"],"description":"Location name."},"slug":{"type":["string","null"],"description":"Location slug."}}},"tagged_users":{"type":["array","null"],"description":"Accounts explicitly tagged in the media.","items":{"type":["object","null"],"description":"Tagged account.","properties":{"id":{"type":["string","null"],"description":"Platform account ID."},"username":{"type":["string","null"],"description":"Handle."},"display_name":{"type":["string","null"],"description":"Display name."}}}},"media_assets":{"type":["array","null"],"description":"Returned image/video variants with dimensions.","items":{"type":["object","null"],"description":"One source media variant; URLs may expire.","properties":{"url":{"type":["string","null"],"description":"Source URL."},"width":{"type":["number","null"],"description":"Width in pixels."},"height":{"type":["number","null"],"description":"Height in pixels."},"asset_type":{"type":["string","null"],"description":"image, video, thumbnail or avatar."},"variant":{"type":["string","null"],"description":"Source variant when known."},"expires_at":{"type":["string","null"],"description":"Expiry timestamp when known."}}}},"children":{"type":["array","null"],"description":"Ordered carousel children when returned; null for non-carousels.","items":{"type":["object","null"],"description":"One carousel child.","properties":{"id":{"type":["string","null"],"description":"Media ID."},"position":{"type":["number","null"],"description":"Zero-based position."},"media_type":{"type":["string","null"],"description":"image, video or null."},"media_url":{"type":["string","null"],"description":"Preview image URL."},"video_url":{"type":["string","null"],"description":"Source video URL when available."},"width":{"type":["number","null"],"description":"Width in pixels."},"height":{"type":["number","null"],"description":"Height in pixels."}}}}}}}}}}]}}}},"400":{"$ref":"#/components/responses/InvalidInput"},"401":{"$ref":"#/components/responses/InvalidApiKey"},"402":{"$ref":"#/components/responses/InsufficientCredits"},"403":{"$ref":"#/components/responses/SourceRestricted"},"404":{"$ref":"#/components/responses/ResourceNotFound"},"408":{"$ref":"#/components/responses/SourceTimeout"},"422":{"$ref":"#/components/responses/SourceResponseChanged"},"429":{"$ref":"#/components/responses/TemporaryCapacity"},"501":{"$ref":"#/components/responses/SourceNotImplemented"},"503":{"$ref":"#/components/responses/SourceUnavailable"}},"x-availability":"planned","x-identifier-one-of":["handle"],"x-credits":1,"x-source-access":"public_page","x-preview":true,"x-codeSamples":[{"lang":"curl","source":"curl 'https://api.socialdatakit.com/v1/instagram/user/embed?handle=natgeo' \\\n  -H 'x-api-key: YOUR_API_KEY'"},{"lang":"javascript","source":"const response = await fetch(\"https://api.socialdatakit.com/v1/instagram/user/embed?handle=natgeo\", {\n  headers: { \"x-api-key\": process.env.SOCIALDATAKIT_API_KEY }\n});\nif (!response.ok) throw new Error(await response.text());\nconst result = await response.json();"},{"lang":"python","source":"import os\nimport requests\n\nresponse = requests.get(\n    \"https://api.socialdatakit.com/v1/instagram/user/embed?handle=natgeo\",\n    headers={\"x-api-key\": os.environ[\"SOCIALDATAKIT_API_KEY\"]},\n    timeout=30,\n)\nresponse.raise_for_status()\nresult = response.json()"}],"x-response-fields":{"id":{"type":"string","description":"Resource identifier used by this endpoint."},"author":{"type":"string","description":"Public creator name or handle."},"published_at":{"type":"string","description":"Source publication date or timestamp; null when absent."},"views":{"type":"number","description":"Observed views, where exposed by this source."},"likes":{"type":"number","description":"Observed likes."},"comments":{"type":"number","description":"Observed comment count, not comment rows."},"media_url":{"type":"string","description":"Preview image URL; not a guaranteed downloadable video."},"permalink":{"type":"string","description":"Public content URL."},"duration_seconds":{"type":"number","description":"Duration in seconds when returned."},"hashtags":{"type":"array","description":"Hashtags with platform or derived_text provenance.","items":{"type":"object","description":"Entity observed at source or derived from text.","properties":{"name":{"type":"string","description":"Hashtag or account name."},"id":{"type":"string","description":"Platform ID when supplied."},"source":{"type":"string","description":"platform or derived_text."}}}},"mentions":{"type":"array","description":"Mentions with platform or derived_text provenance; text is not proof of an account relationship.","items":{"type":"object","description":"Entity observed at source or derived from text.","properties":{"name":{"type":"string","description":"Hashtag or account name."},"id":{"type":"string","description":"Platform ID when supplied."},"source":{"type":"string","description":"platform or derived_text."}}}},"author_id":{"type":"string","description":"Stable creator ID when returned."},"author_display_name":{"type":"string","description":"Public display name."},"author_verified":{"type":"boolean","description":"Explicit creator verification state."},"author_avatar_url":{"type":"string","description":"Public creator avatar URL."},"platform_content_id":{"type":"string","description":"Platform media ID, separate from the shortcode."},"caption":{"type":"string","description":"Public caption."},"media_type":{"type":"string","description":"image, video, carousel, or null when unknown."},"media_product_type":{"type":"string","description":"Source product type, kept separate from media type."},"width":{"type":"number","description":"Media width in pixels."},"height":{"type":"number","description":"Media height in pixels."},"video_url":{"type":"string","description":"Source video URL where returned; may expire."},"comments_enabled":{"type":"boolean","description":"Observed comments setting."},"paid_partnership":{"type":"boolean","description":"Explicit source partnership flag; null when unavailable."},"accessibility_caption":{"type":"string","description":"Source alt text or accessibility description."},"location":{"type":"object","description":"Publicly attached location label.","properties":{"id":{"type":"string","description":"Location ID."},"name":{"type":"string","description":"Location name."},"slug":{"type":"string","description":"Location slug."}}},"tagged_users":{"type":"array","description":"Accounts explicitly tagged in the media.","items":{"type":"object","description":"Tagged account.","properties":{"id":{"type":"string","description":"Platform account ID."},"username":{"type":"string","description":"Handle."},"display_name":{"type":"string","description":"Display name."}}}},"media_assets":{"type":"array","description":"Returned image/video variants with dimensions.","items":{"type":"object","description":"One source media variant; URLs may expire.","properties":{"url":{"type":"string","description":"Source URL."},"width":{"type":"number","description":"Width in pixels."},"height":{"type":"number","description":"Height in pixels."},"asset_type":{"type":"string","description":"image, video, thumbnail or avatar."},"variant":{"type":"string","description":"Source variant when known."},"expires_at":{"type":"string","description":"Expiry timestamp when known."}}}},"children":{"type":"array","description":"Ordered carousel children when returned; null for non-carousels.","items":{"type":"object","description":"One carousel child.","properties":{"id":{"type":"string","description":"Media ID."},"position":{"type":"number","description":"Zero-based position."},"media_type":{"type":"string","description":"image, video or null."},"media_url":{"type":"string","description":"Preview image URL."},"video_url":{"type":"string","description":"Source video URL when available."},"width":{"type":"number","description":"Width in pixels."},"height":{"type":"number","description":"Height in pixels."}}}}}}},"/v3/tiktok/profile/videos":{"get":{"operationId":"tiktok_v3_profile_videos","summary":"TikTok profile videos","description":"Get videos from a public profile. Preview: evaluate live availability and source coverage before customer use.","tags":["tiktok"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"handle","in":"query","required":true,"schema":{"type":"string","pattern":"^@?[A-Za-z0-9._]{2,24}$","example":"tiktok"},"description":"Required tiktok handle."},{"name":"cache_max_age","in":"query","required":false,"schema":{"type":"string","enum":["1d","3d","7d","14d","30d"]},"description":"Maximum acceptable cache age. Valid cache hits cost zero credits."},{"name":"fields","in":"query","required":false,"schema":{"type":"string","example":"items"},"description":"Comma-separated fields or dot paths, including inside arrays such as items.id. Response identity and pagination are retained."},{"name":"trim","in":"query","required":false,"schema":{"type":"boolean","default":false},"description":"Remove null and empty values. Meaningful empty YouTube region-restriction lists are retained."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":20,"default":3},"description":"Number of items to return."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"},"description":"Opaque pagination value returned as data.pagination.next_cursor. Keep the identifier, filters and limit unchanged."}],"responses":{"200":{"description":"Normalized resource","headers":{"x-request-id":{"schema":{"type":"string"}},"x-data-mode":{"schema":{"type":"string","enum":["live","sandbox"]}},"x-cache":{"schema":{"type":"string","enum":["HIT","MISS"]}},"x-credits-charged":{"schema":{"type":"integer"}},"x-credits-remaining":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"data":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","additionalProperties":true,"properties":{"id":{"type":["string","null"],"description":"Resource identifier used by this endpoint."},"author":{"type":["string","null"],"description":"Public creator name or handle."},"published_at":{"type":["string","null"],"description":"Source publication date or timestamp; null when absent."},"views":{"type":["number","null"],"description":"Observed views, where exposed by this source."},"likes":{"type":["number","null"],"description":"Observed likes."},"comments":{"type":["number","null"],"description":"Observed comment count, not comment rows."},"media_url":{"type":["string","null"],"description":"Preview image URL; not a guaranteed downloadable video."},"permalink":{"type":["string","null"],"description":"Public content URL."},"duration_seconds":{"type":["number","null"],"description":"Duration in seconds when returned."},"hashtags":{"type":["array","null"],"description":"Hashtags with platform or derived_text provenance.","items":{"type":["object","null"],"description":"Entity observed at source or derived from text.","properties":{"name":{"type":["string","null"],"description":"Hashtag or account name."},"id":{"type":["string","null"],"description":"Platform ID when supplied."},"source":{"type":["string","null"],"description":"platform or derived_text."}}}},"mentions":{"type":["array","null"],"description":"Mentions with platform or derived_text provenance; text is not proof of an account relationship.","items":{"type":["object","null"],"description":"Entity observed at source or derived from text.","properties":{"name":{"type":["string","null"],"description":"Hashtag or account name."},"id":{"type":["string","null"],"description":"Platform ID when supplied."},"source":{"type":["string","null"],"description":"platform or derived_text."}}}},"caption":{"type":["string","null"],"description":"Public video description."},"shares":{"type":["number","null"],"description":"Observed shares."},"favorites":{"type":["number","null"],"description":"Observed collect count; null when absent."},"width":{"type":["number","null"],"description":"Video width in pixels."},"height":{"type":["number","null"],"description":"Video height in pixels."},"author_id":{"type":["string","null"],"description":"Stable creator ID when returned."},"author_display_name":{"type":["string","null"],"description":"Public display name."},"author_verified":{"type":["boolean","null"],"description":"Explicit creator verification state."},"author_avatar_url":{"type":["string","null"],"description":"Public creator avatar URL."},"region_code":{"type":["string","null"],"description":"Source content region code when exposed; not proof of creator residence."},"video_url":{"type":["string","null"],"description":"Public playback URL when supplied; may expire or require source request headers."},"subtitle_tracks":{"type":["array","null"],"description":"Subtitle links exposed by the public video; does not run transcription.","items":{"type":["object","null"],"description":"Subtitle track.","properties":{"language":{"type":["string","null"],"description":"Source language code."},"language_id":{"type":["string","null"],"description":"Source language identifier."},"url":{"type":["string","null"],"description":"Source subtitle URL."},"format":{"type":["string","null"],"description":"Subtitle format."}}}},"effects":{"type":["array","null"],"description":"Effect metadata exposed by the public page.","items":{"type":["object","null"],"description":"Effect.","properties":{"id":{"type":["string","null"],"description":"Effect ID."},"name":{"type":["string","null"],"description":"Effect name."}}}},"stickers":{"type":["array","null"],"description":"Sticker metadata exposed by the public page.","items":{"type":["object","null"],"description":"Sticker.","properties":{"type":{"type":["number","null"],"description":"Source sticker type."},"texts":{"type":["array","null"],"description":"Returned sticker text.","items":{"type":["string","null"],"description":"Text."}}}}},"music":{"type":["object","null"],"description":"Sound metadata from the public video.","properties":{"id":{"type":["string","null"],"description":"Sound ID."},"title":{"type":["string","null"],"description":"Sound title."},"author":{"type":["string","null"],"description":"Sound author."},"original":{"type":["boolean","null"],"description":"Source original-sound flag."},"duration_seconds":{"type":["number","null"],"description":"Sound duration."},"cover_url":{"type":["string","null"],"description":"Sound cover URL."},"play_url":{"type":["string","null"],"description":"Sound preview URL."}}},"playlist_id":{"type":["string","null"],"description":"Source playlist ID when returned."},"pinned":{"type":["boolean","null"],"description":"Explicit pinned-item state when returned."},"media_assets":{"type":["array","null"],"description":"Returned cover variants.","items":{"type":["object","null"],"description":"One source media variant; URLs may expire.","properties":{"url":{"type":["string","null"],"description":"Source URL."},"width":{"type":["number","null"],"description":"Width in pixels."},"height":{"type":["number","null"],"description":"Height in pixels."},"asset_type":{"type":["string","null"],"description":"image, video, thumbnail or avatar."},"variant":{"type":["string","null"],"description":"Source variant when known."},"expires_at":{"type":["string","null"],"description":"Expiry timestamp when known."}}}}}}}}}}}]}}}},"400":{"$ref":"#/components/responses/InvalidInput"},"401":{"$ref":"#/components/responses/InvalidApiKey"},"402":{"$ref":"#/components/responses/InsufficientCredits"},"403":{"$ref":"#/components/responses/SourceRestricted"},"404":{"$ref":"#/components/responses/ResourceNotFound"},"408":{"$ref":"#/components/responses/SourceTimeout"},"422":{"$ref":"#/components/responses/SourceResponseChanged"},"429":{"$ref":"#/components/responses/TemporaryCapacity"},"501":{"$ref":"#/components/responses/SourceNotImplemented"},"503":{"$ref":"#/components/responses/SourceUnavailable"}},"x-availability":"preview","x-identifier-one-of":["handle"],"x-credits":2,"x-source-access":"public_page","x-preview":true,"x-codeSamples":[{"lang":"curl","source":"curl 'https://api.socialdatakit.com/v3/tiktok/profile/videos?handle=tiktok' \\\n  -H 'x-api-key: YOUR_API_KEY'"},{"lang":"javascript","source":"const response = await fetch(\"https://api.socialdatakit.com/v3/tiktok/profile/videos?handle=tiktok\", {\n  headers: { \"x-api-key\": process.env.SOCIALDATAKIT_API_KEY }\n});\nif (!response.ok) throw new Error(await response.text());\nconst result = await response.json();"},{"lang":"python","source":"import os\nimport requests\n\nresponse = requests.get(\n    \"https://api.socialdatakit.com/v3/tiktok/profile/videos?handle=tiktok\",\n    headers={\"x-api-key\": os.environ[\"SOCIALDATAKIT_API_KEY\"]},\n    timeout=30,\n)\nresponse.raise_for_status()\nresult = response.json()"}],"x-response-fields":{"id":{"type":"string","description":"Resource identifier used by this endpoint."},"author":{"type":"string","description":"Public creator name or handle."},"published_at":{"type":"string","description":"Source publication date or timestamp; null when absent."},"views":{"type":"number","description":"Observed views, where exposed by this source."},"likes":{"type":"number","description":"Observed likes."},"comments":{"type":"number","description":"Observed comment count, not comment rows."},"media_url":{"type":"string","description":"Preview image URL; not a guaranteed downloadable video."},"permalink":{"type":"string","description":"Public content URL."},"duration_seconds":{"type":"number","description":"Duration in seconds when returned."},"hashtags":{"type":"array","description":"Hashtags with platform or derived_text provenance.","items":{"type":"object","description":"Entity observed at source or derived from text.","properties":{"name":{"type":"string","description":"Hashtag or account name."},"id":{"type":"string","description":"Platform ID when supplied."},"source":{"type":"string","description":"platform or derived_text."}}}},"mentions":{"type":"array","description":"Mentions with platform or derived_text provenance; text is not proof of an account relationship.","items":{"type":"object","description":"Entity observed at source or derived from text.","properties":{"name":{"type":"string","description":"Hashtag or account name."},"id":{"type":"string","description":"Platform ID when supplied."},"source":{"type":"string","description":"platform or derived_text."}}}},"caption":{"type":"string","description":"Public video description."},"shares":{"type":"number","description":"Observed shares."},"favorites":{"type":"number","description":"Observed collect count; null when absent."},"width":{"type":"number","description":"Video width in pixels."},"height":{"type":"number","description":"Video height in pixels."},"author_id":{"type":"string","description":"Stable creator ID when returned."},"author_display_name":{"type":"string","description":"Public display name."},"author_verified":{"type":"boolean","description":"Explicit creator verification state."},"author_avatar_url":{"type":"string","description":"Public creator avatar URL."},"region_code":{"type":"string","description":"Source content region code when exposed; not proof of creator residence."},"video_url":{"type":"string","description":"Public playback URL when supplied; may expire or require source request headers."},"subtitle_tracks":{"type":"array","description":"Subtitle links exposed by the public video; does not run transcription.","items":{"type":"object","description":"Subtitle track.","properties":{"language":{"type":"string","description":"Source language code."},"language_id":{"type":"string","description":"Source language identifier."},"url":{"type":"string","description":"Source subtitle URL."},"format":{"type":"string","description":"Subtitle format."}}}},"effects":{"type":"array","description":"Effect metadata exposed by the public page.","items":{"type":"object","description":"Effect.","properties":{"id":{"type":"string","description":"Effect ID."},"name":{"type":"string","description":"Effect name."}}}},"stickers":{"type":"array","description":"Sticker metadata exposed by the public page.","items":{"type":"object","description":"Sticker.","properties":{"type":{"type":"number","description":"Source sticker type."},"texts":{"type":"array","description":"Returned sticker text.","items":{"type":"string","description":"Text."}}}}},"music":{"type":"object","description":"Sound metadata from the public video.","properties":{"id":{"type":"string","description":"Sound ID."},"title":{"type":"string","description":"Sound title."},"author":{"type":"string","description":"Sound author."},"original":{"type":"boolean","description":"Source original-sound flag."},"duration_seconds":{"type":"number","description":"Sound duration."},"cover_url":{"type":"string","description":"Sound cover URL."},"play_url":{"type":"string","description":"Sound preview URL."}}},"playlist_id":{"type":"string","description":"Source playlist ID when returned."},"pinned":{"type":"boolean","description":"Explicit pinned-item state when returned."},"media_assets":{"type":"array","description":"Returned cover variants.","items":{"type":"object","description":"One source media variant; URLs may expire.","properties":{"url":{"type":"string","description":"Source URL."},"width":{"type":"number","description":"Width in pixels."},"height":{"type":"number","description":"Height in pixels."},"asset_type":{"type":"string","description":"image, video, thumbnail or avatar."},"variant":{"type":"string","description":"Source variant when known."},"expires_at":{"type":"string","description":"Expiry timestamp when known."}}}}}}},"/v2/tiktok/video":{"get":{"operationId":"tiktok_v2_video","summary":"TikTok video","description":"Get a public video's caption, creator, cover and metrics. Preview: evaluate live availability and source coverage before customer use.","tags":["tiktok"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"url","in":"query","required":true,"schema":{"type":"string","pattern":"^https?://[^\\s]{5,400}$","example":"https://www.tiktok.com/@tiktok/video/7350000000000000000"},"description":"Required tiktok url."},{"name":"cache_max_age","in":"query","required":false,"schema":{"type":"string","enum":["1d","3d","7d","14d","30d"]},"description":"Maximum acceptable cache age. Valid cache hits cost zero credits."},{"name":"fields","in":"query","required":false,"schema":{"type":"string","example":"item"},"description":"Comma-separated fields or dot paths, including inside arrays such as items.id. Response identity and pagination are retained."},{"name":"trim","in":"query","required":false,"schema":{"type":"boolean","default":false},"description":"Remove null and empty values. Meaningful empty YouTube region-restriction lists are retained."}],"responses":{"200":{"description":"Normalized resource","headers":{"x-request-id":{"schema":{"type":"string"}},"x-data-mode":{"schema":{"type":"string","enum":["live","sandbox"]}},"x-cache":{"schema":{"type":"string","enum":["HIT","MISS"]}},"x-credits-charged":{"schema":{"type":"integer"}},"x-credits-remaining":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"data":{"type":"object","properties":{"item":{"type":"object","additionalProperties":true,"properties":{"id":{"type":["string","null"],"description":"Resource identifier used by this endpoint."},"author":{"type":["string","null"],"description":"Public creator name or handle."},"published_at":{"type":["string","null"],"description":"Source publication date or timestamp; null when absent."},"views":{"type":["number","null"],"description":"Observed views, where exposed by this source."},"likes":{"type":["number","null"],"description":"Observed likes."},"comments":{"type":["number","null"],"description":"Observed comment count, not comment rows."},"media_url":{"type":["string","null"],"description":"Preview image URL; not a guaranteed downloadable video."},"permalink":{"type":["string","null"],"description":"Public content URL."},"duration_seconds":{"type":["number","null"],"description":"Duration in seconds when returned."},"hashtags":{"type":["array","null"],"description":"Hashtags with platform or derived_text provenance.","items":{"type":["object","null"],"description":"Entity observed at source or derived from text.","properties":{"name":{"type":["string","null"],"description":"Hashtag or account name."},"id":{"type":["string","null"],"description":"Platform ID when supplied."},"source":{"type":["string","null"],"description":"platform or derived_text."}}}},"mentions":{"type":["array","null"],"description":"Mentions with platform or derived_text provenance; text is not proof of an account relationship.","items":{"type":["object","null"],"description":"Entity observed at source or derived from text.","properties":{"name":{"type":["string","null"],"description":"Hashtag or account name."},"id":{"type":["string","null"],"description":"Platform ID when supplied."},"source":{"type":["string","null"],"description":"platform or derived_text."}}}},"caption":{"type":["string","null"],"description":"Public video description."},"shares":{"type":["number","null"],"description":"Observed shares."},"favorites":{"type":["number","null"],"description":"Observed collect count; null when absent."},"width":{"type":["number","null"],"description":"Video width in pixels."},"height":{"type":["number","null"],"description":"Video height in pixels."},"author_id":{"type":["string","null"],"description":"Stable creator ID when returned."},"author_display_name":{"type":["string","null"],"description":"Public display name."},"author_verified":{"type":["boolean","null"],"description":"Explicit creator verification state."},"author_avatar_url":{"type":["string","null"],"description":"Public creator avatar URL."},"region_code":{"type":["string","null"],"description":"Source content region code when exposed; not proof of creator residence."},"video_url":{"type":["string","null"],"description":"Public playback URL when supplied; may expire or require source request headers."},"subtitle_tracks":{"type":["array","null"],"description":"Subtitle links exposed by the public video; does not run transcription.","items":{"type":["object","null"],"description":"Subtitle track.","properties":{"language":{"type":["string","null"],"description":"Source language code."},"language_id":{"type":["string","null"],"description":"Source language identifier."},"url":{"type":["string","null"],"description":"Source subtitle URL."},"format":{"type":["string","null"],"description":"Subtitle format."}}}},"effects":{"type":["array","null"],"description":"Effect metadata exposed by the public page.","items":{"type":["object","null"],"description":"Effect.","properties":{"id":{"type":["string","null"],"description":"Effect ID."},"name":{"type":["string","null"],"description":"Effect name."}}}},"stickers":{"type":["array","null"],"description":"Sticker metadata exposed by the public page.","items":{"type":["object","null"],"description":"Sticker.","properties":{"type":{"type":["number","null"],"description":"Source sticker type."},"texts":{"type":["array","null"],"description":"Returned sticker text.","items":{"type":["string","null"],"description":"Text."}}}}},"music":{"type":["object","null"],"description":"Sound metadata from the public video.","properties":{"id":{"type":["string","null"],"description":"Sound ID."},"title":{"type":["string","null"],"description":"Sound title."},"author":{"type":["string","null"],"description":"Sound author."},"original":{"type":["boolean","null"],"description":"Source original-sound flag."},"duration_seconds":{"type":["number","null"],"description":"Sound duration."},"cover_url":{"type":["string","null"],"description":"Sound cover URL."},"play_url":{"type":["string","null"],"description":"Sound preview URL."}}},"playlist_id":{"type":["string","null"],"description":"Source playlist ID when returned."},"pinned":{"type":["boolean","null"],"description":"Explicit pinned-item state when returned."},"media_assets":{"type":["array","null"],"description":"Returned cover variants.","items":{"type":["object","null"],"description":"One source media variant; URLs may expire.","properties":{"url":{"type":["string","null"],"description":"Source URL."},"width":{"type":["number","null"],"description":"Width in pixels."},"height":{"type":["number","null"],"description":"Height in pixels."},"asset_type":{"type":["string","null"],"description":"image, video, thumbnail or avatar."},"variant":{"type":["string","null"],"description":"Source variant when known."},"expires_at":{"type":["string","null"],"description":"Expiry timestamp when known."}}}}}}}}}}]}}}},"400":{"$ref":"#/components/responses/InvalidInput"},"401":{"$ref":"#/components/responses/InvalidApiKey"},"402":{"$ref":"#/components/responses/InsufficientCredits"},"403":{"$ref":"#/components/responses/SourceRestricted"},"404":{"$ref":"#/components/responses/ResourceNotFound"},"408":{"$ref":"#/components/responses/SourceTimeout"},"422":{"$ref":"#/components/responses/SourceResponseChanged"},"429":{"$ref":"#/components/responses/TemporaryCapacity"},"501":{"$ref":"#/components/responses/SourceNotImplemented"},"503":{"$ref":"#/components/responses/SourceUnavailable"}},"x-availability":"preview","x-identifier-one-of":["url"],"x-credits":1,"x-source-access":"public_page","x-preview":true,"x-codeSamples":[{"lang":"curl","source":"curl 'https://api.socialdatakit.com/v2/tiktok/video?url=https%3A%2F%2Fwww.tiktok.com%2F%40tiktok%2Fvideo%2F7350000000000000000' \\\n  -H 'x-api-key: YOUR_API_KEY'"},{"lang":"javascript","source":"const response = await fetch(\"https://api.socialdatakit.com/v2/tiktok/video?url=https%3A%2F%2Fwww.tiktok.com%2F%40tiktok%2Fvideo%2F7350000000000000000\", {\n  headers: { \"x-api-key\": process.env.SOCIALDATAKIT_API_KEY }\n});\nif (!response.ok) throw new Error(await response.text());\nconst result = await response.json();"},{"lang":"python","source":"import os\nimport requests\n\nresponse = requests.get(\n    \"https://api.socialdatakit.com/v2/tiktok/video?url=https%3A%2F%2Fwww.tiktok.com%2F%40tiktok%2Fvideo%2F7350000000000000000\",\n    headers={\"x-api-key\": os.environ[\"SOCIALDATAKIT_API_KEY\"]},\n    timeout=30,\n)\nresponse.raise_for_status()\nresult = response.json()"}],"x-response-fields":{"id":{"type":"string","description":"Resource identifier used by this endpoint."},"author":{"type":"string","description":"Public creator name or handle."},"published_at":{"type":"string","description":"Source publication date or timestamp; null when absent."},"views":{"type":"number","description":"Observed views, where exposed by this source."},"likes":{"type":"number","description":"Observed likes."},"comments":{"type":"number","description":"Observed comment count, not comment rows."},"media_url":{"type":"string","description":"Preview image URL; not a guaranteed downloadable video."},"permalink":{"type":"string","description":"Public content URL."},"duration_seconds":{"type":"number","description":"Duration in seconds when returned."},"hashtags":{"type":"array","description":"Hashtags with platform or derived_text provenance.","items":{"type":"object","description":"Entity observed at source or derived from text.","properties":{"name":{"type":"string","description":"Hashtag or account name."},"id":{"type":"string","description":"Platform ID when supplied."},"source":{"type":"string","description":"platform or derived_text."}}}},"mentions":{"type":"array","description":"Mentions with platform or derived_text provenance; text is not proof of an account relationship.","items":{"type":"object","description":"Entity observed at source or derived from text.","properties":{"name":{"type":"string","description":"Hashtag or account name."},"id":{"type":"string","description":"Platform ID when supplied."},"source":{"type":"string","description":"platform or derived_text."}}}},"caption":{"type":"string","description":"Public video description."},"shares":{"type":"number","description":"Observed shares."},"favorites":{"type":"number","description":"Observed collect count; null when absent."},"width":{"type":"number","description":"Video width in pixels."},"height":{"type":"number","description":"Video height in pixels."},"author_id":{"type":"string","description":"Stable creator ID when returned."},"author_display_name":{"type":"string","description":"Public display name."},"author_verified":{"type":"boolean","description":"Explicit creator verification state."},"author_avatar_url":{"type":"string","description":"Public creator avatar URL."},"region_code":{"type":"string","description":"Source content region code when exposed; not proof of creator residence."},"video_url":{"type":"string","description":"Public playback URL when supplied; may expire or require source request headers."},"subtitle_tracks":{"type":"array","description":"Subtitle links exposed by the public video; does not run transcription.","items":{"type":"object","description":"Subtitle track.","properties":{"language":{"type":"string","description":"Source language code."},"language_id":{"type":"string","description":"Source language identifier."},"url":{"type":"string","description":"Source subtitle URL."},"format":{"type":"string","description":"Subtitle format."}}}},"effects":{"type":"array","description":"Effect metadata exposed by the public page.","items":{"type":"object","description":"Effect.","properties":{"id":{"type":"string","description":"Effect ID."},"name":{"type":"string","description":"Effect name."}}}},"stickers":{"type":"array","description":"Sticker metadata exposed by the public page.","items":{"type":"object","description":"Sticker.","properties":{"type":{"type":"number","description":"Source sticker type."},"texts":{"type":"array","description":"Returned sticker text.","items":{"type":"string","description":"Text."}}}}},"music":{"type":"object","description":"Sound metadata from the public video.","properties":{"id":{"type":"string","description":"Sound ID."},"title":{"type":"string","description":"Sound title."},"author":{"type":"string","description":"Sound author."},"original":{"type":"boolean","description":"Source original-sound flag."},"duration_seconds":{"type":"number","description":"Sound duration."},"cover_url":{"type":"string","description":"Sound cover URL."},"play_url":{"type":"string","description":"Sound preview URL."}}},"playlist_id":{"type":"string","description":"Source playlist ID when returned."},"pinned":{"type":"boolean","description":"Explicit pinned-item state when returned."},"media_assets":{"type":"array","description":"Returned cover variants.","items":{"type":"object","description":"One source media variant; URLs may expire.","properties":{"url":{"type":"string","description":"Source URL."},"width":{"type":"number","description":"Width in pixels."},"height":{"type":"number","description":"Height in pixels."},"asset_type":{"type":"string","description":"image, video, thumbnail or avatar."},"variant":{"type":"string","description":"Source variant when known."},"expires_at":{"type":"string","description":"Expiry timestamp when known."}}}}}}},"/v1/tiktok/video/comments":{"get":{"operationId":"tiktok_v1_video_comments","summary":"TikTok video comments","description":"Get public comments on a video. Preview: evaluate live availability and source coverage before customer use.","tags":["tiktok"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"url","in":"query","required":true,"schema":{"type":"string","pattern":"^https?://[^\\s]{5,400}$","example":"https://www.tiktok.com/@tiktok/video/7350000000000000000"},"description":"Required tiktok url."},{"name":"cache_max_age","in":"query","required":false,"schema":{"type":"string","enum":["1d","3d","7d","14d","30d"]},"description":"Maximum acceptable cache age. Valid cache hits cost zero credits."},{"name":"fields","in":"query","required":false,"schema":{"type":"string","example":"items"},"description":"Comma-separated fields or dot paths, including inside arrays such as items.id. Response identity and pagination are retained."},{"name":"trim","in":"query","required":false,"schema":{"type":"boolean","default":false},"description":"Remove null and empty values. Meaningful empty YouTube region-restriction lists are retained."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":20,"default":3},"description":"Number of items to return."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"},"description":"Opaque pagination value returned as data.pagination.next_cursor. Keep the identifier, filters and limit unchanged."}],"responses":{"200":{"description":"Normalized resource","headers":{"x-request-id":{"schema":{"type":"string"}},"x-data-mode":{"schema":{"type":"string","enum":["live","sandbox"]}},"x-cache":{"schema":{"type":"string","enum":["HIT","MISS"]}},"x-credits-charged":{"schema":{"type":"integer"}},"x-credits-remaining":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"data":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","additionalProperties":true,"properties":{"id":{"type":["string","null"],"description":"Platform comment ID, retained as a string."},"content_id":{"type":["string","null"],"description":"Parent video/post ID when known."},"parent_comment_id":{"type":["string","null"],"description":"Top-level comment ID for a reply; null for a top-level comment or unknown parent."},"text":{"type":["string","null"],"description":"Public comment text. YouTube requests plainText formatting; no owner-only textOriginal."},"likes":{"type":["number","null"],"description":"Observed comment likes."},"reply_count":{"type":["number","null"],"description":"Observed total reply count; not the number of replies returned."},"author_id":{"type":["string","null"],"description":"Public author account ID."},"author_username":{"type":["string","null"],"description":"Public author handle."},"author_display_name":{"type":["string","null"],"description":"Public display name."},"author_avatar_url":{"type":["string","null"],"description":"Public avatar URL."},"author_profile_url":{"type":["string","null"],"description":"Public author profile URL."},"published_at":{"type":["string","null"],"description":"Comment publication timestamp."},"updated_at":{"type":["string","null"],"description":"Source edit timestamp when available."}}}}}}}}]}}}},"400":{"$ref":"#/components/responses/InvalidInput"},"401":{"$ref":"#/components/responses/InvalidApiKey"},"402":{"$ref":"#/components/responses/InsufficientCredits"},"403":{"$ref":"#/components/responses/SourceRestricted"},"404":{"$ref":"#/components/responses/ResourceNotFound"},"408":{"$ref":"#/components/responses/SourceTimeout"},"422":{"$ref":"#/components/responses/SourceResponseChanged"},"429":{"$ref":"#/components/responses/TemporaryCapacity"},"501":{"$ref":"#/components/responses/SourceNotImplemented"},"503":{"$ref":"#/components/responses/SourceUnavailable"}},"x-availability":"preview","x-identifier-one-of":["url"],"x-credits":2,"x-source-access":"public_page","x-preview":true,"x-codeSamples":[{"lang":"curl","source":"curl 'https://api.socialdatakit.com/v1/tiktok/video/comments?url=https%3A%2F%2Fwww.tiktok.com%2F%40tiktok%2Fvideo%2F7350000000000000000' \\\n  -H 'x-api-key: YOUR_API_KEY'"},{"lang":"javascript","source":"const response = await fetch(\"https://api.socialdatakit.com/v1/tiktok/video/comments?url=https%3A%2F%2Fwww.tiktok.com%2F%40tiktok%2Fvideo%2F7350000000000000000\", {\n  headers: { \"x-api-key\": process.env.SOCIALDATAKIT_API_KEY }\n});\nif (!response.ok) throw new Error(await response.text());\nconst result = await response.json();"},{"lang":"python","source":"import os\nimport requests\n\nresponse = requests.get(\n    \"https://api.socialdatakit.com/v1/tiktok/video/comments?url=https%3A%2F%2Fwww.tiktok.com%2F%40tiktok%2Fvideo%2F7350000000000000000\",\n    headers={\"x-api-key\": os.environ[\"SOCIALDATAKIT_API_KEY\"]},\n    timeout=30,\n)\nresponse.raise_for_status()\nresult = response.json()"}],"x-response-fields":{"id":{"type":"string","description":"Platform comment ID, retained as a string."},"content_id":{"type":"string","description":"Parent video/post ID when known."},"parent_comment_id":{"type":"string","description":"Top-level comment ID for a reply; null for a top-level comment or unknown parent."},"text":{"type":"string","description":"Public comment text. YouTube requests plainText formatting; no owner-only textOriginal."},"likes":{"type":"number","description":"Observed comment likes."},"reply_count":{"type":"number","description":"Observed total reply count; not the number of replies returned."},"author_id":{"type":"string","description":"Public author account ID."},"author_username":{"type":"string","description":"Public author handle."},"author_display_name":{"type":"string","description":"Public display name."},"author_avatar_url":{"type":"string","description":"Public avatar URL."},"author_profile_url":{"type":"string","description":"Public author profile URL."},"published_at":{"type":"string","description":"Comment publication timestamp."},"updated_at":{"type":"string","description":"Source edit timestamp when available."}}}},"/v1/tiktok/song":{"get":{"operationId":"tiktok_v1_song","summary":"TikTok song","description":"Get a sound's title, creator, duration and usage count. Preview: evaluate live availability and source coverage before customer use.","tags":["tiktok"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"clipId","in":"query","required":false,"schema":{"type":"string","pattern":"^[0-9]{10,24}$","example":"6793970793613265670"},"description":"Required tiktok clipId. Supply exactly one of: clipId, id."},{"name":"cache_max_age","in":"query","required":false,"schema":{"type":"string","enum":["1d","3d","7d","14d","30d"]},"description":"Maximum acceptable cache age. Valid cache hits cost zero credits."},{"name":"fields","in":"query","required":false,"schema":{"type":"string","example":"item"},"description":"Comma-separated fields or dot paths, including inside arrays such as items.id. Response identity and pagination are retained."},{"name":"trim","in":"query","required":false,"schema":{"type":"boolean","default":false},"description":"Remove null and empty values. Meaningful empty YouTube region-restriction lists are retained."},{"name":"id","in":"query","required":false,"schema":{"type":"string","pattern":"^[0-9]{10,24}$"},"description":"Alternative to clipId. Supply exactly one identifier."}],"responses":{"200":{"description":"Normalized resource","headers":{"x-request-id":{"schema":{"type":"string"}},"x-data-mode":{"schema":{"type":"string","enum":["live","sandbox"]}},"x-cache":{"schema":{"type":"string","enum":["HIT","MISS"]}},"x-credits-charged":{"schema":{"type":"integer"}},"x-credits-remaining":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"data":{"type":"object","properties":{"item":{"type":"object","additionalProperties":true,"properties":{"id":{"type":["string","null"],"description":"Sound ID."},"title":{"type":["string","null"],"description":"Sound title."},"author":{"type":["string","null"],"description":"Public sound author."},"original":{"type":["boolean","null"],"description":"Explicit source original-sound flag."},"duration_seconds":{"type":["number","null"],"description":"Sound duration."},"cover_url":{"type":["string","null"],"description":"Cover URL."},"play_url":{"type":["string","null"],"description":"Source preview URL; may expire."},"content_count":{"type":["number","null"],"description":"Observed videos using the sound."},"permalink":{"type":["string","null"],"description":"Public sound URL."}}}}}}}]}}}},"400":{"$ref":"#/components/responses/InvalidInput"},"401":{"$ref":"#/components/responses/InvalidApiKey"},"402":{"$ref":"#/components/responses/InsufficientCredits"},"403":{"$ref":"#/components/responses/SourceRestricted"},"404":{"$ref":"#/components/responses/ResourceNotFound"},"408":{"$ref":"#/components/responses/SourceTimeout"},"422":{"$ref":"#/components/responses/SourceResponseChanged"},"429":{"$ref":"#/components/responses/TemporaryCapacity"},"501":{"$ref":"#/components/responses/SourceNotImplemented"},"503":{"$ref":"#/components/responses/SourceUnavailable"}},"x-availability":"preview","x-identifier-one-of":["clipId","id"],"x-credits":1,"x-source-access":"public_page","x-preview":true,"x-codeSamples":[{"lang":"curl","source":"curl 'https://api.socialdatakit.com/v1/tiktok/song?clipId=6793970793613265670' \\\n  -H 'x-api-key: YOUR_API_KEY'"},{"lang":"javascript","source":"const response = await fetch(\"https://api.socialdatakit.com/v1/tiktok/song?clipId=6793970793613265670\", {\n  headers: { \"x-api-key\": process.env.SOCIALDATAKIT_API_KEY }\n});\nif (!response.ok) throw new Error(await response.text());\nconst result = await response.json();"},{"lang":"python","source":"import os\nimport requests\n\nresponse = requests.get(\n    \"https://api.socialdatakit.com/v1/tiktok/song?clipId=6793970793613265670\",\n    headers={\"x-api-key\": os.environ[\"SOCIALDATAKIT_API_KEY\"]},\n    timeout=30,\n)\nresponse.raise_for_status()\nresult = response.json()"}],"x-response-fields":{"id":{"type":"string","description":"Sound ID."},"title":{"type":"string","description":"Sound title."},"author":{"type":"string","description":"Public sound author."},"original":{"type":"boolean","description":"Explicit source original-sound flag."},"duration_seconds":{"type":"number","description":"Sound duration."},"cover_url":{"type":"string","description":"Cover URL."},"play_url":{"type":"string","description":"Source preview URL; may expire."},"content_count":{"type":"number","description":"Observed videos using the sound."},"permalink":{"type":"string","description":"Public sound URL."}}}},"/v1/tiktok/song/videos":{"get":{"operationId":"tiktok_v1_song_videos","summary":"TikTok song videos","description":"Get public videos that use a specific sound. Preview: evaluate live availability and source coverage before customer use.","tags":["tiktok"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"clipId","in":"query","required":false,"schema":{"type":"string","pattern":"^[0-9]{10,24}$","example":"6793970793613265670"},"description":"Required tiktok clipId. Supply exactly one of: clipId, id."},{"name":"cache_max_age","in":"query","required":false,"schema":{"type":"string","enum":["1d","3d","7d","14d","30d"]},"description":"Maximum acceptable cache age. Valid cache hits cost zero credits."},{"name":"fields","in":"query","required":false,"schema":{"type":"string","example":"items"},"description":"Comma-separated fields or dot paths, including inside arrays such as items.id. Response identity and pagination are retained."},{"name":"trim","in":"query","required":false,"schema":{"type":"boolean","default":false},"description":"Remove null and empty values. Meaningful empty YouTube region-restriction lists are retained."},{"name":"id","in":"query","required":false,"schema":{"type":"string","pattern":"^[0-9]{10,24}$"},"description":"Alternative to clipId. Supply exactly one identifier."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":20,"default":3},"description":"Number of items to return."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"},"description":"Opaque pagination value returned as data.pagination.next_cursor. Keep the identifier, filters and limit unchanged."}],"responses":{"200":{"description":"Normalized resource","headers":{"x-request-id":{"schema":{"type":"string"}},"x-data-mode":{"schema":{"type":"string","enum":["live","sandbox"]}},"x-cache":{"schema":{"type":"string","enum":["HIT","MISS"]}},"x-credits-charged":{"schema":{"type":"integer"}},"x-credits-remaining":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"data":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","additionalProperties":true,"properties":{"id":{"type":["string","null"],"description":"Resource identifier used by this endpoint."},"author":{"type":["string","null"],"description":"Public creator name or handle."},"published_at":{"type":["string","null"],"description":"Source publication date or timestamp; null when absent."},"views":{"type":["number","null"],"description":"Observed views, where exposed by this source."},"likes":{"type":["number","null"],"description":"Observed likes."},"comments":{"type":["number","null"],"description":"Observed comment count, not comment rows."},"media_url":{"type":["string","null"],"description":"Preview image URL; not a guaranteed downloadable video."},"permalink":{"type":["string","null"],"description":"Public content URL."},"duration_seconds":{"type":["number","null"],"description":"Duration in seconds when returned."},"hashtags":{"type":["array","null"],"description":"Hashtags with platform or derived_text provenance.","items":{"type":["object","null"],"description":"Entity observed at source or derived from text.","properties":{"name":{"type":["string","null"],"description":"Hashtag or account name."},"id":{"type":["string","null"],"description":"Platform ID when supplied."},"source":{"type":["string","null"],"description":"platform or derived_text."}}}},"mentions":{"type":["array","null"],"description":"Mentions with platform or derived_text provenance; text is not proof of an account relationship.","items":{"type":["object","null"],"description":"Entity observed at source or derived from text.","properties":{"name":{"type":["string","null"],"description":"Hashtag or account name."},"id":{"type":["string","null"],"description":"Platform ID when supplied."},"source":{"type":["string","null"],"description":"platform or derived_text."}}}},"caption":{"type":["string","null"],"description":"Public video description."},"shares":{"type":["number","null"],"description":"Observed shares."},"favorites":{"type":["number","null"],"description":"Observed collect count; null when absent."},"width":{"type":["number","null"],"description":"Video width in pixels."},"height":{"type":["number","null"],"description":"Video height in pixels."},"author_id":{"type":["string","null"],"description":"Stable creator ID when returned."},"author_display_name":{"type":["string","null"],"description":"Public display name."},"author_verified":{"type":["boolean","null"],"description":"Explicit creator verification state."},"author_avatar_url":{"type":["string","null"],"description":"Public creator avatar URL."},"region_code":{"type":["string","null"],"description":"Source content region code when exposed; not proof of creator residence."},"video_url":{"type":["string","null"],"description":"Public playback URL when supplied; may expire or require source request headers."},"subtitle_tracks":{"type":["array","null"],"description":"Subtitle links exposed by the public video; does not run transcription.","items":{"type":["object","null"],"description":"Subtitle track.","properties":{"language":{"type":["string","null"],"description":"Source language code."},"language_id":{"type":["string","null"],"description":"Source language identifier."},"url":{"type":["string","null"],"description":"Source subtitle URL."},"format":{"type":["string","null"],"description":"Subtitle format."}}}},"effects":{"type":["array","null"],"description":"Effect metadata exposed by the public page.","items":{"type":["object","null"],"description":"Effect.","properties":{"id":{"type":["string","null"],"description":"Effect ID."},"name":{"type":["string","null"],"description":"Effect name."}}}},"stickers":{"type":["array","null"],"description":"Sticker metadata exposed by the public page.","items":{"type":["object","null"],"description":"Sticker.","properties":{"type":{"type":["number","null"],"description":"Source sticker type."},"texts":{"type":["array","null"],"description":"Returned sticker text.","items":{"type":["string","null"],"description":"Text."}}}}},"music":{"type":["object","null"],"description":"Sound metadata from the public video.","properties":{"id":{"type":["string","null"],"description":"Sound ID."},"title":{"type":["string","null"],"description":"Sound title."},"author":{"type":["string","null"],"description":"Sound author."},"original":{"type":["boolean","null"],"description":"Source original-sound flag."},"duration_seconds":{"type":["number","null"],"description":"Sound duration."},"cover_url":{"type":["string","null"],"description":"Sound cover URL."},"play_url":{"type":["string","null"],"description":"Sound preview URL."}}},"playlist_id":{"type":["string","null"],"description":"Source playlist ID when returned."},"pinned":{"type":["boolean","null"],"description":"Explicit pinned-item state when returned."},"media_assets":{"type":["array","null"],"description":"Returned cover variants.","items":{"type":["object","null"],"description":"One source media variant; URLs may expire.","properties":{"url":{"type":["string","null"],"description":"Source URL."},"width":{"type":["number","null"],"description":"Width in pixels."},"height":{"type":["number","null"],"description":"Height in pixels."},"asset_type":{"type":["string","null"],"description":"image, video, thumbnail or avatar."},"variant":{"type":["string","null"],"description":"Source variant when known."},"expires_at":{"type":["string","null"],"description":"Expiry timestamp when known."}}}}}}}}}}}]}}}},"400":{"$ref":"#/components/responses/InvalidInput"},"401":{"$ref":"#/components/responses/InvalidApiKey"},"402":{"$ref":"#/components/responses/InsufficientCredits"},"403":{"$ref":"#/components/responses/SourceRestricted"},"404":{"$ref":"#/components/responses/ResourceNotFound"},"408":{"$ref":"#/components/responses/SourceTimeout"},"422":{"$ref":"#/components/responses/SourceResponseChanged"},"429":{"$ref":"#/components/responses/TemporaryCapacity"},"501":{"$ref":"#/components/responses/SourceNotImplemented"},"503":{"$ref":"#/components/responses/SourceUnavailable"}},"x-availability":"preview","x-identifier-one-of":["clipId","id"],"x-credits":2,"x-source-access":"public_page","x-preview":true,"x-codeSamples":[{"lang":"curl","source":"curl 'https://api.socialdatakit.com/v1/tiktok/song/videos?clipId=6793970793613265670' \\\n  -H 'x-api-key: YOUR_API_KEY'"},{"lang":"javascript","source":"const response = await fetch(\"https://api.socialdatakit.com/v1/tiktok/song/videos?clipId=6793970793613265670\", {\n  headers: { \"x-api-key\": process.env.SOCIALDATAKIT_API_KEY }\n});\nif (!response.ok) throw new Error(await response.text());\nconst result = await response.json();"},{"lang":"python","source":"import os\nimport requests\n\nresponse = requests.get(\n    \"https://api.socialdatakit.com/v1/tiktok/song/videos?clipId=6793970793613265670\",\n    headers={\"x-api-key\": os.environ[\"SOCIALDATAKIT_API_KEY\"]},\n    timeout=30,\n)\nresponse.raise_for_status()\nresult = response.json()"}],"x-response-fields":{"id":{"type":"string","description":"Resource identifier used by this endpoint."},"author":{"type":"string","description":"Public creator name or handle."},"published_at":{"type":"string","description":"Source publication date or timestamp; null when absent."},"views":{"type":"number","description":"Observed views, where exposed by this source."},"likes":{"type":"number","description":"Observed likes."},"comments":{"type":"number","description":"Observed comment count, not comment rows."},"media_url":{"type":"string","description":"Preview image URL; not a guaranteed downloadable video."},"permalink":{"type":"string","description":"Public content URL."},"duration_seconds":{"type":"number","description":"Duration in seconds when returned."},"hashtags":{"type":"array","description":"Hashtags with platform or derived_text provenance.","items":{"type":"object","description":"Entity observed at source or derived from text.","properties":{"name":{"type":"string","description":"Hashtag or account name."},"id":{"type":"string","description":"Platform ID when supplied."},"source":{"type":"string","description":"platform or derived_text."}}}},"mentions":{"type":"array","description":"Mentions with platform or derived_text provenance; text is not proof of an account relationship.","items":{"type":"object","description":"Entity observed at source or derived from text.","properties":{"name":{"type":"string","description":"Hashtag or account name."},"id":{"type":"string","description":"Platform ID when supplied."},"source":{"type":"string","description":"platform or derived_text."}}}},"caption":{"type":"string","description":"Public video description."},"shares":{"type":"number","description":"Observed shares."},"favorites":{"type":"number","description":"Observed collect count; null when absent."},"width":{"type":"number","description":"Video width in pixels."},"height":{"type":"number","description":"Video height in pixels."},"author_id":{"type":"string","description":"Stable creator ID when returned."},"author_display_name":{"type":"string","description":"Public display name."},"author_verified":{"type":"boolean","description":"Explicit creator verification state."},"author_avatar_url":{"type":"string","description":"Public creator avatar URL."},"region_code":{"type":"string","description":"Source content region code when exposed; not proof of creator residence."},"video_url":{"type":"string","description":"Public playback URL when supplied; may expire or require source request headers."},"subtitle_tracks":{"type":"array","description":"Subtitle links exposed by the public video; does not run transcription.","items":{"type":"object","description":"Subtitle track.","properties":{"language":{"type":"string","description":"Source language code."},"language_id":{"type":"string","description":"Source language identifier."},"url":{"type":"string","description":"Source subtitle URL."},"format":{"type":"string","description":"Subtitle format."}}}},"effects":{"type":"array","description":"Effect metadata exposed by the public page.","items":{"type":"object","description":"Effect.","properties":{"id":{"type":"string","description":"Effect ID."},"name":{"type":"string","description":"Effect name."}}}},"stickers":{"type":"array","description":"Sticker metadata exposed by the public page.","items":{"type":"object","description":"Sticker.","properties":{"type":{"type":"number","description":"Source sticker type."},"texts":{"type":"array","description":"Returned sticker text.","items":{"type":"string","description":"Text."}}}}},"music":{"type":"object","description":"Sound metadata from the public video.","properties":{"id":{"type":"string","description":"Sound ID."},"title":{"type":"string","description":"Sound title."},"author":{"type":"string","description":"Sound author."},"original":{"type":"boolean","description":"Source original-sound flag."},"duration_seconds":{"type":"number","description":"Sound duration."},"cover_url":{"type":"string","description":"Sound cover URL."},"play_url":{"type":"string","description":"Sound preview URL."}}},"playlist_id":{"type":"string","description":"Source playlist ID when returned."},"pinned":{"type":"boolean","description":"Explicit pinned-item state when returned."},"media_assets":{"type":"array","description":"Returned cover variants.","items":{"type":"object","description":"One source media variant; URLs may expire.","properties":{"url":{"type":"string","description":"Source URL."},"width":{"type":"number","description":"Width in pixels."},"height":{"type":"number","description":"Height in pixels."},"asset_type":{"type":"string","description":"image, video, thumbnail or avatar."},"variant":{"type":"string","description":"Source variant when known."},"expires_at":{"type":"string","description":"Expiry timestamp when known."}}}}}}},"/v1/tiktok/video/transcript":{"get":{"operationId":"tiktok_v1_video_transcript","summary":"TikTok video transcript","description":"Get a transcript for a public video. Planned: returns 501 SOURCE_NOT_IMPLEMENTED; no collector or sample response is available and no credits are charged.","tags":["tiktok"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"url","in":"query","required":true,"schema":{"type":"string","pattern":"^https?://[^\\s]{5,400}$","example":"https://www.tiktok.com/@tiktok/video/7350000000000000000"},"description":"Required tiktok url."},{"name":"cache_max_age","in":"query","required":false,"schema":{"type":"string","enum":["1d","3d","7d","14d","30d"]},"description":"Maximum acceptable cache age. Valid cache hits cost zero credits."},{"name":"fields","in":"query","required":false,"schema":{"type":"string","example":"item"},"description":"Comma-separated fields or dot paths, including inside arrays such as items.id. Response identity and pagination are retained."},{"name":"trim","in":"query","required":false,"schema":{"type":"boolean","default":false},"description":"Remove null and empty values. Meaningful empty YouTube region-restriction lists are retained."},{"name":"lang","in":"query","required":false,"description":"Language","schema":{"type":"string","pattern":"^[a-z]{2}(-[A-Za-z0-9]{2,8})?$","example":"en"}}],"responses":{"200":{"description":"Normalized resource","headers":{"x-request-id":{"schema":{"type":"string"}},"x-data-mode":{"schema":{"type":"string","enum":["live","sandbox"]}},"x-cache":{"schema":{"type":"string","enum":["HIT","MISS"]}},"x-credits-charged":{"schema":{"type":"integer"}},"x-credits-remaining":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"data":{"type":"object","properties":{"item":{"type":"object","additionalProperties":true,"properties":{"id":{"type":["string","null"],"description":"Resource identifier used by this endpoint."},"author":{"type":["string","null"],"description":"Public creator name or handle."},"published_at":{"type":["string","null"],"description":"Source publication date or timestamp; null when absent."},"views":{"type":["number","null"],"description":"Observed views, where exposed by this source."},"likes":{"type":["number","null"],"description":"Observed likes."},"comments":{"type":["number","null"],"description":"Observed comment count, not comment rows."},"media_url":{"type":["string","null"],"description":"Preview image URL; not a guaranteed downloadable video."},"permalink":{"type":["string","null"],"description":"Public content URL."},"duration_seconds":{"type":["number","null"],"description":"Duration in seconds when returned."},"hashtags":{"type":["array","null"],"description":"Hashtags with platform or derived_text provenance.","items":{"type":["object","null"],"description":"Entity observed at source or derived from text.","properties":{"name":{"type":["string","null"],"description":"Hashtag or account name."},"id":{"type":["string","null"],"description":"Platform ID when supplied."},"source":{"type":["string","null"],"description":"platform or derived_text."}}}},"mentions":{"type":["array","null"],"description":"Mentions with platform or derived_text provenance; text is not proof of an account relationship.","items":{"type":["object","null"],"description":"Entity observed at source or derived from text.","properties":{"name":{"type":["string","null"],"description":"Hashtag or account name."},"id":{"type":["string","null"],"description":"Platform ID when supplied."},"source":{"type":["string","null"],"description":"platform or derived_text."}}}},"caption":{"type":["string","null"],"description":"Public video description."},"shares":{"type":["number","null"],"description":"Observed shares."},"favorites":{"type":["number","null"],"description":"Observed collect count; null when absent."},"width":{"type":["number","null"],"description":"Video width in pixels."},"height":{"type":["number","null"],"description":"Video height in pixels."},"author_id":{"type":["string","null"],"description":"Stable creator ID when returned."},"author_display_name":{"type":["string","null"],"description":"Public display name."},"author_verified":{"type":["boolean","null"],"description":"Explicit creator verification state."},"author_avatar_url":{"type":["string","null"],"description":"Public creator avatar URL."},"region_code":{"type":["string","null"],"description":"Source content region code when exposed; not proof of creator residence."},"video_url":{"type":["string","null"],"description":"Public playback URL when supplied; may expire or require source request headers."},"subtitle_tracks":{"type":["array","null"],"description":"Subtitle links exposed by the public video; does not run transcription.","items":{"type":["object","null"],"description":"Subtitle track.","properties":{"language":{"type":["string","null"],"description":"Source language code."},"language_id":{"type":["string","null"],"description":"Source language identifier."},"url":{"type":["string","null"],"description":"Source subtitle URL."},"format":{"type":["string","null"],"description":"Subtitle format."}}}},"effects":{"type":["array","null"],"description":"Effect metadata exposed by the public page.","items":{"type":["object","null"],"description":"Effect.","properties":{"id":{"type":["string","null"],"description":"Effect ID."},"name":{"type":["string","null"],"description":"Effect name."}}}},"stickers":{"type":["array","null"],"description":"Sticker metadata exposed by the public page.","items":{"type":["object","null"],"description":"Sticker.","properties":{"type":{"type":["number","null"],"description":"Source sticker type."},"texts":{"type":["array","null"],"description":"Returned sticker text.","items":{"type":["string","null"],"description":"Text."}}}}},"music":{"type":["object","null"],"description":"Sound metadata from the public video.","properties":{"id":{"type":["string","null"],"description":"Sound ID."},"title":{"type":["string","null"],"description":"Sound title."},"author":{"type":["string","null"],"description":"Sound author."},"original":{"type":["boolean","null"],"description":"Source original-sound flag."},"duration_seconds":{"type":["number","null"],"description":"Sound duration."},"cover_url":{"type":["string","null"],"description":"Sound cover URL."},"play_url":{"type":["string","null"],"description":"Sound preview URL."}}},"playlist_id":{"type":["string","null"],"description":"Source playlist ID when returned."},"pinned":{"type":["boolean","null"],"description":"Explicit pinned-item state when returned."},"media_assets":{"type":["array","null"],"description":"Returned cover variants.","items":{"type":["object","null"],"description":"One source media variant; URLs may expire.","properties":{"url":{"type":["string","null"],"description":"Source URL."},"width":{"type":["number","null"],"description":"Width in pixels."},"height":{"type":["number","null"],"description":"Height in pixels."},"asset_type":{"type":["string","null"],"description":"image, video, thumbnail or avatar."},"variant":{"type":["string","null"],"description":"Source variant when known."},"expires_at":{"type":["string","null"],"description":"Expiry timestamp when known."}}}}}}}}}}]}}}},"400":{"$ref":"#/components/responses/InvalidInput"},"401":{"$ref":"#/components/responses/InvalidApiKey"},"402":{"$ref":"#/components/responses/InsufficientCredits"},"403":{"$ref":"#/components/responses/SourceRestricted"},"404":{"$ref":"#/components/responses/ResourceNotFound"},"408":{"$ref":"#/components/responses/SourceTimeout"},"422":{"$ref":"#/components/responses/SourceResponseChanged"},"429":{"$ref":"#/components/responses/TemporaryCapacity"},"501":{"$ref":"#/components/responses/SourceNotImplemented"},"503":{"$ref":"#/components/responses/SourceUnavailable"}},"x-availability":"planned","x-identifier-one-of":["url"],"x-credits":4,"x-source-access":"public_page","x-preview":true,"x-codeSamples":[{"lang":"curl","source":"curl 'https://api.socialdatakit.com/v1/tiktok/video/transcript?url=https%3A%2F%2Fwww.tiktok.com%2F%40tiktok%2Fvideo%2F7350000000000000000' \\\n  -H 'x-api-key: YOUR_API_KEY'"},{"lang":"javascript","source":"const response = await fetch(\"https://api.socialdatakit.com/v1/tiktok/video/transcript?url=https%3A%2F%2Fwww.tiktok.com%2F%40tiktok%2Fvideo%2F7350000000000000000\", {\n  headers: { \"x-api-key\": process.env.SOCIALDATAKIT_API_KEY }\n});\nif (!response.ok) throw new Error(await response.text());\nconst result = await response.json();"},{"lang":"python","source":"import os\nimport requests\n\nresponse = requests.get(\n    \"https://api.socialdatakit.com/v1/tiktok/video/transcript?url=https%3A%2F%2Fwww.tiktok.com%2F%40tiktok%2Fvideo%2F7350000000000000000\",\n    headers={\"x-api-key\": os.environ[\"SOCIALDATAKIT_API_KEY\"]},\n    timeout=30,\n)\nresponse.raise_for_status()\nresult = response.json()"}],"x-response-fields":{"id":{"type":"string","description":"Resource identifier used by this endpoint."},"author":{"type":"string","description":"Public creator name or handle."},"published_at":{"type":"string","description":"Source publication date or timestamp; null when absent."},"views":{"type":"number","description":"Observed views, where exposed by this source."},"likes":{"type":"number","description":"Observed likes."},"comments":{"type":"number","description":"Observed comment count, not comment rows."},"media_url":{"type":"string","description":"Preview image URL; not a guaranteed downloadable video."},"permalink":{"type":"string","description":"Public content URL."},"duration_seconds":{"type":"number","description":"Duration in seconds when returned."},"hashtags":{"type":"array","description":"Hashtags with platform or derived_text provenance.","items":{"type":"object","description":"Entity observed at source or derived from text.","properties":{"name":{"type":"string","description":"Hashtag or account name."},"id":{"type":"string","description":"Platform ID when supplied."},"source":{"type":"string","description":"platform or derived_text."}}}},"mentions":{"type":"array","description":"Mentions with platform or derived_text provenance; text is not proof of an account relationship.","items":{"type":"object","description":"Entity observed at source or derived from text.","properties":{"name":{"type":"string","description":"Hashtag or account name."},"id":{"type":"string","description":"Platform ID when supplied."},"source":{"type":"string","description":"platform or derived_text."}}}},"caption":{"type":"string","description":"Public video description."},"shares":{"type":"number","description":"Observed shares."},"favorites":{"type":"number","description":"Observed collect count; null when absent."},"width":{"type":"number","description":"Video width in pixels."},"height":{"type":"number","description":"Video height in pixels."},"author_id":{"type":"string","description":"Stable creator ID when returned."},"author_display_name":{"type":"string","description":"Public display name."},"author_verified":{"type":"boolean","description":"Explicit creator verification state."},"author_avatar_url":{"type":"string","description":"Public creator avatar URL."},"region_code":{"type":"string","description":"Source content region code when exposed; not proof of creator residence."},"video_url":{"type":"string","description":"Public playback URL when supplied; may expire or require source request headers."},"subtitle_tracks":{"type":"array","description":"Subtitle links exposed by the public video; does not run transcription.","items":{"type":"object","description":"Subtitle track.","properties":{"language":{"type":"string","description":"Source language code."},"language_id":{"type":"string","description":"Source language identifier."},"url":{"type":"string","description":"Source subtitle URL."},"format":{"type":"string","description":"Subtitle format."}}}},"effects":{"type":"array","description":"Effect metadata exposed by the public page.","items":{"type":"object","description":"Effect.","properties":{"id":{"type":"string","description":"Effect ID."},"name":{"type":"string","description":"Effect name."}}}},"stickers":{"type":"array","description":"Sticker metadata exposed by the public page.","items":{"type":"object","description":"Sticker.","properties":{"type":{"type":"number","description":"Source sticker type."},"texts":{"type":"array","description":"Returned sticker text.","items":{"type":"string","description":"Text."}}}}},"music":{"type":"object","description":"Sound metadata from the public video.","properties":{"id":{"type":"string","description":"Sound ID."},"title":{"type":"string","description":"Sound title."},"author":{"type":"string","description":"Sound author."},"original":{"type":"boolean","description":"Source original-sound flag."},"duration_seconds":{"type":"number","description":"Sound duration."},"cover_url":{"type":"string","description":"Sound cover URL."},"play_url":{"type":"string","description":"Sound preview URL."}}},"playlist_id":{"type":"string","description":"Source playlist ID when returned."},"pinned":{"type":"boolean","description":"Explicit pinned-item state when returned."},"media_assets":{"type":"array","description":"Returned cover variants.","items":{"type":"object","description":"One source media variant; URLs may expire.","properties":{"url":{"type":"string","description":"Source URL."},"width":{"type":"number","description":"Width in pixels."},"height":{"type":"number","description":"Height in pixels."},"asset_type":{"type":"string","description":"image, video, thumbnail or avatar."},"variant":{"type":"string","description":"Source variant when known."},"expires_at":{"type":"string","description":"Expiry timestamp when known."}}}}}}},"/v1/tiktok/search/users":{"get":{"operationId":"tiktok_v1_search_users","summary":"TikTok user search","description":"Search public TikTok accounts by keyword. Planned: returns 501 SOURCE_NOT_IMPLEMENTED; no collector or sample response is available and no credits are charged.","tags":["tiktok"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"query","in":"query","required":true,"schema":{"type":"string","pattern":"^.{1,180}$","example":"nasa"},"description":"Required tiktok query."},{"name":"cache_max_age","in":"query","required":false,"schema":{"type":"string","enum":["1d","3d","7d","14d","30d"]},"description":"Maximum acceptable cache age. Valid cache hits cost zero credits."},{"name":"fields","in":"query","required":false,"schema":{"type":"string","example":"items"},"description":"Comma-separated fields or dot paths, including inside arrays such as items.id. Response identity and pagination are retained."},{"name":"trim","in":"query","required":false,"schema":{"type":"boolean","default":false},"description":"Remove null and empty values. Meaningful empty YouTube region-restriction lists are retained."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":20,"default":3},"description":"Number of items to return."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"},"description":"Opaque pagination value returned as data.pagination.next_cursor. Keep the identifier, filters and limit unchanged."}],"responses":{"200":{"description":"Normalized resource","headers":{"x-request-id":{"schema":{"type":"string"}},"x-data-mode":{"schema":{"type":"string","enum":["live","sandbox"]}},"x-cache":{"schema":{"type":"string","enum":["HIT","MISS"]}},"x-credits-charged":{"schema":{"type":"integer"}},"x-credits-remaining":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"data":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","additionalProperties":true,"properties":{"id":{"type":["string","null"],"description":"Matched platform object ID."},"result_type":{"type":["string","null"],"description":"video, channel or playlist."},"title":{"type":["string","null"],"description":"Source title."},"description":{"type":["string","null"],"description":"Search snippet."},"channel_id":{"type":["string","null"],"description":"Owning channel ID."},"author":{"type":["string","null"],"description":"Channel name."},"published_at":{"type":["string","null"],"description":"Source publish time."},"thumbnails":{"type":["array","null"],"description":"All returned thumbnail variants; dimensions are source values.","items":{"type":["object","null"],"description":"Thumbnail.","properties":{"url":{"type":["string","null"],"description":"Source URL."},"variant":{"type":["string","null"],"description":"Source variant."},"width":{"type":["number","null"],"description":"Width."},"height":{"type":["number","null"],"description":"Height."},"asset_type":{"type":["string","null"],"description":"thumbnail."},"expires_at":{"type":["string","null"],"description":"Expiry when known."}}}},"live_status":{"type":["string","null"],"description":"Broadcast status."},"permalink":{"type":["string","null"],"description":"Public result URL."},"query":{"type":["string","null"],"description":"Query submitted."},"position":{"type":["number","null"],"description":"One-based position in this API result traversal, not personalized website ranking."},"region_code":{"type":["string","null"],"description":"Requested region, if specified."},"language":{"type":["string","null"],"description":"Requested relevance language, if specified."},"order":{"type":["string","null"],"description":"Requested sorting order."}}}}}}}}]}}}},"400":{"$ref":"#/components/responses/InvalidInput"},"401":{"$ref":"#/components/responses/InvalidApiKey"},"402":{"$ref":"#/components/responses/InsufficientCredits"},"403":{"$ref":"#/components/responses/SourceRestricted"},"404":{"$ref":"#/components/responses/ResourceNotFound"},"408":{"$ref":"#/components/responses/SourceTimeout"},"422":{"$ref":"#/components/responses/SourceResponseChanged"},"429":{"$ref":"#/components/responses/TemporaryCapacity"},"501":{"$ref":"#/components/responses/SourceNotImplemented"},"503":{"$ref":"#/components/responses/SourceUnavailable"}},"x-availability":"planned","x-identifier-one-of":["query"],"x-credits":3,"x-source-access":"public_page","x-preview":true,"x-codeSamples":[{"lang":"curl","source":"curl 'https://api.socialdatakit.com/v1/tiktok/search/users?query=nasa' \\\n  -H 'x-api-key: YOUR_API_KEY'"},{"lang":"javascript","source":"const response = await fetch(\"https://api.socialdatakit.com/v1/tiktok/search/users?query=nasa\", {\n  headers: { \"x-api-key\": process.env.SOCIALDATAKIT_API_KEY }\n});\nif (!response.ok) throw new Error(await response.text());\nconst result = await response.json();"},{"lang":"python","source":"import os\nimport requests\n\nresponse = requests.get(\n    \"https://api.socialdatakit.com/v1/tiktok/search/users?query=nasa\",\n    headers={\"x-api-key\": os.environ[\"SOCIALDATAKIT_API_KEY\"]},\n    timeout=30,\n)\nresponse.raise_for_status()\nresult = response.json()"}],"x-response-fields":{"id":{"type":"string","description":"Matched platform object ID."},"result_type":{"type":"string","description":"video, channel or playlist."},"title":{"type":"string","description":"Source title."},"description":{"type":"string","description":"Search snippet."},"channel_id":{"type":"string","description":"Owning channel ID."},"author":{"type":"string","description":"Channel name."},"published_at":{"type":"string","description":"Source publish time."},"thumbnails":{"type":"array","description":"All returned thumbnail variants; dimensions are source values.","items":{"type":"object","description":"Thumbnail.","properties":{"url":{"type":"string","description":"Source URL."},"variant":{"type":"string","description":"Source variant."},"width":{"type":"number","description":"Width."},"height":{"type":"number","description":"Height."},"asset_type":{"type":"string","description":"thumbnail."},"expires_at":{"type":"string","description":"Expiry when known."}}}},"live_status":{"type":"string","description":"Broadcast status."},"permalink":{"type":"string","description":"Public result URL."},"query":{"type":"string","description":"Query submitted."},"position":{"type":"number","description":"One-based position in this API result traversal, not personalized website ranking."},"region_code":{"type":"string","description":"Requested region, if specified."},"language":{"type":"string","description":"Requested relevance language, if specified."},"order":{"type":"string","description":"Requested sorting order."}}}},"/v1/tiktok/search/keyword":{"get":{"operationId":"tiktok_v1_search_keyword","summary":"TikTok keyword search","description":"Search public videos by keyword. Planned: returns 501 SOURCE_NOT_IMPLEMENTED; no collector or sample response is available and no credits are charged.","tags":["tiktok"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"query","in":"query","required":true,"schema":{"type":"string","pattern":"^.{1,180}$","example":"space"},"description":"Required tiktok query."},{"name":"cache_max_age","in":"query","required":false,"schema":{"type":"string","enum":["1d","3d","7d","14d","30d"]},"description":"Maximum acceptable cache age. Valid cache hits cost zero credits."},{"name":"fields","in":"query","required":false,"schema":{"type":"string","example":"items"},"description":"Comma-separated fields or dot paths, including inside arrays such as items.id. Response identity and pagination are retained."},{"name":"trim","in":"query","required":false,"schema":{"type":"boolean","default":false},"description":"Remove null and empty values. Meaningful empty YouTube region-restriction lists are retained."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":20,"default":3},"description":"Number of items to return."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"},"description":"Opaque pagination value returned as data.pagination.next_cursor. Keep the identifier, filters and limit unchanged."}],"responses":{"200":{"description":"Normalized resource","headers":{"x-request-id":{"schema":{"type":"string"}},"x-data-mode":{"schema":{"type":"string","enum":["live","sandbox"]}},"x-cache":{"schema":{"type":"string","enum":["HIT","MISS"]}},"x-credits-charged":{"schema":{"type":"integer"}},"x-credits-remaining":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"data":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","additionalProperties":true,"properties":{"id":{"type":["string","null"],"description":"Matched platform object ID."},"result_type":{"type":["string","null"],"description":"video, channel or playlist."},"title":{"type":["string","null"],"description":"Source title."},"description":{"type":["string","null"],"description":"Search snippet."},"channel_id":{"type":["string","null"],"description":"Owning channel ID."},"author":{"type":["string","null"],"description":"Channel name."},"published_at":{"type":["string","null"],"description":"Source publish time."},"thumbnails":{"type":["array","null"],"description":"All returned thumbnail variants; dimensions are source values.","items":{"type":["object","null"],"description":"Thumbnail.","properties":{"url":{"type":["string","null"],"description":"Source URL."},"variant":{"type":["string","null"],"description":"Source variant."},"width":{"type":["number","null"],"description":"Width."},"height":{"type":["number","null"],"description":"Height."},"asset_type":{"type":["string","null"],"description":"thumbnail."},"expires_at":{"type":["string","null"],"description":"Expiry when known."}}}},"live_status":{"type":["string","null"],"description":"Broadcast status."},"permalink":{"type":["string","null"],"description":"Public result URL."},"query":{"type":["string","null"],"description":"Query submitted."},"position":{"type":["number","null"],"description":"One-based position in this API result traversal, not personalized website ranking."},"region_code":{"type":["string","null"],"description":"Requested region, if specified."},"language":{"type":["string","null"],"description":"Requested relevance language, if specified."},"order":{"type":["string","null"],"description":"Requested sorting order."}}}}}}}}]}}}},"400":{"$ref":"#/components/responses/InvalidInput"},"401":{"$ref":"#/components/responses/InvalidApiKey"},"402":{"$ref":"#/components/responses/InsufficientCredits"},"403":{"$ref":"#/components/responses/SourceRestricted"},"404":{"$ref":"#/components/responses/ResourceNotFound"},"408":{"$ref":"#/components/responses/SourceTimeout"},"422":{"$ref":"#/components/responses/SourceResponseChanged"},"429":{"$ref":"#/components/responses/TemporaryCapacity"},"501":{"$ref":"#/components/responses/SourceNotImplemented"},"503":{"$ref":"#/components/responses/SourceUnavailable"}},"x-availability":"planned","x-identifier-one-of":["query"],"x-credits":3,"x-source-access":"public_page","x-preview":true,"x-codeSamples":[{"lang":"curl","source":"curl 'https://api.socialdatakit.com/v1/tiktok/search/keyword?query=space' \\\n  -H 'x-api-key: YOUR_API_KEY'"},{"lang":"javascript","source":"const response = await fetch(\"https://api.socialdatakit.com/v1/tiktok/search/keyword?query=space\", {\n  headers: { \"x-api-key\": process.env.SOCIALDATAKIT_API_KEY }\n});\nif (!response.ok) throw new Error(await response.text());\nconst result = await response.json();"},{"lang":"python","source":"import os\nimport requests\n\nresponse = requests.get(\n    \"https://api.socialdatakit.com/v1/tiktok/search/keyword?query=space\",\n    headers={\"x-api-key\": os.environ[\"SOCIALDATAKIT_API_KEY\"]},\n    timeout=30,\n)\nresponse.raise_for_status()\nresult = response.json()"}],"x-response-fields":{"id":{"type":"string","description":"Matched platform object ID."},"result_type":{"type":"string","description":"video, channel or playlist."},"title":{"type":"string","description":"Source title."},"description":{"type":"string","description":"Search snippet."},"channel_id":{"type":"string","description":"Owning channel ID."},"author":{"type":"string","description":"Channel name."},"published_at":{"type":"string","description":"Source publish time."},"thumbnails":{"type":"array","description":"All returned thumbnail variants; dimensions are source values.","items":{"type":"object","description":"Thumbnail.","properties":{"url":{"type":"string","description":"Source URL."},"variant":{"type":"string","description":"Source variant."},"width":{"type":"number","description":"Width."},"height":{"type":"number","description":"Height."},"asset_type":{"type":"string","description":"thumbnail."},"expires_at":{"type":"string","description":"Expiry when known."}}}},"live_status":{"type":"string","description":"Broadcast status."},"permalink":{"type":"string","description":"Public result URL."},"query":{"type":"string","description":"Query submitted."},"position":{"type":"number","description":"One-based position in this API result traversal, not personalized website ranking."},"region_code":{"type":"string","description":"Requested region, if specified."},"language":{"type":"string","description":"Requested relevance language, if specified."},"order":{"type":"string","description":"Requested sorting order."}}}},"/v1/tiktok/search/hashtag":{"get":{"operationId":"tiktok_v1_search_hashtag","summary":"TikTok hashtag search","description":"Search public hashtags by keyword. Planned: returns 501 SOURCE_NOT_IMPLEMENTED; no collector or sample response is available and no credits are charged.","tags":["tiktok"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"hashtag","in":"query","required":true,"schema":{"type":"string","pattern":"^[\\p{L}\\p{N}_]{1,100}$","example":"photography"},"description":"Required tiktok hashtag."},{"name":"cache_max_age","in":"query","required":false,"schema":{"type":"string","enum":["1d","3d","7d","14d","30d"]},"description":"Maximum acceptable cache age. Valid cache hits cost zero credits."},{"name":"fields","in":"query","required":false,"schema":{"type":"string","example":"items"},"description":"Comma-separated fields or dot paths, including inside arrays such as items.id. Response identity and pagination are retained."},{"name":"trim","in":"query","required":false,"schema":{"type":"boolean","default":false},"description":"Remove null and empty values. Meaningful empty YouTube region-restriction lists are retained."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":20,"default":3},"description":"Number of items to return."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"},"description":"Opaque pagination value returned as data.pagination.next_cursor. Keep the identifier, filters and limit unchanged."}],"responses":{"200":{"description":"Normalized resource","headers":{"x-request-id":{"schema":{"type":"string"}},"x-data-mode":{"schema":{"type":"string","enum":["live","sandbox"]}},"x-cache":{"schema":{"type":"string","enum":["HIT","MISS"]}},"x-credits-charged":{"schema":{"type":"integer"}},"x-credits-remaining":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"data":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","additionalProperties":true,"properties":{"id":{"type":["string","null"],"description":"Matched platform object ID."},"result_type":{"type":["string","null"],"description":"video, channel or playlist."},"title":{"type":["string","null"],"description":"Source title."},"description":{"type":["string","null"],"description":"Search snippet."},"channel_id":{"type":["string","null"],"description":"Owning channel ID."},"author":{"type":["string","null"],"description":"Channel name."},"published_at":{"type":["string","null"],"description":"Source publish time."},"thumbnails":{"type":["array","null"],"description":"All returned thumbnail variants; dimensions are source values.","items":{"type":["object","null"],"description":"Thumbnail.","properties":{"url":{"type":["string","null"],"description":"Source URL."},"variant":{"type":["string","null"],"description":"Source variant."},"width":{"type":["number","null"],"description":"Width."},"height":{"type":["number","null"],"description":"Height."},"asset_type":{"type":["string","null"],"description":"thumbnail."},"expires_at":{"type":["string","null"],"description":"Expiry when known."}}}},"live_status":{"type":["string","null"],"description":"Broadcast status."},"permalink":{"type":["string","null"],"description":"Public result URL."},"query":{"type":["string","null"],"description":"Query submitted."},"position":{"type":["number","null"],"description":"One-based position in this API result traversal, not personalized website ranking."},"region_code":{"type":["string","null"],"description":"Requested region, if specified."},"language":{"type":["string","null"],"description":"Requested relevance language, if specified."},"order":{"type":["string","null"],"description":"Requested sorting order."}}}}}}}}]}}}},"400":{"$ref":"#/components/responses/InvalidInput"},"401":{"$ref":"#/components/responses/InvalidApiKey"},"402":{"$ref":"#/components/responses/InsufficientCredits"},"403":{"$ref":"#/components/responses/SourceRestricted"},"404":{"$ref":"#/components/responses/ResourceNotFound"},"408":{"$ref":"#/components/responses/SourceTimeout"},"422":{"$ref":"#/components/responses/SourceResponseChanged"},"429":{"$ref":"#/components/responses/TemporaryCapacity"},"501":{"$ref":"#/components/responses/SourceNotImplemented"},"503":{"$ref":"#/components/responses/SourceUnavailable"}},"x-availability":"planned","x-identifier-one-of":["hashtag"],"x-credits":3,"x-source-access":"public_page","x-preview":true,"x-codeSamples":[{"lang":"curl","source":"curl 'https://api.socialdatakit.com/v1/tiktok/search/hashtag?hashtag=photography' \\\n  -H 'x-api-key: YOUR_API_KEY'"},{"lang":"javascript","source":"const response = await fetch(\"https://api.socialdatakit.com/v1/tiktok/search/hashtag?hashtag=photography\", {\n  headers: { \"x-api-key\": process.env.SOCIALDATAKIT_API_KEY }\n});\nif (!response.ok) throw new Error(await response.text());\nconst result = await response.json();"},{"lang":"python","source":"import os\nimport requests\n\nresponse = requests.get(\n    \"https://api.socialdatakit.com/v1/tiktok/search/hashtag?hashtag=photography\",\n    headers={\"x-api-key\": os.environ[\"SOCIALDATAKIT_API_KEY\"]},\n    timeout=30,\n)\nresponse.raise_for_status()\nresult = response.json()"}],"x-response-fields":{"id":{"type":"string","description":"Matched platform object ID."},"result_type":{"type":"string","description":"video, channel or playlist."},"title":{"type":"string","description":"Source title."},"description":{"type":"string","description":"Search snippet."},"channel_id":{"type":"string","description":"Owning channel ID."},"author":{"type":"string","description":"Channel name."},"published_at":{"type":"string","description":"Source publish time."},"thumbnails":{"type":"array","description":"All returned thumbnail variants; dimensions are source values.","items":{"type":"object","description":"Thumbnail.","properties":{"url":{"type":"string","description":"Source URL."},"variant":{"type":"string","description":"Source variant."},"width":{"type":"number","description":"Width."},"height":{"type":"number","description":"Height."},"asset_type":{"type":"string","description":"thumbnail."},"expires_at":{"type":"string","description":"Expiry when known."}}}},"live_status":{"type":"string","description":"Broadcast status."},"permalink":{"type":"string","description":"Public result URL."},"query":{"type":"string","description":"Query submitted."},"position":{"type":"number","description":"One-based position in this API result traversal, not personalized website ranking."},"region_code":{"type":"string","description":"Requested region, if specified."},"language":{"type":"string","description":"Requested relevance language, if specified."},"order":{"type":"string","description":"Requested sorting order."}}}},"/v1/tiktok/search/top":{"get":{"operationId":"tiktok_v1_search_top","summary":"TikTok top search","description":"Get the blended top results for a keyword. Planned: returns 501 SOURCE_NOT_IMPLEMENTED; no collector or sample response is available and no credits are charged.","tags":["tiktok"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"query","in":"query","required":true,"schema":{"type":"string","pattern":"^.{1,180}$","example":"space"},"description":"Required tiktok query."},{"name":"cache_max_age","in":"query","required":false,"schema":{"type":"string","enum":["1d","3d","7d","14d","30d"]},"description":"Maximum acceptable cache age. Valid cache hits cost zero credits."},{"name":"fields","in":"query","required":false,"schema":{"type":"string","example":"items"},"description":"Comma-separated fields or dot paths, including inside arrays such as items.id. Response identity and pagination are retained."},{"name":"trim","in":"query","required":false,"schema":{"type":"boolean","default":false},"description":"Remove null and empty values. Meaningful empty YouTube region-restriction lists are retained."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":20,"default":3},"description":"Number of items to return."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"},"description":"Opaque pagination value returned as data.pagination.next_cursor. Keep the identifier, filters and limit unchanged."}],"responses":{"200":{"description":"Normalized resource","headers":{"x-request-id":{"schema":{"type":"string"}},"x-data-mode":{"schema":{"type":"string","enum":["live","sandbox"]}},"x-cache":{"schema":{"type":"string","enum":["HIT","MISS"]}},"x-credits-charged":{"schema":{"type":"integer"}},"x-credits-remaining":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"data":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","additionalProperties":true,"properties":{"id":{"type":["string","null"],"description":"Matched platform object ID."},"result_type":{"type":["string","null"],"description":"video, channel or playlist."},"title":{"type":["string","null"],"description":"Source title."},"description":{"type":["string","null"],"description":"Search snippet."},"channel_id":{"type":["string","null"],"description":"Owning channel ID."},"author":{"type":["string","null"],"description":"Channel name."},"published_at":{"type":["string","null"],"description":"Source publish time."},"thumbnails":{"type":["array","null"],"description":"All returned thumbnail variants; dimensions are source values.","items":{"type":["object","null"],"description":"Thumbnail.","properties":{"url":{"type":["string","null"],"description":"Source URL."},"variant":{"type":["string","null"],"description":"Source variant."},"width":{"type":["number","null"],"description":"Width."},"height":{"type":["number","null"],"description":"Height."},"asset_type":{"type":["string","null"],"description":"thumbnail."},"expires_at":{"type":["string","null"],"description":"Expiry when known."}}}},"live_status":{"type":["string","null"],"description":"Broadcast status."},"permalink":{"type":["string","null"],"description":"Public result URL."},"query":{"type":["string","null"],"description":"Query submitted."},"position":{"type":["number","null"],"description":"One-based position in this API result traversal, not personalized website ranking."},"region_code":{"type":["string","null"],"description":"Requested region, if specified."},"language":{"type":["string","null"],"description":"Requested relevance language, if specified."},"order":{"type":["string","null"],"description":"Requested sorting order."}}}}}}}}]}}}},"400":{"$ref":"#/components/responses/InvalidInput"},"401":{"$ref":"#/components/responses/InvalidApiKey"},"402":{"$ref":"#/components/responses/InsufficientCredits"},"403":{"$ref":"#/components/responses/SourceRestricted"},"404":{"$ref":"#/components/responses/ResourceNotFound"},"408":{"$ref":"#/components/responses/SourceTimeout"},"422":{"$ref":"#/components/responses/SourceResponseChanged"},"429":{"$ref":"#/components/responses/TemporaryCapacity"},"501":{"$ref":"#/components/responses/SourceNotImplemented"},"503":{"$ref":"#/components/responses/SourceUnavailable"}},"x-availability":"planned","x-identifier-one-of":["query"],"x-credits":3,"x-source-access":"public_page","x-preview":true,"x-codeSamples":[{"lang":"curl","source":"curl 'https://api.socialdatakit.com/v1/tiktok/search/top?query=space' \\\n  -H 'x-api-key: YOUR_API_KEY'"},{"lang":"javascript","source":"const response = await fetch(\"https://api.socialdatakit.com/v1/tiktok/search/top?query=space\", {\n  headers: { \"x-api-key\": process.env.SOCIALDATAKIT_API_KEY }\n});\nif (!response.ok) throw new Error(await response.text());\nconst result = await response.json();"},{"lang":"python","source":"import os\nimport requests\n\nresponse = requests.get(\n    \"https://api.socialdatakit.com/v1/tiktok/search/top?query=space\",\n    headers={\"x-api-key\": os.environ[\"SOCIALDATAKIT_API_KEY\"]},\n    timeout=30,\n)\nresponse.raise_for_status()\nresult = response.json()"}],"x-response-fields":{"id":{"type":"string","description":"Matched platform object ID."},"result_type":{"type":"string","description":"video, channel or playlist."},"title":{"type":"string","description":"Source title."},"description":{"type":"string","description":"Search snippet."},"channel_id":{"type":"string","description":"Owning channel ID."},"author":{"type":"string","description":"Channel name."},"published_at":{"type":"string","description":"Source publish time."},"thumbnails":{"type":"array","description":"All returned thumbnail variants; dimensions are source values.","items":{"type":"object","description":"Thumbnail.","properties":{"url":{"type":"string","description":"Source URL."},"variant":{"type":"string","description":"Source variant."},"width":{"type":"number","description":"Width."},"height":{"type":"number","description":"Height."},"asset_type":{"type":"string","description":"thumbnail."},"expires_at":{"type":"string","description":"Expiry when known."}}}},"live_status":{"type":"string","description":"Broadcast status."},"permalink":{"type":"string","description":"Public result URL."},"query":{"type":"string","description":"Query submitted."},"position":{"type":"number","description":"One-based position in this API result traversal, not personalized website ranking."},"region_code":{"type":"string","description":"Requested region, if specified."},"language":{"type":"string","description":"Requested relevance language, if specified."},"order":{"type":"string","description":"Requested sorting order."}}}},"/v1/tiktok/user/following":{"get":{"operationId":"tiktok_v1_user_following","summary":"TikTok following","description":"Get accounts a public profile follows. Planned: returns 501 SOURCE_NOT_IMPLEMENTED; no collector or sample response is available and no credits are charged.","tags":["tiktok"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"handle","in":"query","required":true,"schema":{"type":"string","pattern":"^@?[A-Za-z0-9._]{2,24}$","example":"tiktok"},"description":"Required tiktok handle."},{"name":"cache_max_age","in":"query","required":false,"schema":{"type":"string","enum":["1d","3d","7d","14d","30d"]},"description":"Maximum acceptable cache age. Valid cache hits cost zero credits."},{"name":"fields","in":"query","required":false,"schema":{"type":"string","example":"items"},"description":"Comma-separated fields or dot paths, including inside arrays such as items.id. Response identity and pagination are retained."},{"name":"trim","in":"query","required":false,"schema":{"type":"boolean","default":false},"description":"Remove null and empty values. Meaningful empty YouTube region-restriction lists are retained."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":20,"default":3},"description":"Number of items to return."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"},"description":"Opaque pagination value returned as data.pagination.next_cursor. Keep the identifier, filters and limit unchanged."}],"responses":{"200":{"description":"Normalized resource","headers":{"x-request-id":{"schema":{"type":"string"}},"x-data-mode":{"schema":{"type":"string","enum":["live","sandbox"]}},"x-cache":{"schema":{"type":"string","enum":["HIT","MISS"]}},"x-credits-charged":{"schema":{"type":"integer"}},"x-credits-remaining":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"data":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","additionalProperties":true,"properties":{"id":{"type":["string","null"],"description":"Resource identifier used by this endpoint."},"author":{"type":["string","null"],"description":"Public creator name or handle."},"published_at":{"type":["string","null"],"description":"Source publication date or timestamp; null when absent."},"views":{"type":["number","null"],"description":"Observed views, where exposed by this source."},"likes":{"type":["number","null"],"description":"Observed likes."},"comments":{"type":["number","null"],"description":"Observed comment count, not comment rows."},"media_url":{"type":["string","null"],"description":"Preview image URL; not a guaranteed downloadable video."},"permalink":{"type":["string","null"],"description":"Public content URL."},"duration_seconds":{"type":["number","null"],"description":"Duration in seconds when returned."},"hashtags":{"type":["array","null"],"description":"Hashtags with platform or derived_text provenance.","items":{"type":["object","null"],"description":"Entity observed at source or derived from text.","properties":{"name":{"type":["string","null"],"description":"Hashtag or account name."},"id":{"type":["string","null"],"description":"Platform ID when supplied."},"source":{"type":["string","null"],"description":"platform or derived_text."}}}},"mentions":{"type":["array","null"],"description":"Mentions with platform or derived_text provenance; text is not proof of an account relationship.","items":{"type":["object","null"],"description":"Entity observed at source or derived from text.","properties":{"name":{"type":["string","null"],"description":"Hashtag or account name."},"id":{"type":["string","null"],"description":"Platform ID when supplied."},"source":{"type":["string","null"],"description":"platform or derived_text."}}}},"caption":{"type":["string","null"],"description":"Public video description."},"shares":{"type":["number","null"],"description":"Observed shares."},"favorites":{"type":["number","null"],"description":"Observed collect count; null when absent."},"width":{"type":["number","null"],"description":"Video width in pixels."},"height":{"type":["number","null"],"description":"Video height in pixels."},"author_id":{"type":["string","null"],"description":"Stable creator ID when returned."},"author_display_name":{"type":["string","null"],"description":"Public display name."},"author_verified":{"type":["boolean","null"],"description":"Explicit creator verification state."},"author_avatar_url":{"type":["string","null"],"description":"Public creator avatar URL."},"region_code":{"type":["string","null"],"description":"Source content region code when exposed; not proof of creator residence."},"video_url":{"type":["string","null"],"description":"Public playback URL when supplied; may expire or require source request headers."},"subtitle_tracks":{"type":["array","null"],"description":"Subtitle links exposed by the public video; does not run transcription.","items":{"type":["object","null"],"description":"Subtitle track.","properties":{"language":{"type":["string","null"],"description":"Source language code."},"language_id":{"type":["string","null"],"description":"Source language identifier."},"url":{"type":["string","null"],"description":"Source subtitle URL."},"format":{"type":["string","null"],"description":"Subtitle format."}}}},"effects":{"type":["array","null"],"description":"Effect metadata exposed by the public page.","items":{"type":["object","null"],"description":"Effect.","properties":{"id":{"type":["string","null"],"description":"Effect ID."},"name":{"type":["string","null"],"description":"Effect name."}}}},"stickers":{"type":["array","null"],"description":"Sticker metadata exposed by the public page.","items":{"type":["object","null"],"description":"Sticker.","properties":{"type":{"type":["number","null"],"description":"Source sticker type."},"texts":{"type":["array","null"],"description":"Returned sticker text.","items":{"type":["string","null"],"description":"Text."}}}}},"music":{"type":["object","null"],"description":"Sound metadata from the public video.","properties":{"id":{"type":["string","null"],"description":"Sound ID."},"title":{"type":["string","null"],"description":"Sound title."},"author":{"type":["string","null"],"description":"Sound author."},"original":{"type":["boolean","null"],"description":"Source original-sound flag."},"duration_seconds":{"type":["number","null"],"description":"Sound duration."},"cover_url":{"type":["string","null"],"description":"Sound cover URL."},"play_url":{"type":["string","null"],"description":"Sound preview URL."}}},"playlist_id":{"type":["string","null"],"description":"Source playlist ID when returned."},"pinned":{"type":["boolean","null"],"description":"Explicit pinned-item state when returned."},"media_assets":{"type":["array","null"],"description":"Returned cover variants.","items":{"type":["object","null"],"description":"One source media variant; URLs may expire.","properties":{"url":{"type":["string","null"],"description":"Source URL."},"width":{"type":["number","null"],"description":"Width in pixels."},"height":{"type":["number","null"],"description":"Height in pixels."},"asset_type":{"type":["string","null"],"description":"image, video, thumbnail or avatar."},"variant":{"type":["string","null"],"description":"Source variant when known."},"expires_at":{"type":["string","null"],"description":"Expiry timestamp when known."}}}}}}}}}}}]}}}},"400":{"$ref":"#/components/responses/InvalidInput"},"401":{"$ref":"#/components/responses/InvalidApiKey"},"402":{"$ref":"#/components/responses/InsufficientCredits"},"403":{"$ref":"#/components/responses/SourceRestricted"},"404":{"$ref":"#/components/responses/ResourceNotFound"},"408":{"$ref":"#/components/responses/SourceTimeout"},"422":{"$ref":"#/components/responses/SourceResponseChanged"},"429":{"$ref":"#/components/responses/TemporaryCapacity"},"501":{"$ref":"#/components/responses/SourceNotImplemented"},"503":{"$ref":"#/components/responses/SourceUnavailable"}},"x-availability":"planned","x-identifier-one-of":["handle"],"x-credits":2,"x-source-access":"public_page","x-preview":true,"x-codeSamples":[{"lang":"curl","source":"curl 'https://api.socialdatakit.com/v1/tiktok/user/following?handle=tiktok' \\\n  -H 'x-api-key: YOUR_API_KEY'"},{"lang":"javascript","source":"const response = await fetch(\"https://api.socialdatakit.com/v1/tiktok/user/following?handle=tiktok\", {\n  headers: { \"x-api-key\": process.env.SOCIALDATAKIT_API_KEY }\n});\nif (!response.ok) throw new Error(await response.text());\nconst result = await response.json();"},{"lang":"python","source":"import os\nimport requests\n\nresponse = requests.get(\n    \"https://api.socialdatakit.com/v1/tiktok/user/following?handle=tiktok\",\n    headers={\"x-api-key\": os.environ[\"SOCIALDATAKIT_API_KEY\"]},\n    timeout=30,\n)\nresponse.raise_for_status()\nresult = response.json()"}],"x-response-fields":{"id":{"type":"string","description":"Resource identifier used by this endpoint."},"author":{"type":"string","description":"Public creator name or handle."},"published_at":{"type":"string","description":"Source publication date or timestamp; null when absent."},"views":{"type":"number","description":"Observed views, where exposed by this source."},"likes":{"type":"number","description":"Observed likes."},"comments":{"type":"number","description":"Observed comment count, not comment rows."},"media_url":{"type":"string","description":"Preview image URL; not a guaranteed downloadable video."},"permalink":{"type":"string","description":"Public content URL."},"duration_seconds":{"type":"number","description":"Duration in seconds when returned."},"hashtags":{"type":"array","description":"Hashtags with platform or derived_text provenance.","items":{"type":"object","description":"Entity observed at source or derived from text.","properties":{"name":{"type":"string","description":"Hashtag or account name."},"id":{"type":"string","description":"Platform ID when supplied."},"source":{"type":"string","description":"platform or derived_text."}}}},"mentions":{"type":"array","description":"Mentions with platform or derived_text provenance; text is not proof of an account relationship.","items":{"type":"object","description":"Entity observed at source or derived from text.","properties":{"name":{"type":"string","description":"Hashtag or account name."},"id":{"type":"string","description":"Platform ID when supplied."},"source":{"type":"string","description":"platform or derived_text."}}}},"caption":{"type":"string","description":"Public video description."},"shares":{"type":"number","description":"Observed shares."},"favorites":{"type":"number","description":"Observed collect count; null when absent."},"width":{"type":"number","description":"Video width in pixels."},"height":{"type":"number","description":"Video height in pixels."},"author_id":{"type":"string","description":"Stable creator ID when returned."},"author_display_name":{"type":"string","description":"Public display name."},"author_verified":{"type":"boolean","description":"Explicit creator verification state."},"author_avatar_url":{"type":"string","description":"Public creator avatar URL."},"region_code":{"type":"string","description":"Source content region code when exposed; not proof of creator residence."},"video_url":{"type":"string","description":"Public playback URL when supplied; may expire or require source request headers."},"subtitle_tracks":{"type":"array","description":"Subtitle links exposed by the public video; does not run transcription.","items":{"type":"object","description":"Subtitle track.","properties":{"language":{"type":"string","description":"Source language code."},"language_id":{"type":"string","description":"Source language identifier."},"url":{"type":"string","description":"Source subtitle URL."},"format":{"type":"string","description":"Subtitle format."}}}},"effects":{"type":"array","description":"Effect metadata exposed by the public page.","items":{"type":"object","description":"Effect.","properties":{"id":{"type":"string","description":"Effect ID."},"name":{"type":"string","description":"Effect name."}}}},"stickers":{"type":"array","description":"Sticker metadata exposed by the public page.","items":{"type":"object","description":"Sticker.","properties":{"type":{"type":"number","description":"Source sticker type."},"texts":{"type":"array","description":"Returned sticker text.","items":{"type":"string","description":"Text."}}}}},"music":{"type":"object","description":"Sound metadata from the public video.","properties":{"id":{"type":"string","description":"Sound ID."},"title":{"type":"string","description":"Sound title."},"author":{"type":"string","description":"Sound author."},"original":{"type":"boolean","description":"Source original-sound flag."},"duration_seconds":{"type":"number","description":"Sound duration."},"cover_url":{"type":"string","description":"Sound cover URL."},"play_url":{"type":"string","description":"Sound preview URL."}}},"playlist_id":{"type":"string","description":"Source playlist ID when returned."},"pinned":{"type":"boolean","description":"Explicit pinned-item state when returned."},"media_assets":{"type":"array","description":"Returned cover variants.","items":{"type":"object","description":"One source media variant; URLs may expire.","properties":{"url":{"type":"string","description":"Source URL."},"width":{"type":"number","description":"Width in pixels."},"height":{"type":"number","description":"Height in pixels."},"asset_type":{"type":"string","description":"image, video, thumbnail or avatar."},"variant":{"type":"string","description":"Source variant when known."},"expires_at":{"type":"string","description":"Expiry timestamp when known."}}}}}}},"/v1/tiktok/user/followers":{"get":{"operationId":"tiktok_v1_user_followers","summary":"TikTok followers","description":"Get followers of a public profile. Planned: returns 501 SOURCE_NOT_IMPLEMENTED; no collector or sample response is available and no credits are charged.","tags":["tiktok"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"handle","in":"query","required":true,"schema":{"type":"string","pattern":"^@?[A-Za-z0-9._]{2,24}$","example":"tiktok"},"description":"Required tiktok handle."},{"name":"cache_max_age","in":"query","required":false,"schema":{"type":"string","enum":["1d","3d","7d","14d","30d"]},"description":"Maximum acceptable cache age. Valid cache hits cost zero credits."},{"name":"fields","in":"query","required":false,"schema":{"type":"string","example":"items"},"description":"Comma-separated fields or dot paths, including inside arrays such as items.id. Response identity and pagination are retained."},{"name":"trim","in":"query","required":false,"schema":{"type":"boolean","default":false},"description":"Remove null and empty values. Meaningful empty YouTube region-restriction lists are retained."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":20,"default":3},"description":"Number of items to return."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"},"description":"Opaque pagination value returned as data.pagination.next_cursor. Keep the identifier, filters and limit unchanged."}],"responses":{"200":{"description":"Normalized resource","headers":{"x-request-id":{"schema":{"type":"string"}},"x-data-mode":{"schema":{"type":"string","enum":["live","sandbox"]}},"x-cache":{"schema":{"type":"string","enum":["HIT","MISS"]}},"x-credits-charged":{"schema":{"type":"integer"}},"x-credits-remaining":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"data":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","additionalProperties":true,"properties":{"id":{"type":["string","null"],"description":"Resource identifier used by this endpoint."},"author":{"type":["string","null"],"description":"Public creator name or handle."},"published_at":{"type":["string","null"],"description":"Source publication date or timestamp; null when absent."},"views":{"type":["number","null"],"description":"Observed views, where exposed by this source."},"likes":{"type":["number","null"],"description":"Observed likes."},"comments":{"type":["number","null"],"description":"Observed comment count, not comment rows."},"media_url":{"type":["string","null"],"description":"Preview image URL; not a guaranteed downloadable video."},"permalink":{"type":["string","null"],"description":"Public content URL."},"duration_seconds":{"type":["number","null"],"description":"Duration in seconds when returned."},"hashtags":{"type":["array","null"],"description":"Hashtags with platform or derived_text provenance.","items":{"type":["object","null"],"description":"Entity observed at source or derived from text.","properties":{"name":{"type":["string","null"],"description":"Hashtag or account name."},"id":{"type":["string","null"],"description":"Platform ID when supplied."},"source":{"type":["string","null"],"description":"platform or derived_text."}}}},"mentions":{"type":["array","null"],"description":"Mentions with platform or derived_text provenance; text is not proof of an account relationship.","items":{"type":["object","null"],"description":"Entity observed at source or derived from text.","properties":{"name":{"type":["string","null"],"description":"Hashtag or account name."},"id":{"type":["string","null"],"description":"Platform ID when supplied."},"source":{"type":["string","null"],"description":"platform or derived_text."}}}},"caption":{"type":["string","null"],"description":"Public video description."},"shares":{"type":["number","null"],"description":"Observed shares."},"favorites":{"type":["number","null"],"description":"Observed collect count; null when absent."},"width":{"type":["number","null"],"description":"Video width in pixels."},"height":{"type":["number","null"],"description":"Video height in pixels."},"author_id":{"type":["string","null"],"description":"Stable creator ID when returned."},"author_display_name":{"type":["string","null"],"description":"Public display name."},"author_verified":{"type":["boolean","null"],"description":"Explicit creator verification state."},"author_avatar_url":{"type":["string","null"],"description":"Public creator avatar URL."},"region_code":{"type":["string","null"],"description":"Source content region code when exposed; not proof of creator residence."},"video_url":{"type":["string","null"],"description":"Public playback URL when supplied; may expire or require source request headers."},"subtitle_tracks":{"type":["array","null"],"description":"Subtitle links exposed by the public video; does not run transcription.","items":{"type":["object","null"],"description":"Subtitle track.","properties":{"language":{"type":["string","null"],"description":"Source language code."},"language_id":{"type":["string","null"],"description":"Source language identifier."},"url":{"type":["string","null"],"description":"Source subtitle URL."},"format":{"type":["string","null"],"description":"Subtitle format."}}}},"effects":{"type":["array","null"],"description":"Effect metadata exposed by the public page.","items":{"type":["object","null"],"description":"Effect.","properties":{"id":{"type":["string","null"],"description":"Effect ID."},"name":{"type":["string","null"],"description":"Effect name."}}}},"stickers":{"type":["array","null"],"description":"Sticker metadata exposed by the public page.","items":{"type":["object","null"],"description":"Sticker.","properties":{"type":{"type":["number","null"],"description":"Source sticker type."},"texts":{"type":["array","null"],"description":"Returned sticker text.","items":{"type":["string","null"],"description":"Text."}}}}},"music":{"type":["object","null"],"description":"Sound metadata from the public video.","properties":{"id":{"type":["string","null"],"description":"Sound ID."},"title":{"type":["string","null"],"description":"Sound title."},"author":{"type":["string","null"],"description":"Sound author."},"original":{"type":["boolean","null"],"description":"Source original-sound flag."},"duration_seconds":{"type":["number","null"],"description":"Sound duration."},"cover_url":{"type":["string","null"],"description":"Sound cover URL."},"play_url":{"type":["string","null"],"description":"Sound preview URL."}}},"playlist_id":{"type":["string","null"],"description":"Source playlist ID when returned."},"pinned":{"type":["boolean","null"],"description":"Explicit pinned-item state when returned."},"media_assets":{"type":["array","null"],"description":"Returned cover variants.","items":{"type":["object","null"],"description":"One source media variant; URLs may expire.","properties":{"url":{"type":["string","null"],"description":"Source URL."},"width":{"type":["number","null"],"description":"Width in pixels."},"height":{"type":["number","null"],"description":"Height in pixels."},"asset_type":{"type":["string","null"],"description":"image, video, thumbnail or avatar."},"variant":{"type":["string","null"],"description":"Source variant when known."},"expires_at":{"type":["string","null"],"description":"Expiry timestamp when known."}}}}}}}}}}}]}}}},"400":{"$ref":"#/components/responses/InvalidInput"},"401":{"$ref":"#/components/responses/InvalidApiKey"},"402":{"$ref":"#/components/responses/InsufficientCredits"},"403":{"$ref":"#/components/responses/SourceRestricted"},"404":{"$ref":"#/components/responses/ResourceNotFound"},"408":{"$ref":"#/components/responses/SourceTimeout"},"422":{"$ref":"#/components/responses/SourceResponseChanged"},"429":{"$ref":"#/components/responses/TemporaryCapacity"},"501":{"$ref":"#/components/responses/SourceNotImplemented"},"503":{"$ref":"#/components/responses/SourceUnavailable"}},"x-availability":"planned","x-identifier-one-of":["handle"],"x-credits":2,"x-source-access":"public_page","x-preview":true,"x-codeSamples":[{"lang":"curl","source":"curl 'https://api.socialdatakit.com/v1/tiktok/user/followers?handle=tiktok' \\\n  -H 'x-api-key: YOUR_API_KEY'"},{"lang":"javascript","source":"const response = await fetch(\"https://api.socialdatakit.com/v1/tiktok/user/followers?handle=tiktok\", {\n  headers: { \"x-api-key\": process.env.SOCIALDATAKIT_API_KEY }\n});\nif (!response.ok) throw new Error(await response.text());\nconst result = await response.json();"},{"lang":"python","source":"import os\nimport requests\n\nresponse = requests.get(\n    \"https://api.socialdatakit.com/v1/tiktok/user/followers?handle=tiktok\",\n    headers={\"x-api-key\": os.environ[\"SOCIALDATAKIT_API_KEY\"]},\n    timeout=30,\n)\nresponse.raise_for_status()\nresult = response.json()"}],"x-response-fields":{"id":{"type":"string","description":"Resource identifier used by this endpoint."},"author":{"type":"string","description":"Public creator name or handle."},"published_at":{"type":"string","description":"Source publication date or timestamp; null when absent."},"views":{"type":"number","description":"Observed views, where exposed by this source."},"likes":{"type":"number","description":"Observed likes."},"comments":{"type":"number","description":"Observed comment count, not comment rows."},"media_url":{"type":"string","description":"Preview image URL; not a guaranteed downloadable video."},"permalink":{"type":"string","description":"Public content URL."},"duration_seconds":{"type":"number","description":"Duration in seconds when returned."},"hashtags":{"type":"array","description":"Hashtags with platform or derived_text provenance.","items":{"type":"object","description":"Entity observed at source or derived from text.","properties":{"name":{"type":"string","description":"Hashtag or account name."},"id":{"type":"string","description":"Platform ID when supplied."},"source":{"type":"string","description":"platform or derived_text."}}}},"mentions":{"type":"array","description":"Mentions with platform or derived_text provenance; text is not proof of an account relationship.","items":{"type":"object","description":"Entity observed at source or derived from text.","properties":{"name":{"type":"string","description":"Hashtag or account name."},"id":{"type":"string","description":"Platform ID when supplied."},"source":{"type":"string","description":"platform or derived_text."}}}},"caption":{"type":"string","description":"Public video description."},"shares":{"type":"number","description":"Observed shares."},"favorites":{"type":"number","description":"Observed collect count; null when absent."},"width":{"type":"number","description":"Video width in pixels."},"height":{"type":"number","description":"Video height in pixels."},"author_id":{"type":"string","description":"Stable creator ID when returned."},"author_display_name":{"type":"string","description":"Public display name."},"author_verified":{"type":"boolean","description":"Explicit creator verification state."},"author_avatar_url":{"type":"string","description":"Public creator avatar URL."},"region_code":{"type":"string","description":"Source content region code when exposed; not proof of creator residence."},"video_url":{"type":"string","description":"Public playback URL when supplied; may expire or require source request headers."},"subtitle_tracks":{"type":"array","description":"Subtitle links exposed by the public video; does not run transcription.","items":{"type":"object","description":"Subtitle track.","properties":{"language":{"type":"string","description":"Source language code."},"language_id":{"type":"string","description":"Source language identifier."},"url":{"type":"string","description":"Source subtitle URL."},"format":{"type":"string","description":"Subtitle format."}}}},"effects":{"type":"array","description":"Effect metadata exposed by the public page.","items":{"type":"object","description":"Effect.","properties":{"id":{"type":"string","description":"Effect ID."},"name":{"type":"string","description":"Effect name."}}}},"stickers":{"type":"array","description":"Sticker metadata exposed by the public page.","items":{"type":"object","description":"Sticker.","properties":{"type":{"type":"number","description":"Source sticker type."},"texts":{"type":"array","description":"Returned sticker text.","items":{"type":"string","description":"Text."}}}}},"music":{"type":"object","description":"Sound metadata from the public video.","properties":{"id":{"type":"string","description":"Sound ID."},"title":{"type":"string","description":"Sound title."},"author":{"type":"string","description":"Sound author."},"original":{"type":"boolean","description":"Source original-sound flag."},"duration_seconds":{"type":"number","description":"Sound duration."},"cover_url":{"type":"string","description":"Sound cover URL."},"play_url":{"type":"string","description":"Sound preview URL."}}},"playlist_id":{"type":"string","description":"Source playlist ID when returned."},"pinned":{"type":"boolean","description":"Explicit pinned-item state when returned."},"media_assets":{"type":"array","description":"Returned cover variants.","items":{"type":"object","description":"One source media variant; URLs may expire.","properties":{"url":{"type":"string","description":"Source URL."},"width":{"type":"number","description":"Width in pixels."},"height":{"type":"number","description":"Height in pixels."},"asset_type":{"type":"string","description":"image, video, thumbnail or avatar."},"variant":{"type":"string","description":"Source variant when known."},"expires_at":{"type":"string","description":"Expiry timestamp when known."}}}}}}},"/v1/tiktok/user/audience":{"get":{"operationId":"tiktok_v1_user_audience","summary":"TikTok audience","description":"Get published audience demographics for a creator. Planned: returns 501 SOURCE_NOT_IMPLEMENTED; no collector or sample response is available and no credits are charged.","tags":["tiktok"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"handle","in":"query","required":true,"schema":{"type":"string","pattern":"^@?[A-Za-z0-9._]{2,24}$","example":"tiktok"},"description":"Required tiktok handle."},{"name":"cache_max_age","in":"query","required":false,"schema":{"type":"string","enum":["1d","3d","7d","14d","30d"]},"description":"Maximum acceptable cache age. Valid cache hits cost zero credits."},{"name":"fields","in":"query","required":false,"schema":{"type":"string","example":"item"},"description":"Comma-separated fields or dot paths, including inside arrays such as items.id. Response identity and pagination are retained."},{"name":"trim","in":"query","required":false,"schema":{"type":"boolean","default":false},"description":"Remove null and empty values. Meaningful empty YouTube region-restriction lists are retained."}],"responses":{"200":{"description":"Normalized resource","headers":{"x-request-id":{"schema":{"type":"string"}},"x-data-mode":{"schema":{"type":"string","enum":["live","sandbox"]}},"x-cache":{"schema":{"type":"string","enum":["HIT","MISS"]}},"x-credits-charged":{"schema":{"type":"integer"}},"x-credits-remaining":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"data":{"type":"object","properties":{"item":{"type":"object","additionalProperties":true,"properties":{"id":{"type":["string","null"],"description":"Resource identifier used by this endpoint."},"author":{"type":["string","null"],"description":"Public creator name or handle."},"published_at":{"type":["string","null"],"description":"Source publication date or timestamp; null when absent."},"views":{"type":["number","null"],"description":"Observed views, where exposed by this source."},"likes":{"type":["number","null"],"description":"Observed likes."},"comments":{"type":["number","null"],"description":"Observed comment count, not comment rows."},"media_url":{"type":["string","null"],"description":"Preview image URL; not a guaranteed downloadable video."},"permalink":{"type":["string","null"],"description":"Public content URL."},"duration_seconds":{"type":["number","null"],"description":"Duration in seconds when returned."},"hashtags":{"type":["array","null"],"description":"Hashtags with platform or derived_text provenance.","items":{"type":["object","null"],"description":"Entity observed at source or derived from text.","properties":{"name":{"type":["string","null"],"description":"Hashtag or account name."},"id":{"type":["string","null"],"description":"Platform ID when supplied."},"source":{"type":["string","null"],"description":"platform or derived_text."}}}},"mentions":{"type":["array","null"],"description":"Mentions with platform or derived_text provenance; text is not proof of an account relationship.","items":{"type":["object","null"],"description":"Entity observed at source or derived from text.","properties":{"name":{"type":["string","null"],"description":"Hashtag or account name."},"id":{"type":["string","null"],"description":"Platform ID when supplied."},"source":{"type":["string","null"],"description":"platform or derived_text."}}}},"caption":{"type":["string","null"],"description":"Public video description."},"shares":{"type":["number","null"],"description":"Observed shares."},"favorites":{"type":["number","null"],"description":"Observed collect count; null when absent."},"width":{"type":["number","null"],"description":"Video width in pixels."},"height":{"type":["number","null"],"description":"Video height in pixels."},"author_id":{"type":["string","null"],"description":"Stable creator ID when returned."},"author_display_name":{"type":["string","null"],"description":"Public display name."},"author_verified":{"type":["boolean","null"],"description":"Explicit creator verification state."},"author_avatar_url":{"type":["string","null"],"description":"Public creator avatar URL."},"region_code":{"type":["string","null"],"description":"Source content region code when exposed; not proof of creator residence."},"video_url":{"type":["string","null"],"description":"Public playback URL when supplied; may expire or require source request headers."},"subtitle_tracks":{"type":["array","null"],"description":"Subtitle links exposed by the public video; does not run transcription.","items":{"type":["object","null"],"description":"Subtitle track.","properties":{"language":{"type":["string","null"],"description":"Source language code."},"language_id":{"type":["string","null"],"description":"Source language identifier."},"url":{"type":["string","null"],"description":"Source subtitle URL."},"format":{"type":["string","null"],"description":"Subtitle format."}}}},"effects":{"type":["array","null"],"description":"Effect metadata exposed by the public page.","items":{"type":["object","null"],"description":"Effect.","properties":{"id":{"type":["string","null"],"description":"Effect ID."},"name":{"type":["string","null"],"description":"Effect name."}}}},"stickers":{"type":["array","null"],"description":"Sticker metadata exposed by the public page.","items":{"type":["object","null"],"description":"Sticker.","properties":{"type":{"type":["number","null"],"description":"Source sticker type."},"texts":{"type":["array","null"],"description":"Returned sticker text.","items":{"type":["string","null"],"description":"Text."}}}}},"music":{"type":["object","null"],"description":"Sound metadata from the public video.","properties":{"id":{"type":["string","null"],"description":"Sound ID."},"title":{"type":["string","null"],"description":"Sound title."},"author":{"type":["string","null"],"description":"Sound author."},"original":{"type":["boolean","null"],"description":"Source original-sound flag."},"duration_seconds":{"type":["number","null"],"description":"Sound duration."},"cover_url":{"type":["string","null"],"description":"Sound cover URL."},"play_url":{"type":["string","null"],"description":"Sound preview URL."}}},"playlist_id":{"type":["string","null"],"description":"Source playlist ID when returned."},"pinned":{"type":["boolean","null"],"description":"Explicit pinned-item state when returned."},"media_assets":{"type":["array","null"],"description":"Returned cover variants.","items":{"type":["object","null"],"description":"One source media variant; URLs may expire.","properties":{"url":{"type":["string","null"],"description":"Source URL."},"width":{"type":["number","null"],"description":"Width in pixels."},"height":{"type":["number","null"],"description":"Height in pixels."},"asset_type":{"type":["string","null"],"description":"image, video, thumbnail or avatar."},"variant":{"type":["string","null"],"description":"Source variant when known."},"expires_at":{"type":["string","null"],"description":"Expiry timestamp when known."}}}}}}}}}}]}}}},"400":{"$ref":"#/components/responses/InvalidInput"},"401":{"$ref":"#/components/responses/InvalidApiKey"},"402":{"$ref":"#/components/responses/InsufficientCredits"},"403":{"$ref":"#/components/responses/SourceRestricted"},"404":{"$ref":"#/components/responses/ResourceNotFound"},"408":{"$ref":"#/components/responses/SourceTimeout"},"422":{"$ref":"#/components/responses/SourceResponseChanged"},"429":{"$ref":"#/components/responses/TemporaryCapacity"},"501":{"$ref":"#/components/responses/SourceNotImplemented"},"503":{"$ref":"#/components/responses/SourceUnavailable"}},"x-availability":"planned","x-identifier-one-of":["handle"],"x-credits":26,"x-source-access":"public_page","x-preview":true,"x-codeSamples":[{"lang":"curl","source":"curl 'https://api.socialdatakit.com/v1/tiktok/user/audience?handle=tiktok' \\\n  -H 'x-api-key: YOUR_API_KEY'"},{"lang":"javascript","source":"const response = await fetch(\"https://api.socialdatakit.com/v1/tiktok/user/audience?handle=tiktok\", {\n  headers: { \"x-api-key\": process.env.SOCIALDATAKIT_API_KEY }\n});\nif (!response.ok) throw new Error(await response.text());\nconst result = await response.json();"},{"lang":"python","source":"import os\nimport requests\n\nresponse = requests.get(\n    \"https://api.socialdatakit.com/v1/tiktok/user/audience?handle=tiktok\",\n    headers={\"x-api-key\": os.environ[\"SOCIALDATAKIT_API_KEY\"]},\n    timeout=30,\n)\nresponse.raise_for_status()\nresult = response.json()"}],"x-response-fields":{"id":{"type":"string","description":"Resource identifier used by this endpoint."},"author":{"type":"string","description":"Public creator name or handle."},"published_at":{"type":"string","description":"Source publication date or timestamp; null when absent."},"views":{"type":"number","description":"Observed views, where exposed by this source."},"likes":{"type":"number","description":"Observed likes."},"comments":{"type":"number","description":"Observed comment count, not comment rows."},"media_url":{"type":"string","description":"Preview image URL; not a guaranteed downloadable video."},"permalink":{"type":"string","description":"Public content URL."},"duration_seconds":{"type":"number","description":"Duration in seconds when returned."},"hashtags":{"type":"array","description":"Hashtags with platform or derived_text provenance.","items":{"type":"object","description":"Entity observed at source or derived from text.","properties":{"name":{"type":"string","description":"Hashtag or account name."},"id":{"type":"string","description":"Platform ID when supplied."},"source":{"type":"string","description":"platform or derived_text."}}}},"mentions":{"type":"array","description":"Mentions with platform or derived_text provenance; text is not proof of an account relationship.","items":{"type":"object","description":"Entity observed at source or derived from text.","properties":{"name":{"type":"string","description":"Hashtag or account name."},"id":{"type":"string","description":"Platform ID when supplied."},"source":{"type":"string","description":"platform or derived_text."}}}},"caption":{"type":"string","description":"Public video description."},"shares":{"type":"number","description":"Observed shares."},"favorites":{"type":"number","description":"Observed collect count; null when absent."},"width":{"type":"number","description":"Video width in pixels."},"height":{"type":"number","description":"Video height in pixels."},"author_id":{"type":"string","description":"Stable creator ID when returned."},"author_display_name":{"type":"string","description":"Public display name."},"author_verified":{"type":"boolean","description":"Explicit creator verification state."},"author_avatar_url":{"type":"string","description":"Public creator avatar URL."},"region_code":{"type":"string","description":"Source content region code when exposed; not proof of creator residence."},"video_url":{"type":"string","description":"Public playback URL when supplied; may expire or require source request headers."},"subtitle_tracks":{"type":"array","description":"Subtitle links exposed by the public video; does not run transcription.","items":{"type":"object","description":"Subtitle track.","properties":{"language":{"type":"string","description":"Source language code."},"language_id":{"type":"string","description":"Source language identifier."},"url":{"type":"string","description":"Source subtitle URL."},"format":{"type":"string","description":"Subtitle format."}}}},"effects":{"type":"array","description":"Effect metadata exposed by the public page.","items":{"type":"object","description":"Effect.","properties":{"id":{"type":"string","description":"Effect ID."},"name":{"type":"string","description":"Effect name."}}}},"stickers":{"type":"array","description":"Sticker metadata exposed by the public page.","items":{"type":"object","description":"Sticker.","properties":{"type":{"type":"number","description":"Source sticker type."},"texts":{"type":"array","description":"Returned sticker text.","items":{"type":"string","description":"Text."}}}}},"music":{"type":"object","description":"Sound metadata from the public video.","properties":{"id":{"type":"string","description":"Sound ID."},"title":{"type":"string","description":"Sound title."},"author":{"type":"string","description":"Sound author."},"original":{"type":"boolean","description":"Source original-sound flag."},"duration_seconds":{"type":"number","description":"Sound duration."},"cover_url":{"type":"string","description":"Sound cover URL."},"play_url":{"type":"string","description":"Sound preview URL."}}},"playlist_id":{"type":"string","description":"Source playlist ID when returned."},"pinned":{"type":"boolean","description":"Explicit pinned-item state when returned."},"media_assets":{"type":"array","description":"Returned cover variants.","items":{"type":"object","description":"One source media variant; URLs may expire.","properties":{"url":{"type":"string","description":"Source URL."},"width":{"type":"number","description":"Width in pixels."},"height":{"type":"number","description":"Height in pixels."},"asset_type":{"type":"string","description":"image, video, thumbnail or avatar."},"variant":{"type":"string","description":"Source variant when known."},"expires_at":{"type":"string","description":"Expiry timestamp when known."}}}}}}},"/v1/tiktok/user/live":{"get":{"operationId":"tiktok_v1_user_live","summary":"TikTok live","description":"Get a profile's live stream state. Planned: returns 501 SOURCE_NOT_IMPLEMENTED; no collector or sample response is available and no credits are charged.","tags":["tiktok"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"handle","in":"query","required":true,"schema":{"type":"string","pattern":"^@?[A-Za-z0-9._]{2,24}$","example":"tiktok"},"description":"Required tiktok handle."},{"name":"cache_max_age","in":"query","required":false,"schema":{"type":"string","enum":["1d","3d","7d","14d","30d"]},"description":"Maximum acceptable cache age. Valid cache hits cost zero credits."},{"name":"fields","in":"query","required":false,"schema":{"type":"string","example":"item"},"description":"Comma-separated fields or dot paths, including inside arrays such as items.id. Response identity and pagination are retained."},{"name":"trim","in":"query","required":false,"schema":{"type":"boolean","default":false},"description":"Remove null and empty values. Meaningful empty YouTube region-restriction lists are retained."}],"responses":{"200":{"description":"Normalized resource","headers":{"x-request-id":{"schema":{"type":"string"}},"x-data-mode":{"schema":{"type":"string","enum":["live","sandbox"]}},"x-cache":{"schema":{"type":"string","enum":["HIT","MISS"]}},"x-credits-charged":{"schema":{"type":"integer"}},"x-credits-remaining":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"data":{"type":"object","properties":{"item":{"type":"object","additionalProperties":true,"properties":{"id":{"type":["string","null"],"description":"Resource identifier used by this endpoint."},"author":{"type":["string","null"],"description":"Public creator name or handle."},"published_at":{"type":["string","null"],"description":"Source publication date or timestamp; null when absent."},"views":{"type":["number","null"],"description":"Observed views, where exposed by this source."},"likes":{"type":["number","null"],"description":"Observed likes."},"comments":{"type":["number","null"],"description":"Observed comment count, not comment rows."},"media_url":{"type":["string","null"],"description":"Preview image URL; not a guaranteed downloadable video."},"permalink":{"type":["string","null"],"description":"Public content URL."},"duration_seconds":{"type":["number","null"],"description":"Duration in seconds when returned."},"hashtags":{"type":["array","null"],"description":"Hashtags with platform or derived_text provenance.","items":{"type":["object","null"],"description":"Entity observed at source or derived from text.","properties":{"name":{"type":["string","null"],"description":"Hashtag or account name."},"id":{"type":["string","null"],"description":"Platform ID when supplied."},"source":{"type":["string","null"],"description":"platform or derived_text."}}}},"mentions":{"type":["array","null"],"description":"Mentions with platform or derived_text provenance; text is not proof of an account relationship.","items":{"type":["object","null"],"description":"Entity observed at source or derived from text.","properties":{"name":{"type":["string","null"],"description":"Hashtag or account name."},"id":{"type":["string","null"],"description":"Platform ID when supplied."},"source":{"type":["string","null"],"description":"platform or derived_text."}}}},"caption":{"type":["string","null"],"description":"Public video description."},"shares":{"type":["number","null"],"description":"Observed shares."},"favorites":{"type":["number","null"],"description":"Observed collect count; null when absent."},"width":{"type":["number","null"],"description":"Video width in pixels."},"height":{"type":["number","null"],"description":"Video height in pixels."},"author_id":{"type":["string","null"],"description":"Stable creator ID when returned."},"author_display_name":{"type":["string","null"],"description":"Public display name."},"author_verified":{"type":["boolean","null"],"description":"Explicit creator verification state."},"author_avatar_url":{"type":["string","null"],"description":"Public creator avatar URL."},"region_code":{"type":["string","null"],"description":"Source content region code when exposed; not proof of creator residence."},"video_url":{"type":["string","null"],"description":"Public playback URL when supplied; may expire or require source request headers."},"subtitle_tracks":{"type":["array","null"],"description":"Subtitle links exposed by the public video; does not run transcription.","items":{"type":["object","null"],"description":"Subtitle track.","properties":{"language":{"type":["string","null"],"description":"Source language code."},"language_id":{"type":["string","null"],"description":"Source language identifier."},"url":{"type":["string","null"],"description":"Source subtitle URL."},"format":{"type":["string","null"],"description":"Subtitle format."}}}},"effects":{"type":["array","null"],"description":"Effect metadata exposed by the public page.","items":{"type":["object","null"],"description":"Effect.","properties":{"id":{"type":["string","null"],"description":"Effect ID."},"name":{"type":["string","null"],"description":"Effect name."}}}},"stickers":{"type":["array","null"],"description":"Sticker metadata exposed by the public page.","items":{"type":["object","null"],"description":"Sticker.","properties":{"type":{"type":["number","null"],"description":"Source sticker type."},"texts":{"type":["array","null"],"description":"Returned sticker text.","items":{"type":["string","null"],"description":"Text."}}}}},"music":{"type":["object","null"],"description":"Sound metadata from the public video.","properties":{"id":{"type":["string","null"],"description":"Sound ID."},"title":{"type":["string","null"],"description":"Sound title."},"author":{"type":["string","null"],"description":"Sound author."},"original":{"type":["boolean","null"],"description":"Source original-sound flag."},"duration_seconds":{"type":["number","null"],"description":"Sound duration."},"cover_url":{"type":["string","null"],"description":"Sound cover URL."},"play_url":{"type":["string","null"],"description":"Sound preview URL."}}},"playlist_id":{"type":["string","null"],"description":"Source playlist ID when returned."},"pinned":{"type":["boolean","null"],"description":"Explicit pinned-item state when returned."},"media_assets":{"type":["array","null"],"description":"Returned cover variants.","items":{"type":["object","null"],"description":"One source media variant; URLs may expire.","properties":{"url":{"type":["string","null"],"description":"Source URL."},"width":{"type":["number","null"],"description":"Width in pixels."},"height":{"type":["number","null"],"description":"Height in pixels."},"asset_type":{"type":["string","null"],"description":"image, video, thumbnail or avatar."},"variant":{"type":["string","null"],"description":"Source variant when known."},"expires_at":{"type":["string","null"],"description":"Expiry timestamp when known."}}}}}}}}}}]}}}},"400":{"$ref":"#/components/responses/InvalidInput"},"401":{"$ref":"#/components/responses/InvalidApiKey"},"402":{"$ref":"#/components/responses/InsufficientCredits"},"403":{"$ref":"#/components/responses/SourceRestricted"},"404":{"$ref":"#/components/responses/ResourceNotFound"},"408":{"$ref":"#/components/responses/SourceTimeout"},"422":{"$ref":"#/components/responses/SourceResponseChanged"},"429":{"$ref":"#/components/responses/TemporaryCapacity"},"501":{"$ref":"#/components/responses/SourceNotImplemented"},"503":{"$ref":"#/components/responses/SourceUnavailable"}},"x-availability":"planned","x-identifier-one-of":["handle"],"x-credits":1,"x-source-access":"public_page","x-preview":true,"x-codeSamples":[{"lang":"curl","source":"curl 'https://api.socialdatakit.com/v1/tiktok/user/live?handle=tiktok' \\\n  -H 'x-api-key: YOUR_API_KEY'"},{"lang":"javascript","source":"const response = await fetch(\"https://api.socialdatakit.com/v1/tiktok/user/live?handle=tiktok\", {\n  headers: { \"x-api-key\": process.env.SOCIALDATAKIT_API_KEY }\n});\nif (!response.ok) throw new Error(await response.text());\nconst result = await response.json();"},{"lang":"python","source":"import os\nimport requests\n\nresponse = requests.get(\n    \"https://api.socialdatakit.com/v1/tiktok/user/live?handle=tiktok\",\n    headers={\"x-api-key\": os.environ[\"SOCIALDATAKIT_API_KEY\"]},\n    timeout=30,\n)\nresponse.raise_for_status()\nresult = response.json()"}],"x-response-fields":{"id":{"type":"string","description":"Resource identifier used by this endpoint."},"author":{"type":"string","description":"Public creator name or handle."},"published_at":{"type":"string","description":"Source publication date or timestamp; null when absent."},"views":{"type":"number","description":"Observed views, where exposed by this source."},"likes":{"type":"number","description":"Observed likes."},"comments":{"type":"number","description":"Observed comment count, not comment rows."},"media_url":{"type":"string","description":"Preview image URL; not a guaranteed downloadable video."},"permalink":{"type":"string","description":"Public content URL."},"duration_seconds":{"type":"number","description":"Duration in seconds when returned."},"hashtags":{"type":"array","description":"Hashtags with platform or derived_text provenance.","items":{"type":"object","description":"Entity observed at source or derived from text.","properties":{"name":{"type":"string","description":"Hashtag or account name."},"id":{"type":"string","description":"Platform ID when supplied."},"source":{"type":"string","description":"platform or derived_text."}}}},"mentions":{"type":"array","description":"Mentions with platform or derived_text provenance; text is not proof of an account relationship.","items":{"type":"object","description":"Entity observed at source or derived from text.","properties":{"name":{"type":"string","description":"Hashtag or account name."},"id":{"type":"string","description":"Platform ID when supplied."},"source":{"type":"string","description":"platform or derived_text."}}}},"caption":{"type":"string","description":"Public video description."},"shares":{"type":"number","description":"Observed shares."},"favorites":{"type":"number","description":"Observed collect count; null when absent."},"width":{"type":"number","description":"Video width in pixels."},"height":{"type":"number","description":"Video height in pixels."},"author_id":{"type":"string","description":"Stable creator ID when returned."},"author_display_name":{"type":"string","description":"Public display name."},"author_verified":{"type":"boolean","description":"Explicit creator verification state."},"author_avatar_url":{"type":"string","description":"Public creator avatar URL."},"region_code":{"type":"string","description":"Source content region code when exposed; not proof of creator residence."},"video_url":{"type":"string","description":"Public playback URL when supplied; may expire or require source request headers."},"subtitle_tracks":{"type":"array","description":"Subtitle links exposed by the public video; does not run transcription.","items":{"type":"object","description":"Subtitle track.","properties":{"language":{"type":"string","description":"Source language code."},"language_id":{"type":"string","description":"Source language identifier."},"url":{"type":"string","description":"Source subtitle URL."},"format":{"type":"string","description":"Subtitle format."}}}},"effects":{"type":"array","description":"Effect metadata exposed by the public page.","items":{"type":"object","description":"Effect.","properties":{"id":{"type":"string","description":"Effect ID."},"name":{"type":"string","description":"Effect name."}}}},"stickers":{"type":"array","description":"Sticker metadata exposed by the public page.","items":{"type":"object","description":"Sticker.","properties":{"type":{"type":"number","description":"Source sticker type."},"texts":{"type":"array","description":"Returned sticker text.","items":{"type":"string","description":"Text."}}}}},"music":{"type":"object","description":"Sound metadata from the public video.","properties":{"id":{"type":"string","description":"Sound ID."},"title":{"type":"string","description":"Sound title."},"author":{"type":"string","description":"Sound author."},"original":{"type":"boolean","description":"Source original-sound flag."},"duration_seconds":{"type":"number","description":"Sound duration."},"cover_url":{"type":"string","description":"Sound cover URL."},"play_url":{"type":"string","description":"Sound preview URL."}}},"playlist_id":{"type":"string","description":"Source playlist ID when returned."},"pinned":{"type":"boolean","description":"Explicit pinned-item state when returned."},"media_assets":{"type":"array","description":"Returned cover variants.","items":{"type":"object","description":"One source media variant; URLs may expire.","properties":{"url":{"type":"string","description":"Source URL."},"width":{"type":"number","description":"Width in pixels."},"height":{"type":"number","description":"Height in pixels."},"asset_type":{"type":"string","description":"image, video, thumbnail or avatar."},"variant":{"type":"string","description":"Source variant when known."},"expires_at":{"type":"string","description":"Expiry timestamp when known."}}}}}}},"/v1/tiktok/get-trending-feed":{"get":{"operationId":"tiktok_v1_get-trending-feed","summary":"TikTok trending feed","description":"Get the public trending feed for a region. Planned: returns 501 SOURCE_NOT_IMPLEMENTED; no collector or sample response is available and no credits are charged.","tags":["tiktok"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"handle","in":"query","required":true,"schema":{"type":"string","pattern":"^[A-Z]{2}$","example":"GB"},"description":"Required tiktok handle."},{"name":"cache_max_age","in":"query","required":false,"schema":{"type":"string","enum":["1d","3d","7d","14d","30d"]},"description":"Maximum acceptable cache age. Valid cache hits cost zero credits."},{"name":"fields","in":"query","required":false,"schema":{"type":"string","example":"items"},"description":"Comma-separated fields or dot paths, including inside arrays such as items.id. Response identity and pagination are retained."},{"name":"trim","in":"query","required":false,"schema":{"type":"boolean","default":false},"description":"Remove null and empty values. Meaningful empty YouTube region-restriction lists are retained."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":20,"default":3},"description":"Number of items to return."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"},"description":"Opaque pagination value returned as data.pagination.next_cursor. Keep the identifier, filters and limit unchanged."}],"responses":{"200":{"description":"Normalized resource","headers":{"x-request-id":{"schema":{"type":"string"}},"x-data-mode":{"schema":{"type":"string","enum":["live","sandbox"]}},"x-cache":{"schema":{"type":"string","enum":["HIT","MISS"]}},"x-credits-charged":{"schema":{"type":"integer"}},"x-credits-remaining":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"data":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","additionalProperties":true,"properties":{"id":{"type":["string","null"],"description":"Resource identifier used by this endpoint."},"author":{"type":["string","null"],"description":"Public creator name or handle."},"published_at":{"type":["string","null"],"description":"Source publication date or timestamp; null when absent."},"views":{"type":["number","null"],"description":"Observed views, where exposed by this source."},"likes":{"type":["number","null"],"description":"Observed likes."},"comments":{"type":["number","null"],"description":"Observed comment count, not comment rows."},"media_url":{"type":["string","null"],"description":"Preview image URL; not a guaranteed downloadable video."},"permalink":{"type":["string","null"],"description":"Public content URL."},"duration_seconds":{"type":["number","null"],"description":"Duration in seconds when returned."},"hashtags":{"type":["array","null"],"description":"Hashtags with platform or derived_text provenance.","items":{"type":["object","null"],"description":"Entity observed at source or derived from text.","properties":{"name":{"type":["string","null"],"description":"Hashtag or account name."},"id":{"type":["string","null"],"description":"Platform ID when supplied."},"source":{"type":["string","null"],"description":"platform or derived_text."}}}},"mentions":{"type":["array","null"],"description":"Mentions with platform or derived_text provenance; text is not proof of an account relationship.","items":{"type":["object","null"],"description":"Entity observed at source or derived from text.","properties":{"name":{"type":["string","null"],"description":"Hashtag or account name."},"id":{"type":["string","null"],"description":"Platform ID when supplied."},"source":{"type":["string","null"],"description":"platform or derived_text."}}}},"caption":{"type":["string","null"],"description":"Public video description."},"shares":{"type":["number","null"],"description":"Observed shares."},"favorites":{"type":["number","null"],"description":"Observed collect count; null when absent."},"width":{"type":["number","null"],"description":"Video width in pixels."},"height":{"type":["number","null"],"description":"Video height in pixels."},"author_id":{"type":["string","null"],"description":"Stable creator ID when returned."},"author_display_name":{"type":["string","null"],"description":"Public display name."},"author_verified":{"type":["boolean","null"],"description":"Explicit creator verification state."},"author_avatar_url":{"type":["string","null"],"description":"Public creator avatar URL."},"region_code":{"type":["string","null"],"description":"Source content region code when exposed; not proof of creator residence."},"video_url":{"type":["string","null"],"description":"Public playback URL when supplied; may expire or require source request headers."},"subtitle_tracks":{"type":["array","null"],"description":"Subtitle links exposed by the public video; does not run transcription.","items":{"type":["object","null"],"description":"Subtitle track.","properties":{"language":{"type":["string","null"],"description":"Source language code."},"language_id":{"type":["string","null"],"description":"Source language identifier."},"url":{"type":["string","null"],"description":"Source subtitle URL."},"format":{"type":["string","null"],"description":"Subtitle format."}}}},"effects":{"type":["array","null"],"description":"Effect metadata exposed by the public page.","items":{"type":["object","null"],"description":"Effect.","properties":{"id":{"type":["string","null"],"description":"Effect ID."},"name":{"type":["string","null"],"description":"Effect name."}}}},"stickers":{"type":["array","null"],"description":"Sticker metadata exposed by the public page.","items":{"type":["object","null"],"description":"Sticker.","properties":{"type":{"type":["number","null"],"description":"Source sticker type."},"texts":{"type":["array","null"],"description":"Returned sticker text.","items":{"type":["string","null"],"description":"Text."}}}}},"music":{"type":["object","null"],"description":"Sound metadata from the public video.","properties":{"id":{"type":["string","null"],"description":"Sound ID."},"title":{"type":["string","null"],"description":"Sound title."},"author":{"type":["string","null"],"description":"Sound author."},"original":{"type":["boolean","null"],"description":"Source original-sound flag."},"duration_seconds":{"type":["number","null"],"description":"Sound duration."},"cover_url":{"type":["string","null"],"description":"Sound cover URL."},"play_url":{"type":["string","null"],"description":"Sound preview URL."}}},"playlist_id":{"type":["string","null"],"description":"Source playlist ID when returned."},"pinned":{"type":["boolean","null"],"description":"Explicit pinned-item state when returned."},"media_assets":{"type":["array","null"],"description":"Returned cover variants.","items":{"type":["object","null"],"description":"One source media variant; URLs may expire.","properties":{"url":{"type":["string","null"],"description":"Source URL."},"width":{"type":["number","null"],"description":"Width in pixels."},"height":{"type":["number","null"],"description":"Height in pixels."},"asset_type":{"type":["string","null"],"description":"image, video, thumbnail or avatar."},"variant":{"type":["string","null"],"description":"Source variant when known."},"expires_at":{"type":["string","null"],"description":"Expiry timestamp when known."}}}}}}}}}}}]}}}},"400":{"$ref":"#/components/responses/InvalidInput"},"401":{"$ref":"#/components/responses/InvalidApiKey"},"402":{"$ref":"#/components/responses/InsufficientCredits"},"403":{"$ref":"#/components/responses/SourceRestricted"},"404":{"$ref":"#/components/responses/ResourceNotFound"},"408":{"$ref":"#/components/responses/SourceTimeout"},"422":{"$ref":"#/components/responses/SourceResponseChanged"},"429":{"$ref":"#/components/responses/TemporaryCapacity"},"501":{"$ref":"#/components/responses/SourceNotImplemented"},"503":{"$ref":"#/components/responses/SourceUnavailable"}},"x-availability":"planned","x-identifier-one-of":["handle"],"x-credits":2,"x-source-access":"public_page","x-preview":true,"x-codeSamples":[{"lang":"curl","source":"curl 'https://api.socialdatakit.com/v1/tiktok/get-trending-feed?handle=GB' \\\n  -H 'x-api-key: YOUR_API_KEY'"},{"lang":"javascript","source":"const response = await fetch(\"https://api.socialdatakit.com/v1/tiktok/get-trending-feed?handle=GB\", {\n  headers: { \"x-api-key\": process.env.SOCIALDATAKIT_API_KEY }\n});\nif (!response.ok) throw new Error(await response.text());\nconst result = await response.json();"},{"lang":"python","source":"import os\nimport requests\n\nresponse = requests.get(\n    \"https://api.socialdatakit.com/v1/tiktok/get-trending-feed?handle=GB\",\n    headers={\"x-api-key\": os.environ[\"SOCIALDATAKIT_API_KEY\"]},\n    timeout=30,\n)\nresponse.raise_for_status()\nresult = response.json()"}],"x-response-fields":{"id":{"type":"string","description":"Resource identifier used by this endpoint."},"author":{"type":"string","description":"Public creator name or handle."},"published_at":{"type":"string","description":"Source publication date or timestamp; null when absent."},"views":{"type":"number","description":"Observed views, where exposed by this source."},"likes":{"type":"number","description":"Observed likes."},"comments":{"type":"number","description":"Observed comment count, not comment rows."},"media_url":{"type":"string","description":"Preview image URL; not a guaranteed downloadable video."},"permalink":{"type":"string","description":"Public content URL."},"duration_seconds":{"type":"number","description":"Duration in seconds when returned."},"hashtags":{"type":"array","description":"Hashtags with platform or derived_text provenance.","items":{"type":"object","description":"Entity observed at source or derived from text.","properties":{"name":{"type":"string","description":"Hashtag or account name."},"id":{"type":"string","description":"Platform ID when supplied."},"source":{"type":"string","description":"platform or derived_text."}}}},"mentions":{"type":"array","description":"Mentions with platform or derived_text provenance; text is not proof of an account relationship.","items":{"type":"object","description":"Entity observed at source or derived from text.","properties":{"name":{"type":"string","description":"Hashtag or account name."},"id":{"type":"string","description":"Platform ID when supplied."},"source":{"type":"string","description":"platform or derived_text."}}}},"caption":{"type":"string","description":"Public video description."},"shares":{"type":"number","description":"Observed shares."},"favorites":{"type":"number","description":"Observed collect count; null when absent."},"width":{"type":"number","description":"Video width in pixels."},"height":{"type":"number","description":"Video height in pixels."},"author_id":{"type":"string","description":"Stable creator ID when returned."},"author_display_name":{"type":"string","description":"Public display name."},"author_verified":{"type":"boolean","description":"Explicit creator verification state."},"author_avatar_url":{"type":"string","description":"Public creator avatar URL."},"region_code":{"type":"string","description":"Source content region code when exposed; not proof of creator residence."},"video_url":{"type":"string","description":"Public playback URL when supplied; may expire or require source request headers."},"subtitle_tracks":{"type":"array","description":"Subtitle links exposed by the public video; does not run transcription.","items":{"type":"object","description":"Subtitle track.","properties":{"language":{"type":"string","description":"Source language code."},"language_id":{"type":"string","description":"Source language identifier."},"url":{"type":"string","description":"Source subtitle URL."},"format":{"type":"string","description":"Subtitle format."}}}},"effects":{"type":"array","description":"Effect metadata exposed by the public page.","items":{"type":"object","description":"Effect.","properties":{"id":{"type":"string","description":"Effect ID."},"name":{"type":"string","description":"Effect name."}}}},"stickers":{"type":"array","description":"Sticker metadata exposed by the public page.","items":{"type":"object","description":"Sticker.","properties":{"type":{"type":"number","description":"Source sticker type."},"texts":{"type":"array","description":"Returned sticker text.","items":{"type":"string","description":"Text."}}}}},"music":{"type":"object","description":"Sound metadata from the public video.","properties":{"id":{"type":"string","description":"Sound ID."},"title":{"type":"string","description":"Sound title."},"author":{"type":"string","description":"Sound author."},"original":{"type":"boolean","description":"Source original-sound flag."},"duration_seconds":{"type":"number","description":"Sound duration."},"cover_url":{"type":"string","description":"Sound cover URL."},"play_url":{"type":"string","description":"Sound preview URL."}}},"playlist_id":{"type":"string","description":"Source playlist ID when returned."},"pinned":{"type":"boolean","description":"Explicit pinned-item state when returned."},"media_assets":{"type":"array","description":"Returned cover variants.","items":{"type":"object","description":"One source media variant; URLs may expire.","properties":{"url":{"type":"string","description":"Source URL."},"width":{"type":"number","description":"Width in pixels."},"height":{"type":"number","description":"Height in pixels."},"asset_type":{"type":"string","description":"image, video, thumbnail or avatar."},"variant":{"type":"string","description":"Source variant when known."},"expires_at":{"type":"string","description":"Expiry timestamp when known."}}}}}}},"/v1/tiktok/videos/popular":{"get":{"operationId":"tiktok_v1_videos_popular","summary":"TikTok popular videos","description":"Get popular public videos. Planned: returns 501 SOURCE_NOT_IMPLEMENTED; no collector or sample response is available and no credits are charged.","tags":["tiktok"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"query","in":"query","required":true,"schema":{"type":"string","pattern":"^.{1,180}$","example":"GB"},"description":"Required tiktok query."},{"name":"cache_max_age","in":"query","required":false,"schema":{"type":"string","enum":["1d","3d","7d","14d","30d"]},"description":"Maximum acceptable cache age. Valid cache hits cost zero credits."},{"name":"fields","in":"query","required":false,"schema":{"type":"string","example":"items"},"description":"Comma-separated fields or dot paths, including inside arrays such as items.id. Response identity and pagination are retained."},{"name":"trim","in":"query","required":false,"schema":{"type":"boolean","default":false},"description":"Remove null and empty values. Meaningful empty YouTube region-restriction lists are retained."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":20,"default":3},"description":"Number of items to return."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"},"description":"Opaque pagination value returned as data.pagination.next_cursor. Keep the identifier, filters and limit unchanged."}],"responses":{"200":{"description":"Normalized resource","headers":{"x-request-id":{"schema":{"type":"string"}},"x-data-mode":{"schema":{"type":"string","enum":["live","sandbox"]}},"x-cache":{"schema":{"type":"string","enum":["HIT","MISS"]}},"x-credits-charged":{"schema":{"type":"integer"}},"x-credits-remaining":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"data":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","additionalProperties":true,"properties":{"id":{"type":["string","null"],"description":"Resource identifier used by this endpoint."},"author":{"type":["string","null"],"description":"Public creator name or handle."},"published_at":{"type":["string","null"],"description":"Source publication date or timestamp; null when absent."},"views":{"type":["number","null"],"description":"Observed views, where exposed by this source."},"likes":{"type":["number","null"],"description":"Observed likes."},"comments":{"type":["number","null"],"description":"Observed comment count, not comment rows."},"media_url":{"type":["string","null"],"description":"Preview image URL; not a guaranteed downloadable video."},"permalink":{"type":["string","null"],"description":"Public content URL."},"duration_seconds":{"type":["number","null"],"description":"Duration in seconds when returned."},"hashtags":{"type":["array","null"],"description":"Hashtags with platform or derived_text provenance.","items":{"type":["object","null"],"description":"Entity observed at source or derived from text.","properties":{"name":{"type":["string","null"],"description":"Hashtag or account name."},"id":{"type":["string","null"],"description":"Platform ID when supplied."},"source":{"type":["string","null"],"description":"platform or derived_text."}}}},"mentions":{"type":["array","null"],"description":"Mentions with platform or derived_text provenance; text is not proof of an account relationship.","items":{"type":["object","null"],"description":"Entity observed at source or derived from text.","properties":{"name":{"type":["string","null"],"description":"Hashtag or account name."},"id":{"type":["string","null"],"description":"Platform ID when supplied."},"source":{"type":["string","null"],"description":"platform or derived_text."}}}},"caption":{"type":["string","null"],"description":"Public video description."},"shares":{"type":["number","null"],"description":"Observed shares."},"favorites":{"type":["number","null"],"description":"Observed collect count; null when absent."},"width":{"type":["number","null"],"description":"Video width in pixels."},"height":{"type":["number","null"],"description":"Video height in pixels."},"author_id":{"type":["string","null"],"description":"Stable creator ID when returned."},"author_display_name":{"type":["string","null"],"description":"Public display name."},"author_verified":{"type":["boolean","null"],"description":"Explicit creator verification state."},"author_avatar_url":{"type":["string","null"],"description":"Public creator avatar URL."},"region_code":{"type":["string","null"],"description":"Source content region code when exposed; not proof of creator residence."},"video_url":{"type":["string","null"],"description":"Public playback URL when supplied; may expire or require source request headers."},"subtitle_tracks":{"type":["array","null"],"description":"Subtitle links exposed by the public video; does not run transcription.","items":{"type":["object","null"],"description":"Subtitle track.","properties":{"language":{"type":["string","null"],"description":"Source language code."},"language_id":{"type":["string","null"],"description":"Source language identifier."},"url":{"type":["string","null"],"description":"Source subtitle URL."},"format":{"type":["string","null"],"description":"Subtitle format."}}}},"effects":{"type":["array","null"],"description":"Effect metadata exposed by the public page.","items":{"type":["object","null"],"description":"Effect.","properties":{"id":{"type":["string","null"],"description":"Effect ID."},"name":{"type":["string","null"],"description":"Effect name."}}}},"stickers":{"type":["array","null"],"description":"Sticker metadata exposed by the public page.","items":{"type":["object","null"],"description":"Sticker.","properties":{"type":{"type":["number","null"],"description":"Source sticker type."},"texts":{"type":["array","null"],"description":"Returned sticker text.","items":{"type":["string","null"],"description":"Text."}}}}},"music":{"type":["object","null"],"description":"Sound metadata from the public video.","properties":{"id":{"type":["string","null"],"description":"Sound ID."},"title":{"type":["string","null"],"description":"Sound title."},"author":{"type":["string","null"],"description":"Sound author."},"original":{"type":["boolean","null"],"description":"Source original-sound flag."},"duration_seconds":{"type":["number","null"],"description":"Sound duration."},"cover_url":{"type":["string","null"],"description":"Sound cover URL."},"play_url":{"type":["string","null"],"description":"Sound preview URL."}}},"playlist_id":{"type":["string","null"],"description":"Source playlist ID when returned."},"pinned":{"type":["boolean","null"],"description":"Explicit pinned-item state when returned."},"media_assets":{"type":["array","null"],"description":"Returned cover variants.","items":{"type":["object","null"],"description":"One source media variant; URLs may expire.","properties":{"url":{"type":["string","null"],"description":"Source URL."},"width":{"type":["number","null"],"description":"Width in pixels."},"height":{"type":["number","null"],"description":"Height in pixels."},"asset_type":{"type":["string","null"],"description":"image, video, thumbnail or avatar."},"variant":{"type":["string","null"],"description":"Source variant when known."},"expires_at":{"type":["string","null"],"description":"Expiry timestamp when known."}}}}}}}}}}}]}}}},"400":{"$ref":"#/components/responses/InvalidInput"},"401":{"$ref":"#/components/responses/InvalidApiKey"},"402":{"$ref":"#/components/responses/InsufficientCredits"},"403":{"$ref":"#/components/responses/SourceRestricted"},"404":{"$ref":"#/components/responses/ResourceNotFound"},"408":{"$ref":"#/components/responses/SourceTimeout"},"422":{"$ref":"#/components/responses/SourceResponseChanged"},"429":{"$ref":"#/components/responses/TemporaryCapacity"},"501":{"$ref":"#/components/responses/SourceNotImplemented"},"503":{"$ref":"#/components/responses/SourceUnavailable"}},"x-availability":"planned","x-identifier-one-of":["query"],"x-credits":2,"x-source-access":"public_page","x-preview":true,"x-codeSamples":[{"lang":"curl","source":"curl 'https://api.socialdatakit.com/v1/tiktok/videos/popular?query=GB' \\\n  -H 'x-api-key: YOUR_API_KEY'"},{"lang":"javascript","source":"const response = await fetch(\"https://api.socialdatakit.com/v1/tiktok/videos/popular?query=GB\", {\n  headers: { \"x-api-key\": process.env.SOCIALDATAKIT_API_KEY }\n});\nif (!response.ok) throw new Error(await response.text());\nconst result = await response.json();"},{"lang":"python","source":"import os\nimport requests\n\nresponse = requests.get(\n    \"https://api.socialdatakit.com/v1/tiktok/videos/popular?query=GB\",\n    headers={\"x-api-key\": os.environ[\"SOCIALDATAKIT_API_KEY\"]},\n    timeout=30,\n)\nresponse.raise_for_status()\nresult = response.json()"}],"x-response-fields":{"id":{"type":"string","description":"Resource identifier used by this endpoint."},"author":{"type":"string","description":"Public creator name or handle."},"published_at":{"type":"string","description":"Source publication date or timestamp; null when absent."},"views":{"type":"number","description":"Observed views, where exposed by this source."},"likes":{"type":"number","description":"Observed likes."},"comments":{"type":"number","description":"Observed comment count, not comment rows."},"media_url":{"type":"string","description":"Preview image URL; not a guaranteed downloadable video."},"permalink":{"type":"string","description":"Public content URL."},"duration_seconds":{"type":"number","description":"Duration in seconds when returned."},"hashtags":{"type":"array","description":"Hashtags with platform or derived_text provenance.","items":{"type":"object","description":"Entity observed at source or derived from text.","properties":{"name":{"type":"string","description":"Hashtag or account name."},"id":{"type":"string","description":"Platform ID when supplied."},"source":{"type":"string","description":"platform or derived_text."}}}},"mentions":{"type":"array","description":"Mentions with platform or derived_text provenance; text is not proof of an account relationship.","items":{"type":"object","description":"Entity observed at source or derived from text.","properties":{"name":{"type":"string","description":"Hashtag or account name."},"id":{"type":"string","description":"Platform ID when supplied."},"source":{"type":"string","description":"platform or derived_text."}}}},"caption":{"type":"string","description":"Public video description."},"shares":{"type":"number","description":"Observed shares."},"favorites":{"type":"number","description":"Observed collect count; null when absent."},"width":{"type":"number","description":"Video width in pixels."},"height":{"type":"number","description":"Video height in pixels."},"author_id":{"type":"string","description":"Stable creator ID when returned."},"author_display_name":{"type":"string","description":"Public display name."},"author_verified":{"type":"boolean","description":"Explicit creator verification state."},"author_avatar_url":{"type":"string","description":"Public creator avatar URL."},"region_code":{"type":"string","description":"Source content region code when exposed; not proof of creator residence."},"video_url":{"type":"string","description":"Public playback URL when supplied; may expire or require source request headers."},"subtitle_tracks":{"type":"array","description":"Subtitle links exposed by the public video; does not run transcription.","items":{"type":"object","description":"Subtitle track.","properties":{"language":{"type":"string","description":"Source language code."},"language_id":{"type":"string","description":"Source language identifier."},"url":{"type":"string","description":"Source subtitle URL."},"format":{"type":"string","description":"Subtitle format."}}}},"effects":{"type":"array","description":"Effect metadata exposed by the public page.","items":{"type":"object","description":"Effect.","properties":{"id":{"type":"string","description":"Effect ID."},"name":{"type":"string","description":"Effect name."}}}},"stickers":{"type":"array","description":"Sticker metadata exposed by the public page.","items":{"type":"object","description":"Sticker.","properties":{"type":{"type":"number","description":"Source sticker type."},"texts":{"type":"array","description":"Returned sticker text.","items":{"type":"string","description":"Text."}}}}},"music":{"type":"object","description":"Sound metadata from the public video.","properties":{"id":{"type":"string","description":"Sound ID."},"title":{"type":"string","description":"Sound title."},"author":{"type":"string","description":"Sound author."},"original":{"type":"boolean","description":"Source original-sound flag."},"duration_seconds":{"type":"number","description":"Sound duration."},"cover_url":{"type":"string","description":"Sound cover URL."},"play_url":{"type":"string","description":"Sound preview URL."}}},"playlist_id":{"type":"string","description":"Source playlist ID when returned."},"pinned":{"type":"boolean","description":"Explicit pinned-item state when returned."},"media_assets":{"type":"array","description":"Returned cover variants.","items":{"type":"object","description":"One source media variant; URLs may expire.","properties":{"url":{"type":"string","description":"Source URL."},"width":{"type":"number","description":"Width in pixels."},"height":{"type":"number","description":"Height in pixels."},"asset_type":{"type":"string","description":"image, video, thumbnail or avatar."},"variant":{"type":"string","description":"Source variant when known."},"expires_at":{"type":"string","description":"Expiry timestamp when known."}}}}}}},"/v1/tiktok/creators/popular":{"get":{"operationId":"tiktok_v1_creators_popular","summary":"TikTok popular creators","description":"Get popular creators, filterable by follower count and country. Planned: returns 501 SOURCE_NOT_IMPLEMENTED; no collector or sample response is available and no credits are charged.","tags":["tiktok"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"query","in":"query","required":true,"schema":{"type":"string","pattern":"^.{1,180}$","example":"GB"},"description":"Required tiktok query."},{"name":"cache_max_age","in":"query","required":false,"schema":{"type":"string","enum":["1d","3d","7d","14d","30d"]},"description":"Maximum acceptable cache age. Valid cache hits cost zero credits."},{"name":"fields","in":"query","required":false,"schema":{"type":"string","example":"items"},"description":"Comma-separated fields or dot paths, including inside arrays such as items.id. Response identity and pagination are retained."},{"name":"trim","in":"query","required":false,"schema":{"type":"boolean","default":false},"description":"Remove null and empty values. Meaningful empty YouTube region-restriction lists are retained."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":20,"default":3},"description":"Number of items to return."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"},"description":"Opaque pagination value returned as data.pagination.next_cursor. Keep the identifier, filters and limit unchanged."}],"responses":{"200":{"description":"Normalized resource","headers":{"x-request-id":{"schema":{"type":"string"}},"x-data-mode":{"schema":{"type":"string","enum":["live","sandbox"]}},"x-cache":{"schema":{"type":"string","enum":["HIT","MISS"]}},"x-credits-charged":{"schema":{"type":"integer"}},"x-credits-remaining":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"data":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","additionalProperties":true,"properties":{"id":{"type":["string","null"],"description":"Resource identifier used by this endpoint."},"author":{"type":["string","null"],"description":"Public creator name or handle."},"published_at":{"type":["string","null"],"description":"Source publication date or timestamp; null when absent."},"views":{"type":["number","null"],"description":"Observed views, where exposed by this source."},"likes":{"type":["number","null"],"description":"Observed likes."},"comments":{"type":["number","null"],"description":"Observed comment count, not comment rows."},"media_url":{"type":["string","null"],"description":"Preview image URL; not a guaranteed downloadable video."},"permalink":{"type":["string","null"],"description":"Public content URL."},"duration_seconds":{"type":["number","null"],"description":"Duration in seconds when returned."},"hashtags":{"type":["array","null"],"description":"Hashtags with platform or derived_text provenance.","items":{"type":["object","null"],"description":"Entity observed at source or derived from text.","properties":{"name":{"type":["string","null"],"description":"Hashtag or account name."},"id":{"type":["string","null"],"description":"Platform ID when supplied."},"source":{"type":["string","null"],"description":"platform or derived_text."}}}},"mentions":{"type":["array","null"],"description":"Mentions with platform or derived_text provenance; text is not proof of an account relationship.","items":{"type":["object","null"],"description":"Entity observed at source or derived from text.","properties":{"name":{"type":["string","null"],"description":"Hashtag or account name."},"id":{"type":["string","null"],"description":"Platform ID when supplied."},"source":{"type":["string","null"],"description":"platform or derived_text."}}}},"caption":{"type":["string","null"],"description":"Public video description."},"shares":{"type":["number","null"],"description":"Observed shares."},"favorites":{"type":["number","null"],"description":"Observed collect count; null when absent."},"width":{"type":["number","null"],"description":"Video width in pixels."},"height":{"type":["number","null"],"description":"Video height in pixels."},"author_id":{"type":["string","null"],"description":"Stable creator ID when returned."},"author_display_name":{"type":["string","null"],"description":"Public display name."},"author_verified":{"type":["boolean","null"],"description":"Explicit creator verification state."},"author_avatar_url":{"type":["string","null"],"description":"Public creator avatar URL."},"region_code":{"type":["string","null"],"description":"Source content region code when exposed; not proof of creator residence."},"video_url":{"type":["string","null"],"description":"Public playback URL when supplied; may expire or require source request headers."},"subtitle_tracks":{"type":["array","null"],"description":"Subtitle links exposed by the public video; does not run transcription.","items":{"type":["object","null"],"description":"Subtitle track.","properties":{"language":{"type":["string","null"],"description":"Source language code."},"language_id":{"type":["string","null"],"description":"Source language identifier."},"url":{"type":["string","null"],"description":"Source subtitle URL."},"format":{"type":["string","null"],"description":"Subtitle format."}}}},"effects":{"type":["array","null"],"description":"Effect metadata exposed by the public page.","items":{"type":["object","null"],"description":"Effect.","properties":{"id":{"type":["string","null"],"description":"Effect ID."},"name":{"type":["string","null"],"description":"Effect name."}}}},"stickers":{"type":["array","null"],"description":"Sticker metadata exposed by the public page.","items":{"type":["object","null"],"description":"Sticker.","properties":{"type":{"type":["number","null"],"description":"Source sticker type."},"texts":{"type":["array","null"],"description":"Returned sticker text.","items":{"type":["string","null"],"description":"Text."}}}}},"music":{"type":["object","null"],"description":"Sound metadata from the public video.","properties":{"id":{"type":["string","null"],"description":"Sound ID."},"title":{"type":["string","null"],"description":"Sound title."},"author":{"type":["string","null"],"description":"Sound author."},"original":{"type":["boolean","null"],"description":"Source original-sound flag."},"duration_seconds":{"type":["number","null"],"description":"Sound duration."},"cover_url":{"type":["string","null"],"description":"Sound cover URL."},"play_url":{"type":["string","null"],"description":"Sound preview URL."}}},"playlist_id":{"type":["string","null"],"description":"Source playlist ID when returned."},"pinned":{"type":["boolean","null"],"description":"Explicit pinned-item state when returned."},"media_assets":{"type":["array","null"],"description":"Returned cover variants.","items":{"type":["object","null"],"description":"One source media variant; URLs may expire.","properties":{"url":{"type":["string","null"],"description":"Source URL."},"width":{"type":["number","null"],"description":"Width in pixels."},"height":{"type":["number","null"],"description":"Height in pixels."},"asset_type":{"type":["string","null"],"description":"image, video, thumbnail or avatar."},"variant":{"type":["string","null"],"description":"Source variant when known."},"expires_at":{"type":["string","null"],"description":"Expiry timestamp when known."}}}}}}}}}}}]}}}},"400":{"$ref":"#/components/responses/InvalidInput"},"401":{"$ref":"#/components/responses/InvalidApiKey"},"402":{"$ref":"#/components/responses/InsufficientCredits"},"403":{"$ref":"#/components/responses/SourceRestricted"},"404":{"$ref":"#/components/responses/ResourceNotFound"},"408":{"$ref":"#/components/responses/SourceTimeout"},"422":{"$ref":"#/components/responses/SourceResponseChanged"},"429":{"$ref":"#/components/responses/TemporaryCapacity"},"501":{"$ref":"#/components/responses/SourceNotImplemented"},"503":{"$ref":"#/components/responses/SourceUnavailable"}},"x-availability":"planned","x-identifier-one-of":["query"],"x-credits":2,"x-source-access":"public_page","x-preview":true,"x-codeSamples":[{"lang":"curl","source":"curl 'https://api.socialdatakit.com/v1/tiktok/creators/popular?query=GB' \\\n  -H 'x-api-key: YOUR_API_KEY'"},{"lang":"javascript","source":"const response = await fetch(\"https://api.socialdatakit.com/v1/tiktok/creators/popular?query=GB\", {\n  headers: { \"x-api-key\": process.env.SOCIALDATAKIT_API_KEY }\n});\nif (!response.ok) throw new Error(await response.text());\nconst result = await response.json();"},{"lang":"python","source":"import os\nimport requests\n\nresponse = requests.get(\n    \"https://api.socialdatakit.com/v1/tiktok/creators/popular?query=GB\",\n    headers={\"x-api-key\": os.environ[\"SOCIALDATAKIT_API_KEY\"]},\n    timeout=30,\n)\nresponse.raise_for_status()\nresult = response.json()"}],"x-response-fields":{"id":{"type":"string","description":"Resource identifier used by this endpoint."},"author":{"type":"string","description":"Public creator name or handle."},"published_at":{"type":"string","description":"Source publication date or timestamp; null when absent."},"views":{"type":"number","description":"Observed views, where exposed by this source."},"likes":{"type":"number","description":"Observed likes."},"comments":{"type":"number","description":"Observed comment count, not comment rows."},"media_url":{"type":"string","description":"Preview image URL; not a guaranteed downloadable video."},"permalink":{"type":"string","description":"Public content URL."},"duration_seconds":{"type":"number","description":"Duration in seconds when returned."},"hashtags":{"type":"array","description":"Hashtags with platform or derived_text provenance.","items":{"type":"object","description":"Entity observed at source or derived from text.","properties":{"name":{"type":"string","description":"Hashtag or account name."},"id":{"type":"string","description":"Platform ID when supplied."},"source":{"type":"string","description":"platform or derived_text."}}}},"mentions":{"type":"array","description":"Mentions with platform or derived_text provenance; text is not proof of an account relationship.","items":{"type":"object","description":"Entity observed at source or derived from text.","properties":{"name":{"type":"string","description":"Hashtag or account name."},"id":{"type":"string","description":"Platform ID when supplied."},"source":{"type":"string","description":"platform or derived_text."}}}},"caption":{"type":"string","description":"Public video description."},"shares":{"type":"number","description":"Observed shares."},"favorites":{"type":"number","description":"Observed collect count; null when absent."},"width":{"type":"number","description":"Video width in pixels."},"height":{"type":"number","description":"Video height in pixels."},"author_id":{"type":"string","description":"Stable creator ID when returned."},"author_display_name":{"type":"string","description":"Public display name."},"author_verified":{"type":"boolean","description":"Explicit creator verification state."},"author_avatar_url":{"type":"string","description":"Public creator avatar URL."},"region_code":{"type":"string","description":"Source content region code when exposed; not proof of creator residence."},"video_url":{"type":"string","description":"Public playback URL when supplied; may expire or require source request headers."},"subtitle_tracks":{"type":"array","description":"Subtitle links exposed by the public video; does not run transcription.","items":{"type":"object","description":"Subtitle track.","properties":{"language":{"type":"string","description":"Source language code."},"language_id":{"type":"string","description":"Source language identifier."},"url":{"type":"string","description":"Source subtitle URL."},"format":{"type":"string","description":"Subtitle format."}}}},"effects":{"type":"array","description":"Effect metadata exposed by the public page.","items":{"type":"object","description":"Effect.","properties":{"id":{"type":"string","description":"Effect ID."},"name":{"type":"string","description":"Effect name."}}}},"stickers":{"type":"array","description":"Sticker metadata exposed by the public page.","items":{"type":"object","description":"Sticker.","properties":{"type":{"type":"number","description":"Source sticker type."},"texts":{"type":"array","description":"Returned sticker text.","items":{"type":"string","description":"Text."}}}}},"music":{"type":"object","description":"Sound metadata from the public video.","properties":{"id":{"type":"string","description":"Sound ID."},"title":{"type":"string","description":"Sound title."},"author":{"type":"string","description":"Sound author."},"original":{"type":"boolean","description":"Source original-sound flag."},"duration_seconds":{"type":"number","description":"Sound duration."},"cover_url":{"type":"string","description":"Sound cover URL."},"play_url":{"type":"string","description":"Sound preview URL."}}},"playlist_id":{"type":"string","description":"Source playlist ID when returned."},"pinned":{"type":"boolean","description":"Explicit pinned-item state when returned."},"media_assets":{"type":"array","description":"Returned cover variants.","items":{"type":"object","description":"One source media variant; URLs may expire.","properties":{"url":{"type":"string","description":"Source URL."},"width":{"type":"number","description":"Width in pixels."},"height":{"type":"number","description":"Height in pixels."},"asset_type":{"type":"string","description":"image, video, thumbnail or avatar."},"variant":{"type":"string","description":"Source variant when known."},"expires_at":{"type":"string","description":"Expiry timestamp when known."}}}}}}},"/v1/tiktok/hashtags/popular":{"get":{"operationId":"tiktok_v1_hashtags_popular","summary":"TikTok popular hashtags","description":"Get currently popular hashtags. Planned: returns 501 SOURCE_NOT_IMPLEMENTED; no collector or sample response is available and no credits are charged.","tags":["tiktok"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"query","in":"query","required":true,"schema":{"type":"string","pattern":"^.{1,180}$","example":"GB"},"description":"Required tiktok query."},{"name":"cache_max_age","in":"query","required":false,"schema":{"type":"string","enum":["1d","3d","7d","14d","30d"]},"description":"Maximum acceptable cache age. Valid cache hits cost zero credits."},{"name":"fields","in":"query","required":false,"schema":{"type":"string","example":"items"},"description":"Comma-separated fields or dot paths, including inside arrays such as items.id. Response identity and pagination are retained."},{"name":"trim","in":"query","required":false,"schema":{"type":"boolean","default":false},"description":"Remove null and empty values. Meaningful empty YouTube region-restriction lists are retained."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":20,"default":3},"description":"Number of items to return."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"},"description":"Opaque pagination value returned as data.pagination.next_cursor. Keep the identifier, filters and limit unchanged."}],"responses":{"200":{"description":"Normalized resource","headers":{"x-request-id":{"schema":{"type":"string"}},"x-data-mode":{"schema":{"type":"string","enum":["live","sandbox"]}},"x-cache":{"schema":{"type":"string","enum":["HIT","MISS"]}},"x-credits-charged":{"schema":{"type":"integer"}},"x-credits-remaining":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"data":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","additionalProperties":true,"properties":{"id":{"type":["string","null"],"description":"Source hashtag ID."},"name":{"type":["string","null"],"description":"Hashtag name."},"description":{"type":["string","null"],"description":"Source description."},"content_count":{"type":["number","null"],"description":"Observed number of related posts/videos."},"views":{"type":["number","null"],"description":"Observed aggregate hashtag views, where exposed."},"cover_url":{"type":["string","null"],"description":"Public cover URL."},"permalink":{"type":["string","null"],"description":"Public hashtag page."}}}}}}}}]}}}},"400":{"$ref":"#/components/responses/InvalidInput"},"401":{"$ref":"#/components/responses/InvalidApiKey"},"402":{"$ref":"#/components/responses/InsufficientCredits"},"403":{"$ref":"#/components/responses/SourceRestricted"},"404":{"$ref":"#/components/responses/ResourceNotFound"},"408":{"$ref":"#/components/responses/SourceTimeout"},"422":{"$ref":"#/components/responses/SourceResponseChanged"},"429":{"$ref":"#/components/responses/TemporaryCapacity"},"501":{"$ref":"#/components/responses/SourceNotImplemented"},"503":{"$ref":"#/components/responses/SourceUnavailable"}},"x-availability":"planned","x-identifier-one-of":["query"],"x-credits":2,"x-source-access":"public_page","x-preview":true,"x-codeSamples":[{"lang":"curl","source":"curl 'https://api.socialdatakit.com/v1/tiktok/hashtags/popular?query=GB' \\\n  -H 'x-api-key: YOUR_API_KEY'"},{"lang":"javascript","source":"const response = await fetch(\"https://api.socialdatakit.com/v1/tiktok/hashtags/popular?query=GB\", {\n  headers: { \"x-api-key\": process.env.SOCIALDATAKIT_API_KEY }\n});\nif (!response.ok) throw new Error(await response.text());\nconst result = await response.json();"},{"lang":"python","source":"import os\nimport requests\n\nresponse = requests.get(\n    \"https://api.socialdatakit.com/v1/tiktok/hashtags/popular?query=GB\",\n    headers={\"x-api-key\": os.environ[\"SOCIALDATAKIT_API_KEY\"]},\n    timeout=30,\n)\nresponse.raise_for_status()\nresult = response.json()"}],"x-response-fields":{"id":{"type":"string","description":"Source hashtag ID."},"name":{"type":"string","description":"Hashtag name."},"description":{"type":"string","description":"Source description."},"content_count":{"type":"number","description":"Observed number of related posts/videos."},"views":{"type":"number","description":"Observed aggregate hashtag views, where exposed."},"cover_url":{"type":"string","description":"Public cover URL."},"permalink":{"type":"string","description":"Public hashtag page."}}}},"/v1/tiktok/songs/popular":{"get":{"operationId":"tiktok_v1_songs_popular","summary":"TikTok popular songs","description":"Get currently popular sounds. Planned: returns 501 SOURCE_NOT_IMPLEMENTED; no collector or sample response is available and no credits are charged.","tags":["tiktok"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"query","in":"query","required":true,"schema":{"type":"string","pattern":"^.{1,180}$","example":"GB"},"description":"Required tiktok query."},{"name":"cache_max_age","in":"query","required":false,"schema":{"type":"string","enum":["1d","3d","7d","14d","30d"]},"description":"Maximum acceptable cache age. Valid cache hits cost zero credits."},{"name":"fields","in":"query","required":false,"schema":{"type":"string","example":"items"},"description":"Comma-separated fields or dot paths, including inside arrays such as items.id. Response identity and pagination are retained."},{"name":"trim","in":"query","required":false,"schema":{"type":"boolean","default":false},"description":"Remove null and empty values. Meaningful empty YouTube region-restriction lists are retained."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":20,"default":3},"description":"Number of items to return."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"},"description":"Opaque pagination value returned as data.pagination.next_cursor. Keep the identifier, filters and limit unchanged."}],"responses":{"200":{"description":"Normalized resource","headers":{"x-request-id":{"schema":{"type":"string"}},"x-data-mode":{"schema":{"type":"string","enum":["live","sandbox"]}},"x-cache":{"schema":{"type":"string","enum":["HIT","MISS"]}},"x-credits-charged":{"schema":{"type":"integer"}},"x-credits-remaining":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"data":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","additionalProperties":true,"properties":{"id":{"type":["string","null"],"description":"Sound ID."},"title":{"type":["string","null"],"description":"Sound title."},"author":{"type":["string","null"],"description":"Public sound author."},"original":{"type":["boolean","null"],"description":"Explicit source original-sound flag."},"duration_seconds":{"type":["number","null"],"description":"Sound duration."},"cover_url":{"type":["string","null"],"description":"Cover URL."},"play_url":{"type":["string","null"],"description":"Source preview URL; may expire."},"content_count":{"type":["number","null"],"description":"Observed videos using the sound."},"permalink":{"type":["string","null"],"description":"Public sound URL."}}}}}}}}]}}}},"400":{"$ref":"#/components/responses/InvalidInput"},"401":{"$ref":"#/components/responses/InvalidApiKey"},"402":{"$ref":"#/components/responses/InsufficientCredits"},"403":{"$ref":"#/components/responses/SourceRestricted"},"404":{"$ref":"#/components/responses/ResourceNotFound"},"408":{"$ref":"#/components/responses/SourceTimeout"},"422":{"$ref":"#/components/responses/SourceResponseChanged"},"429":{"$ref":"#/components/responses/TemporaryCapacity"},"501":{"$ref":"#/components/responses/SourceNotImplemented"},"503":{"$ref":"#/components/responses/SourceUnavailable"}},"x-availability":"planned","x-identifier-one-of":["query"],"x-credits":2,"x-source-access":"public_page","x-preview":true,"x-codeSamples":[{"lang":"curl","source":"curl 'https://api.socialdatakit.com/v1/tiktok/songs/popular?query=GB' \\\n  -H 'x-api-key: YOUR_API_KEY'"},{"lang":"javascript","source":"const response = await fetch(\"https://api.socialdatakit.com/v1/tiktok/songs/popular?query=GB\", {\n  headers: { \"x-api-key\": process.env.SOCIALDATAKIT_API_KEY }\n});\nif (!response.ok) throw new Error(await response.text());\nconst result = await response.json();"},{"lang":"python","source":"import os\nimport requests\n\nresponse = requests.get(\n    \"https://api.socialdatakit.com/v1/tiktok/songs/popular?query=GB\",\n    headers={\"x-api-key\": os.environ[\"SOCIALDATAKIT_API_KEY\"]},\n    timeout=30,\n)\nresponse.raise_for_status()\nresult = response.json()"}],"x-response-fields":{"id":{"type":"string","description":"Sound ID."},"title":{"type":"string","description":"Sound title."},"author":{"type":"string","description":"Public sound author."},"original":{"type":"boolean","description":"Explicit source original-sound flag."},"duration_seconds":{"type":"number","description":"Sound duration."},"cover_url":{"type":"string","description":"Cover URL."},"play_url":{"type":"string","description":"Source preview URL; may expire."},"content_count":{"type":"number","description":"Observed videos using the sound."},"permalink":{"type":"string","description":"Public sound URL."}}}},"/v1/tiktok/shop/search":{"get":{"operationId":"tiktok_v1_shop_search","summary":"TikTok Shop search","description":"Search public TikTok Shop products. Planned: returns 501 SOURCE_NOT_IMPLEMENTED; no collector or sample response is available and no credits are charged.","tags":["tiktok"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"query","in":"query","required":true,"schema":{"type":"string","pattern":"^.{1,180}$","example":"headphones"},"description":"Required tiktok query."},{"name":"cache_max_age","in":"query","required":false,"schema":{"type":"string","enum":["1d","3d","7d","14d","30d"]},"description":"Maximum acceptable cache age. Valid cache hits cost zero credits."},{"name":"fields","in":"query","required":false,"schema":{"type":"string","example":"items"},"description":"Comma-separated fields or dot paths, including inside arrays such as items.id. Response identity and pagination are retained."},{"name":"trim","in":"query","required":false,"schema":{"type":"boolean","default":false},"description":"Remove null and empty values. Meaningful empty YouTube region-restriction lists are retained."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":20,"default":3},"description":"Number of items to return."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"},"description":"Opaque pagination value returned as data.pagination.next_cursor. Keep the identifier, filters and limit unchanged."}],"responses":{"200":{"description":"Normalized resource","headers":{"x-request-id":{"schema":{"type":"string"}},"x-data-mode":{"schema":{"type":"string","enum":["live","sandbox"]}},"x-cache":{"schema":{"type":"string","enum":["HIT","MISS"]}},"x-credits-charged":{"schema":{"type":"integer"}},"x-credits-remaining":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"data":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","additionalProperties":true,"properties":{"id":{"type":["string","null"],"description":"Resource identifier used by this endpoint."},"author":{"type":["string","null"],"description":"Public creator name or handle."},"published_at":{"type":["string","null"],"description":"Source publication date or timestamp; null when absent."},"views":{"type":["number","null"],"description":"Observed views, where exposed by this source."},"likes":{"type":["number","null"],"description":"Observed likes."},"comments":{"type":["number","null"],"description":"Observed comment count, not comment rows."},"media_url":{"type":["string","null"],"description":"Preview image URL; not a guaranteed downloadable video."},"permalink":{"type":["string","null"],"description":"Public content URL."},"duration_seconds":{"type":["number","null"],"description":"Duration in seconds when returned."},"hashtags":{"type":["array","null"],"description":"Hashtags with platform or derived_text provenance.","items":{"type":["object","null"],"description":"Entity observed at source or derived from text.","properties":{"name":{"type":["string","null"],"description":"Hashtag or account name."},"id":{"type":["string","null"],"description":"Platform ID when supplied."},"source":{"type":["string","null"],"description":"platform or derived_text."}}}},"mentions":{"type":["array","null"],"description":"Mentions with platform or derived_text provenance; text is not proof of an account relationship.","items":{"type":["object","null"],"description":"Entity observed at source or derived from text.","properties":{"name":{"type":["string","null"],"description":"Hashtag or account name."},"id":{"type":["string","null"],"description":"Platform ID when supplied."},"source":{"type":["string","null"],"description":"platform or derived_text."}}}},"caption":{"type":["string","null"],"description":"Public video description."},"shares":{"type":["number","null"],"description":"Observed shares."},"favorites":{"type":["number","null"],"description":"Observed collect count; null when absent."},"width":{"type":["number","null"],"description":"Video width in pixels."},"height":{"type":["number","null"],"description":"Video height in pixels."},"author_id":{"type":["string","null"],"description":"Stable creator ID when returned."},"author_display_name":{"type":["string","null"],"description":"Public display name."},"author_verified":{"type":["boolean","null"],"description":"Explicit creator verification state."},"author_avatar_url":{"type":["string","null"],"description":"Public creator avatar URL."},"region_code":{"type":["string","null"],"description":"Source content region code when exposed; not proof of creator residence."},"video_url":{"type":["string","null"],"description":"Public playback URL when supplied; may expire or require source request headers."},"subtitle_tracks":{"type":["array","null"],"description":"Subtitle links exposed by the public video; does not run transcription.","items":{"type":["object","null"],"description":"Subtitle track.","properties":{"language":{"type":["string","null"],"description":"Source language code."},"language_id":{"type":["string","null"],"description":"Source language identifier."},"url":{"type":["string","null"],"description":"Source subtitle URL."},"format":{"type":["string","null"],"description":"Subtitle format."}}}},"effects":{"type":["array","null"],"description":"Effect metadata exposed by the public page.","items":{"type":["object","null"],"description":"Effect.","properties":{"id":{"type":["string","null"],"description":"Effect ID."},"name":{"type":["string","null"],"description":"Effect name."}}}},"stickers":{"type":["array","null"],"description":"Sticker metadata exposed by the public page.","items":{"type":["object","null"],"description":"Sticker.","properties":{"type":{"type":["number","null"],"description":"Source sticker type."},"texts":{"type":["array","null"],"description":"Returned sticker text.","items":{"type":["string","null"],"description":"Text."}}}}},"music":{"type":["object","null"],"description":"Sound metadata from the public video.","properties":{"id":{"type":["string","null"],"description":"Sound ID."},"title":{"type":["string","null"],"description":"Sound title."},"author":{"type":["string","null"],"description":"Sound author."},"original":{"type":["boolean","null"],"description":"Source original-sound flag."},"duration_seconds":{"type":["number","null"],"description":"Sound duration."},"cover_url":{"type":["string","null"],"description":"Sound cover URL."},"play_url":{"type":["string","null"],"description":"Sound preview URL."}}},"playlist_id":{"type":["string","null"],"description":"Source playlist ID when returned."},"pinned":{"type":["boolean","null"],"description":"Explicit pinned-item state when returned."},"media_assets":{"type":["array","null"],"description":"Returned cover variants.","items":{"type":["object","null"],"description":"One source media variant; URLs may expire.","properties":{"url":{"type":["string","null"],"description":"Source URL."},"width":{"type":["number","null"],"description":"Width in pixels."},"height":{"type":["number","null"],"description":"Height in pixels."},"asset_type":{"type":["string","null"],"description":"image, video, thumbnail or avatar."},"variant":{"type":["string","null"],"description":"Source variant when known."},"expires_at":{"type":["string","null"],"description":"Expiry timestamp when known."}}}}}}}}}}}]}}}},"400":{"$ref":"#/components/responses/InvalidInput"},"401":{"$ref":"#/components/responses/InvalidApiKey"},"402":{"$ref":"#/components/responses/InsufficientCredits"},"403":{"$ref":"#/components/responses/SourceRestricted"},"404":{"$ref":"#/components/responses/ResourceNotFound"},"408":{"$ref":"#/components/responses/SourceTimeout"},"422":{"$ref":"#/components/responses/SourceResponseChanged"},"429":{"$ref":"#/components/responses/TemporaryCapacity"},"501":{"$ref":"#/components/responses/SourceNotImplemented"},"503":{"$ref":"#/components/responses/SourceUnavailable"}},"x-availability":"planned","x-identifier-one-of":["query"],"x-credits":2,"x-source-access":"public_page","x-preview":true,"x-codeSamples":[{"lang":"curl","source":"curl 'https://api.socialdatakit.com/v1/tiktok/shop/search?query=headphones' \\\n  -H 'x-api-key: YOUR_API_KEY'"},{"lang":"javascript","source":"const response = await fetch(\"https://api.socialdatakit.com/v1/tiktok/shop/search?query=headphones\", {\n  headers: { \"x-api-key\": process.env.SOCIALDATAKIT_API_KEY }\n});\nif (!response.ok) throw new Error(await response.text());\nconst result = await response.json();"},{"lang":"python","source":"import os\nimport requests\n\nresponse = requests.get(\n    \"https://api.socialdatakit.com/v1/tiktok/shop/search?query=headphones\",\n    headers={\"x-api-key\": os.environ[\"SOCIALDATAKIT_API_KEY\"]},\n    timeout=30,\n)\nresponse.raise_for_status()\nresult = response.json()"}],"x-response-fields":{"id":{"type":"string","description":"Resource identifier used by this endpoint."},"author":{"type":"string","description":"Public creator name or handle."},"published_at":{"type":"string","description":"Source publication date or timestamp; null when absent."},"views":{"type":"number","description":"Observed views, where exposed by this source."},"likes":{"type":"number","description":"Observed likes."},"comments":{"type":"number","description":"Observed comment count, not comment rows."},"media_url":{"type":"string","description":"Preview image URL; not a guaranteed downloadable video."},"permalink":{"type":"string","description":"Public content URL."},"duration_seconds":{"type":"number","description":"Duration in seconds when returned."},"hashtags":{"type":"array","description":"Hashtags with platform or derived_text provenance.","items":{"type":"object","description":"Entity observed at source or derived from text.","properties":{"name":{"type":"string","description":"Hashtag or account name."},"id":{"type":"string","description":"Platform ID when supplied."},"source":{"type":"string","description":"platform or derived_text."}}}},"mentions":{"type":"array","description":"Mentions with platform or derived_text provenance; text is not proof of an account relationship.","items":{"type":"object","description":"Entity observed at source or derived from text.","properties":{"name":{"type":"string","description":"Hashtag or account name."},"id":{"type":"string","description":"Platform ID when supplied."},"source":{"type":"string","description":"platform or derived_text."}}}},"caption":{"type":"string","description":"Public video description."},"shares":{"type":"number","description":"Observed shares."},"favorites":{"type":"number","description":"Observed collect count; null when absent."},"width":{"type":"number","description":"Video width in pixels."},"height":{"type":"number","description":"Video height in pixels."},"author_id":{"type":"string","description":"Stable creator ID when returned."},"author_display_name":{"type":"string","description":"Public display name."},"author_verified":{"type":"boolean","description":"Explicit creator verification state."},"author_avatar_url":{"type":"string","description":"Public creator avatar URL."},"region_code":{"type":"string","description":"Source content region code when exposed; not proof of creator residence."},"video_url":{"type":"string","description":"Public playback URL when supplied; may expire or require source request headers."},"subtitle_tracks":{"type":"array","description":"Subtitle links exposed by the public video; does not run transcription.","items":{"type":"object","description":"Subtitle track.","properties":{"language":{"type":"string","description":"Source language code."},"language_id":{"type":"string","description":"Source language identifier."},"url":{"type":"string","description":"Source subtitle URL."},"format":{"type":"string","description":"Subtitle format."}}}},"effects":{"type":"array","description":"Effect metadata exposed by the public page.","items":{"type":"object","description":"Effect.","properties":{"id":{"type":"string","description":"Effect ID."},"name":{"type":"string","description":"Effect name."}}}},"stickers":{"type":"array","description":"Sticker metadata exposed by the public page.","items":{"type":"object","description":"Sticker.","properties":{"type":{"type":"number","description":"Source sticker type."},"texts":{"type":"array","description":"Returned sticker text.","items":{"type":"string","description":"Text."}}}}},"music":{"type":"object","description":"Sound metadata from the public video.","properties":{"id":{"type":"string","description":"Sound ID."},"title":{"type":"string","description":"Sound title."},"author":{"type":"string","description":"Sound author."},"original":{"type":"boolean","description":"Source original-sound flag."},"duration_seconds":{"type":"number","description":"Sound duration."},"cover_url":{"type":"string","description":"Sound cover URL."},"play_url":{"type":"string","description":"Sound preview URL."}}},"playlist_id":{"type":"string","description":"Source playlist ID when returned."},"pinned":{"type":"boolean","description":"Explicit pinned-item state when returned."},"media_assets":{"type":"array","description":"Returned cover variants.","items":{"type":"object","description":"One source media variant; URLs may expire.","properties":{"url":{"type":"string","description":"Source URL."},"width":{"type":"number","description":"Width in pixels."},"height":{"type":"number","description":"Height in pixels."},"asset_type":{"type":"string","description":"image, video, thumbnail or avatar."},"variant":{"type":"string","description":"Source variant when known."},"expires_at":{"type":"string","description":"Expiry timestamp when known."}}}}}}},"/v1/tiktok/shop/products":{"get":{"operationId":"tiktok_v1_shop_products","summary":"TikTok Shop store products","description":"Get products listed by a public store. Planned: returns 501 SOURCE_NOT_IMPLEMENTED; no collector or sample response is available and no credits are charged.","tags":["tiktok"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"url","in":"query","required":true,"schema":{"type":"string","pattern":"^https?://[^\\s]{5,400}$","example":"https://www.tiktok.com/shop/store/example"},"description":"Required tiktok url."},{"name":"cache_max_age","in":"query","required":false,"schema":{"type":"string","enum":["1d","3d","7d","14d","30d"]},"description":"Maximum acceptable cache age. Valid cache hits cost zero credits."},{"name":"fields","in":"query","required":false,"schema":{"type":"string","example":"items"},"description":"Comma-separated fields or dot paths, including inside arrays such as items.id. Response identity and pagination are retained."},{"name":"trim","in":"query","required":false,"schema":{"type":"boolean","default":false},"description":"Remove null and empty values. Meaningful empty YouTube region-restriction lists are retained."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":20,"default":3},"description":"Number of items to return."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"},"description":"Opaque pagination value returned as data.pagination.next_cursor. Keep the identifier, filters and limit unchanged."}],"responses":{"200":{"description":"Normalized resource","headers":{"x-request-id":{"schema":{"type":"string"}},"x-data-mode":{"schema":{"type":"string","enum":["live","sandbox"]}},"x-cache":{"schema":{"type":"string","enum":["HIT","MISS"]}},"x-credits-charged":{"schema":{"type":"integer"}},"x-credits-remaining":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"data":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","additionalProperties":true,"properties":{"id":{"type":["string","null"],"description":"Resource identifier used by this endpoint."},"author":{"type":["string","null"],"description":"Public creator name or handle."},"published_at":{"type":["string","null"],"description":"Source publication date or timestamp; null when absent."},"views":{"type":["number","null"],"description":"Observed views, where exposed by this source."},"likes":{"type":["number","null"],"description":"Observed likes."},"comments":{"type":["number","null"],"description":"Observed comment count, not comment rows."},"media_url":{"type":["string","null"],"description":"Preview image URL; not a guaranteed downloadable video."},"permalink":{"type":["string","null"],"description":"Public content URL."},"duration_seconds":{"type":["number","null"],"description":"Duration in seconds when returned."},"hashtags":{"type":["array","null"],"description":"Hashtags with platform or derived_text provenance.","items":{"type":["object","null"],"description":"Entity observed at source or derived from text.","properties":{"name":{"type":["string","null"],"description":"Hashtag or account name."},"id":{"type":["string","null"],"description":"Platform ID when supplied."},"source":{"type":["string","null"],"description":"platform or derived_text."}}}},"mentions":{"type":["array","null"],"description":"Mentions with platform or derived_text provenance; text is not proof of an account relationship.","items":{"type":["object","null"],"description":"Entity observed at source or derived from text.","properties":{"name":{"type":["string","null"],"description":"Hashtag or account name."},"id":{"type":["string","null"],"description":"Platform ID when supplied."},"source":{"type":["string","null"],"description":"platform or derived_text."}}}},"caption":{"type":["string","null"],"description":"Public video description."},"shares":{"type":["number","null"],"description":"Observed shares."},"favorites":{"type":["number","null"],"description":"Observed collect count; null when absent."},"width":{"type":["number","null"],"description":"Video width in pixels."},"height":{"type":["number","null"],"description":"Video height in pixels."},"author_id":{"type":["string","null"],"description":"Stable creator ID when returned."},"author_display_name":{"type":["string","null"],"description":"Public display name."},"author_verified":{"type":["boolean","null"],"description":"Explicit creator verification state."},"author_avatar_url":{"type":["string","null"],"description":"Public creator avatar URL."},"region_code":{"type":["string","null"],"description":"Source content region code when exposed; not proof of creator residence."},"video_url":{"type":["string","null"],"description":"Public playback URL when supplied; may expire or require source request headers."},"subtitle_tracks":{"type":["array","null"],"description":"Subtitle links exposed by the public video; does not run transcription.","items":{"type":["object","null"],"description":"Subtitle track.","properties":{"language":{"type":["string","null"],"description":"Source language code."},"language_id":{"type":["string","null"],"description":"Source language identifier."},"url":{"type":["string","null"],"description":"Source subtitle URL."},"format":{"type":["string","null"],"description":"Subtitle format."}}}},"effects":{"type":["array","null"],"description":"Effect metadata exposed by the public page.","items":{"type":["object","null"],"description":"Effect.","properties":{"id":{"type":["string","null"],"description":"Effect ID."},"name":{"type":["string","null"],"description":"Effect name."}}}},"stickers":{"type":["array","null"],"description":"Sticker metadata exposed by the public page.","items":{"type":["object","null"],"description":"Sticker.","properties":{"type":{"type":["number","null"],"description":"Source sticker type."},"texts":{"type":["array","null"],"description":"Returned sticker text.","items":{"type":["string","null"],"description":"Text."}}}}},"music":{"type":["object","null"],"description":"Sound metadata from the public video.","properties":{"id":{"type":["string","null"],"description":"Sound ID."},"title":{"type":["string","null"],"description":"Sound title."},"author":{"type":["string","null"],"description":"Sound author."},"original":{"type":["boolean","null"],"description":"Source original-sound flag."},"duration_seconds":{"type":["number","null"],"description":"Sound duration."},"cover_url":{"type":["string","null"],"description":"Sound cover URL."},"play_url":{"type":["string","null"],"description":"Sound preview URL."}}},"playlist_id":{"type":["string","null"],"description":"Source playlist ID when returned."},"pinned":{"type":["boolean","null"],"description":"Explicit pinned-item state when returned."},"media_assets":{"type":["array","null"],"description":"Returned cover variants.","items":{"type":["object","null"],"description":"One source media variant; URLs may expire.","properties":{"url":{"type":["string","null"],"description":"Source URL."},"width":{"type":["number","null"],"description":"Width in pixels."},"height":{"type":["number","null"],"description":"Height in pixels."},"asset_type":{"type":["string","null"],"description":"image, video, thumbnail or avatar."},"variant":{"type":["string","null"],"description":"Source variant when known."},"expires_at":{"type":["string","null"],"description":"Expiry timestamp when known."}}}}}}}}}}}]}}}},"400":{"$ref":"#/components/responses/InvalidInput"},"401":{"$ref":"#/components/responses/InvalidApiKey"},"402":{"$ref":"#/components/responses/InsufficientCredits"},"403":{"$ref":"#/components/responses/SourceRestricted"},"404":{"$ref":"#/components/responses/ResourceNotFound"},"408":{"$ref":"#/components/responses/SourceTimeout"},"422":{"$ref":"#/components/responses/SourceResponseChanged"},"429":{"$ref":"#/components/responses/TemporaryCapacity"},"501":{"$ref":"#/components/responses/SourceNotImplemented"},"503":{"$ref":"#/components/responses/SourceUnavailable"}},"x-availability":"planned","x-identifier-one-of":["url"],"x-credits":2,"x-source-access":"public_page","x-preview":true,"x-codeSamples":[{"lang":"curl","source":"curl 'https://api.socialdatakit.com/v1/tiktok/shop/products?url=https%3A%2F%2Fwww.tiktok.com%2Fshop%2Fstore%2Fexample' \\\n  -H 'x-api-key: YOUR_API_KEY'"},{"lang":"javascript","source":"const response = await fetch(\"https://api.socialdatakit.com/v1/tiktok/shop/products?url=https%3A%2F%2Fwww.tiktok.com%2Fshop%2Fstore%2Fexample\", {\n  headers: { \"x-api-key\": process.env.SOCIALDATAKIT_API_KEY }\n});\nif (!response.ok) throw new Error(await response.text());\nconst result = await response.json();"},{"lang":"python","source":"import os\nimport requests\n\nresponse = requests.get(\n    \"https://api.socialdatakit.com/v1/tiktok/shop/products?url=https%3A%2F%2Fwww.tiktok.com%2Fshop%2Fstore%2Fexample\",\n    headers={\"x-api-key\": os.environ[\"SOCIALDATAKIT_API_KEY\"]},\n    timeout=30,\n)\nresponse.raise_for_status()\nresult = response.json()"}],"x-response-fields":{"id":{"type":"string","description":"Resource identifier used by this endpoint."},"author":{"type":"string","description":"Public creator name or handle."},"published_at":{"type":"string","description":"Source publication date or timestamp; null when absent."},"views":{"type":"number","description":"Observed views, where exposed by this source."},"likes":{"type":"number","description":"Observed likes."},"comments":{"type":"number","description":"Observed comment count, not comment rows."},"media_url":{"type":"string","description":"Preview image URL; not a guaranteed downloadable video."},"permalink":{"type":"string","description":"Public content URL."},"duration_seconds":{"type":"number","description":"Duration in seconds when returned."},"hashtags":{"type":"array","description":"Hashtags with platform or derived_text provenance.","items":{"type":"object","description":"Entity observed at source or derived from text.","properties":{"name":{"type":"string","description":"Hashtag or account name."},"id":{"type":"string","description":"Platform ID when supplied."},"source":{"type":"string","description":"platform or derived_text."}}}},"mentions":{"type":"array","description":"Mentions with platform or derived_text provenance; text is not proof of an account relationship.","items":{"type":"object","description":"Entity observed at source or derived from text.","properties":{"name":{"type":"string","description":"Hashtag or account name."},"id":{"type":"string","description":"Platform ID when supplied."},"source":{"type":"string","description":"platform or derived_text."}}}},"caption":{"type":"string","description":"Public video description."},"shares":{"type":"number","description":"Observed shares."},"favorites":{"type":"number","description":"Observed collect count; null when absent."},"width":{"type":"number","description":"Video width in pixels."},"height":{"type":"number","description":"Video height in pixels."},"author_id":{"type":"string","description":"Stable creator ID when returned."},"author_display_name":{"type":"string","description":"Public display name."},"author_verified":{"type":"boolean","description":"Explicit creator verification state."},"author_avatar_url":{"type":"string","description":"Public creator avatar URL."},"region_code":{"type":"string","description":"Source content region code when exposed; not proof of creator residence."},"video_url":{"type":"string","description":"Public playback URL when supplied; may expire or require source request headers."},"subtitle_tracks":{"type":"array","description":"Subtitle links exposed by the public video; does not run transcription.","items":{"type":"object","description":"Subtitle track.","properties":{"language":{"type":"string","description":"Source language code."},"language_id":{"type":"string","description":"Source language identifier."},"url":{"type":"string","description":"Source subtitle URL."},"format":{"type":"string","description":"Subtitle format."}}}},"effects":{"type":"array","description":"Effect metadata exposed by the public page.","items":{"type":"object","description":"Effect.","properties":{"id":{"type":"string","description":"Effect ID."},"name":{"type":"string","description":"Effect name."}}}},"stickers":{"type":"array","description":"Sticker metadata exposed by the public page.","items":{"type":"object","description":"Sticker.","properties":{"type":{"type":"number","description":"Source sticker type."},"texts":{"type":"array","description":"Returned sticker text.","items":{"type":"string","description":"Text."}}}}},"music":{"type":"object","description":"Sound metadata from the public video.","properties":{"id":{"type":"string","description":"Sound ID."},"title":{"type":"string","description":"Sound title."},"author":{"type":"string","description":"Sound author."},"original":{"type":"boolean","description":"Source original-sound flag."},"duration_seconds":{"type":"number","description":"Sound duration."},"cover_url":{"type":"string","description":"Sound cover URL."},"play_url":{"type":"string","description":"Sound preview URL."}}},"playlist_id":{"type":"string","description":"Source playlist ID when returned."},"pinned":{"type":"boolean","description":"Explicit pinned-item state when returned."},"media_assets":{"type":"array","description":"Returned cover variants.","items":{"type":"object","description":"One source media variant; URLs may expire.","properties":{"url":{"type":"string","description":"Source URL."},"width":{"type":"number","description":"Width in pixels."},"height":{"type":"number","description":"Height in pixels."},"asset_type":{"type":"string","description":"image, video, thumbnail or avatar."},"variant":{"type":"string","description":"Source variant when known."},"expires_at":{"type":"string","description":"Expiry timestamp when known."}}}}}}},"/v1/tiktok/product":{"get":{"operationId":"tiktok_v1_product","summary":"TikTok product","description":"Get a public product's detail. Planned: returns 501 SOURCE_NOT_IMPLEMENTED; no collector or sample response is available and no credits are charged.","tags":["tiktok"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"url","in":"query","required":true,"schema":{"type":"string","pattern":"^https?://[^\\s]{5,400}$","example":"https://www.tiktok.com/shop/pdp/example"},"description":"Required tiktok url."},{"name":"cache_max_age","in":"query","required":false,"schema":{"type":"string","enum":["1d","3d","7d","14d","30d"]},"description":"Maximum acceptable cache age. Valid cache hits cost zero credits."},{"name":"fields","in":"query","required":false,"schema":{"type":"string","example":"item"},"description":"Comma-separated fields or dot paths, including inside arrays such as items.id. Response identity and pagination are retained."},{"name":"trim","in":"query","required":false,"schema":{"type":"boolean","default":false},"description":"Remove null and empty values. Meaningful empty YouTube region-restriction lists are retained."}],"responses":{"200":{"description":"Normalized resource","headers":{"x-request-id":{"schema":{"type":"string"}},"x-data-mode":{"schema":{"type":"string","enum":["live","sandbox"]}},"x-cache":{"schema":{"type":"string","enum":["HIT","MISS"]}},"x-credits-charged":{"schema":{"type":"integer"}},"x-credits-remaining":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"data":{"type":"object","properties":{"item":{"type":"object","additionalProperties":true,"properties":{"id":{"type":["string","null"],"description":"Resource identifier used by this endpoint."},"author":{"type":["string","null"],"description":"Public creator name or handle."},"published_at":{"type":["string","null"],"description":"Source publication date or timestamp; null when absent."},"views":{"type":["number","null"],"description":"Observed views, where exposed by this source."},"likes":{"type":["number","null"],"description":"Observed likes."},"comments":{"type":["number","null"],"description":"Observed comment count, not comment rows."},"media_url":{"type":["string","null"],"description":"Preview image URL; not a guaranteed downloadable video."},"permalink":{"type":["string","null"],"description":"Public content URL."},"duration_seconds":{"type":["number","null"],"description":"Duration in seconds when returned."},"hashtags":{"type":["array","null"],"description":"Hashtags with platform or derived_text provenance.","items":{"type":["object","null"],"description":"Entity observed at source or derived from text.","properties":{"name":{"type":["string","null"],"description":"Hashtag or account name."},"id":{"type":["string","null"],"description":"Platform ID when supplied."},"source":{"type":["string","null"],"description":"platform or derived_text."}}}},"mentions":{"type":["array","null"],"description":"Mentions with platform or derived_text provenance; text is not proof of an account relationship.","items":{"type":["object","null"],"description":"Entity observed at source or derived from text.","properties":{"name":{"type":["string","null"],"description":"Hashtag or account name."},"id":{"type":["string","null"],"description":"Platform ID when supplied."},"source":{"type":["string","null"],"description":"platform or derived_text."}}}},"caption":{"type":["string","null"],"description":"Public video description."},"shares":{"type":["number","null"],"description":"Observed shares."},"favorites":{"type":["number","null"],"description":"Observed collect count; null when absent."},"width":{"type":["number","null"],"description":"Video width in pixels."},"height":{"type":["number","null"],"description":"Video height in pixels."},"author_id":{"type":["string","null"],"description":"Stable creator ID when returned."},"author_display_name":{"type":["string","null"],"description":"Public display name."},"author_verified":{"type":["boolean","null"],"description":"Explicit creator verification state."},"author_avatar_url":{"type":["string","null"],"description":"Public creator avatar URL."},"region_code":{"type":["string","null"],"description":"Source content region code when exposed; not proof of creator residence."},"video_url":{"type":["string","null"],"description":"Public playback URL when supplied; may expire or require source request headers."},"subtitle_tracks":{"type":["array","null"],"description":"Subtitle links exposed by the public video; does not run transcription.","items":{"type":["object","null"],"description":"Subtitle track.","properties":{"language":{"type":["string","null"],"description":"Source language code."},"language_id":{"type":["string","null"],"description":"Source language identifier."},"url":{"type":["string","null"],"description":"Source subtitle URL."},"format":{"type":["string","null"],"description":"Subtitle format."}}}},"effects":{"type":["array","null"],"description":"Effect metadata exposed by the public page.","items":{"type":["object","null"],"description":"Effect.","properties":{"id":{"type":["string","null"],"description":"Effect ID."},"name":{"type":["string","null"],"description":"Effect name."}}}},"stickers":{"type":["array","null"],"description":"Sticker metadata exposed by the public page.","items":{"type":["object","null"],"description":"Sticker.","properties":{"type":{"type":["number","null"],"description":"Source sticker type."},"texts":{"type":["array","null"],"description":"Returned sticker text.","items":{"type":["string","null"],"description":"Text."}}}}},"music":{"type":["object","null"],"description":"Sound metadata from the public video.","properties":{"id":{"type":["string","null"],"description":"Sound ID."},"title":{"type":["string","null"],"description":"Sound title."},"author":{"type":["string","null"],"description":"Sound author."},"original":{"type":["boolean","null"],"description":"Source original-sound flag."},"duration_seconds":{"type":["number","null"],"description":"Sound duration."},"cover_url":{"type":["string","null"],"description":"Sound cover URL."},"play_url":{"type":["string","null"],"description":"Sound preview URL."}}},"playlist_id":{"type":["string","null"],"description":"Source playlist ID when returned."},"pinned":{"type":["boolean","null"],"description":"Explicit pinned-item state when returned."},"media_assets":{"type":["array","null"],"description":"Returned cover variants.","items":{"type":["object","null"],"description":"One source media variant; URLs may expire.","properties":{"url":{"type":["string","null"],"description":"Source URL."},"width":{"type":["number","null"],"description":"Width in pixels."},"height":{"type":["number","null"],"description":"Height in pixels."},"asset_type":{"type":["string","null"],"description":"image, video, thumbnail or avatar."},"variant":{"type":["string","null"],"description":"Source variant when known."},"expires_at":{"type":["string","null"],"description":"Expiry timestamp when known."}}}}}}}}}}]}}}},"400":{"$ref":"#/components/responses/InvalidInput"},"401":{"$ref":"#/components/responses/InvalidApiKey"},"402":{"$ref":"#/components/responses/InsufficientCredits"},"403":{"$ref":"#/components/responses/SourceRestricted"},"404":{"$ref":"#/components/responses/ResourceNotFound"},"408":{"$ref":"#/components/responses/SourceTimeout"},"422":{"$ref":"#/components/responses/SourceResponseChanged"},"429":{"$ref":"#/components/responses/TemporaryCapacity"},"501":{"$ref":"#/components/responses/SourceNotImplemented"},"503":{"$ref":"#/components/responses/SourceUnavailable"}},"x-availability":"planned","x-identifier-one-of":["url"],"x-credits":1,"x-source-access":"public_page","x-preview":true,"x-codeSamples":[{"lang":"curl","source":"curl 'https://api.socialdatakit.com/v1/tiktok/product?url=https%3A%2F%2Fwww.tiktok.com%2Fshop%2Fpdp%2Fexample' \\\n  -H 'x-api-key: YOUR_API_KEY'"},{"lang":"javascript","source":"const response = await fetch(\"https://api.socialdatakit.com/v1/tiktok/product?url=https%3A%2F%2Fwww.tiktok.com%2Fshop%2Fpdp%2Fexample\", {\n  headers: { \"x-api-key\": process.env.SOCIALDATAKIT_API_KEY }\n});\nif (!response.ok) throw new Error(await response.text());\nconst result = await response.json();"},{"lang":"python","source":"import os\nimport requests\n\nresponse = requests.get(\n    \"https://api.socialdatakit.com/v1/tiktok/product?url=https%3A%2F%2Fwww.tiktok.com%2Fshop%2Fpdp%2Fexample\",\n    headers={\"x-api-key\": os.environ[\"SOCIALDATAKIT_API_KEY\"]},\n    timeout=30,\n)\nresponse.raise_for_status()\nresult = response.json()"}],"x-response-fields":{"id":{"type":"string","description":"Resource identifier used by this endpoint."},"author":{"type":"string","description":"Public creator name or handle."},"published_at":{"type":"string","description":"Source publication date or timestamp; null when absent."},"views":{"type":"number","description":"Observed views, where exposed by this source."},"likes":{"type":"number","description":"Observed likes."},"comments":{"type":"number","description":"Observed comment count, not comment rows."},"media_url":{"type":"string","description":"Preview image URL; not a guaranteed downloadable video."},"permalink":{"type":"string","description":"Public content URL."},"duration_seconds":{"type":"number","description":"Duration in seconds when returned."},"hashtags":{"type":"array","description":"Hashtags with platform or derived_text provenance.","items":{"type":"object","description":"Entity observed at source or derived from text.","properties":{"name":{"type":"string","description":"Hashtag or account name."},"id":{"type":"string","description":"Platform ID when supplied."},"source":{"type":"string","description":"platform or derived_text."}}}},"mentions":{"type":"array","description":"Mentions with platform or derived_text provenance; text is not proof of an account relationship.","items":{"type":"object","description":"Entity observed at source or derived from text.","properties":{"name":{"type":"string","description":"Hashtag or account name."},"id":{"type":"string","description":"Platform ID when supplied."},"source":{"type":"string","description":"platform or derived_text."}}}},"caption":{"type":"string","description":"Public video description."},"shares":{"type":"number","description":"Observed shares."},"favorites":{"type":"number","description":"Observed collect count; null when absent."},"width":{"type":"number","description":"Video width in pixels."},"height":{"type":"number","description":"Video height in pixels."},"author_id":{"type":"string","description":"Stable creator ID when returned."},"author_display_name":{"type":"string","description":"Public display name."},"author_verified":{"type":"boolean","description":"Explicit creator verification state."},"author_avatar_url":{"type":"string","description":"Public creator avatar URL."},"region_code":{"type":"string","description":"Source content region code when exposed; not proof of creator residence."},"video_url":{"type":"string","description":"Public playback URL when supplied; may expire or require source request headers."},"subtitle_tracks":{"type":"array","description":"Subtitle links exposed by the public video; does not run transcription.","items":{"type":"object","description":"Subtitle track.","properties":{"language":{"type":"string","description":"Source language code."},"language_id":{"type":"string","description":"Source language identifier."},"url":{"type":"string","description":"Source subtitle URL."},"format":{"type":"string","description":"Subtitle format."}}}},"effects":{"type":"array","description":"Effect metadata exposed by the public page.","items":{"type":"object","description":"Effect.","properties":{"id":{"type":"string","description":"Effect ID."},"name":{"type":"string","description":"Effect name."}}}},"stickers":{"type":"array","description":"Sticker metadata exposed by the public page.","items":{"type":"object","description":"Sticker.","properties":{"type":{"type":"number","description":"Source sticker type."},"texts":{"type":"array","description":"Returned sticker text.","items":{"type":"string","description":"Text."}}}}},"music":{"type":"object","description":"Sound metadata from the public video.","properties":{"id":{"type":"string","description":"Sound ID."},"title":{"type":"string","description":"Sound title."},"author":{"type":"string","description":"Sound author."},"original":{"type":"boolean","description":"Source original-sound flag."},"duration_seconds":{"type":"number","description":"Sound duration."},"cover_url":{"type":"string","description":"Sound cover URL."},"play_url":{"type":"string","description":"Sound preview URL."}}},"playlist_id":{"type":"string","description":"Source playlist ID when returned."},"pinned":{"type":"boolean","description":"Explicit pinned-item state when returned."},"media_assets":{"type":"array","description":"Returned cover variants.","items":{"type":"object","description":"One source media variant; URLs may expire.","properties":{"url":{"type":"string","description":"Source URL."},"width":{"type":"number","description":"Width in pixels."},"height":{"type":"number","description":"Height in pixels."},"asset_type":{"type":"string","description":"image, video, thumbnail or avatar."},"variant":{"type":"string","description":"Source variant when known."},"expires_at":{"type":"string","description":"Expiry timestamp when known."}}}}}}},"/v1/tiktok/shop/product/reviews":{"get":{"operationId":"tiktok_v1_shop_product_reviews","summary":"TikTok product reviews","description":"Get public reviews for a product. Planned: returns 501 SOURCE_NOT_IMPLEMENTED; no collector or sample response is available and no credits are charged.","tags":["tiktok"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"url","in":"query","required":true,"schema":{"type":"string","pattern":"^https?://[^\\s]{5,400}$","example":"https://www.tiktok.com/shop/pdp/example"},"description":"Required tiktok url."},{"name":"cache_max_age","in":"query","required":false,"schema":{"type":"string","enum":["1d","3d","7d","14d","30d"]},"description":"Maximum acceptable cache age. Valid cache hits cost zero credits."},{"name":"fields","in":"query","required":false,"schema":{"type":"string","example":"items"},"description":"Comma-separated fields or dot paths, including inside arrays such as items.id. Response identity and pagination are retained."},{"name":"trim","in":"query","required":false,"schema":{"type":"boolean","default":false},"description":"Remove null and empty values. Meaningful empty YouTube region-restriction lists are retained."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":20,"default":3},"description":"Number of items to return."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"},"description":"Opaque pagination value returned as data.pagination.next_cursor. Keep the identifier, filters and limit unchanged."}],"responses":{"200":{"description":"Normalized resource","headers":{"x-request-id":{"schema":{"type":"string"}},"x-data-mode":{"schema":{"type":"string","enum":["live","sandbox"]}},"x-cache":{"schema":{"type":"string","enum":["HIT","MISS"]}},"x-credits-charged":{"schema":{"type":"integer"}},"x-credits-remaining":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"data":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","additionalProperties":true,"properties":{"id":{"type":["string","null"],"description":"Platform comment ID, retained as a string."},"content_id":{"type":["string","null"],"description":"Parent video/post ID when known."},"parent_comment_id":{"type":["string","null"],"description":"Top-level comment ID for a reply; null for a top-level comment or unknown parent."},"text":{"type":["string","null"],"description":"Public comment text. YouTube requests plainText formatting; no owner-only textOriginal."},"likes":{"type":["number","null"],"description":"Observed comment likes."},"reply_count":{"type":["number","null"],"description":"Observed total reply count; not the number of replies returned."},"author_id":{"type":["string","null"],"description":"Public author account ID."},"author_username":{"type":["string","null"],"description":"Public author handle."},"author_display_name":{"type":["string","null"],"description":"Public display name."},"author_avatar_url":{"type":["string","null"],"description":"Public avatar URL."},"author_profile_url":{"type":["string","null"],"description":"Public author profile URL."},"published_at":{"type":["string","null"],"description":"Comment publication timestamp."},"updated_at":{"type":["string","null"],"description":"Source edit timestamp when available."}}}}}}}}]}}}},"400":{"$ref":"#/components/responses/InvalidInput"},"401":{"$ref":"#/components/responses/InvalidApiKey"},"402":{"$ref":"#/components/responses/InsufficientCredits"},"403":{"$ref":"#/components/responses/SourceRestricted"},"404":{"$ref":"#/components/responses/ResourceNotFound"},"408":{"$ref":"#/components/responses/SourceTimeout"},"422":{"$ref":"#/components/responses/SourceResponseChanged"},"429":{"$ref":"#/components/responses/TemporaryCapacity"},"501":{"$ref":"#/components/responses/SourceNotImplemented"},"503":{"$ref":"#/components/responses/SourceUnavailable"}},"x-availability":"planned","x-identifier-one-of":["url"],"x-credits":2,"x-source-access":"public_page","x-preview":true,"x-codeSamples":[{"lang":"curl","source":"curl 'https://api.socialdatakit.com/v1/tiktok/shop/product/reviews?url=https%3A%2F%2Fwww.tiktok.com%2Fshop%2Fpdp%2Fexample' \\\n  -H 'x-api-key: YOUR_API_KEY'"},{"lang":"javascript","source":"const response = await fetch(\"https://api.socialdatakit.com/v1/tiktok/shop/product/reviews?url=https%3A%2F%2Fwww.tiktok.com%2Fshop%2Fpdp%2Fexample\", {\n  headers: { \"x-api-key\": process.env.SOCIALDATAKIT_API_KEY }\n});\nif (!response.ok) throw new Error(await response.text());\nconst result = await response.json();"},{"lang":"python","source":"import os\nimport requests\n\nresponse = requests.get(\n    \"https://api.socialdatakit.com/v1/tiktok/shop/product/reviews?url=https%3A%2F%2Fwww.tiktok.com%2Fshop%2Fpdp%2Fexample\",\n    headers={\"x-api-key\": os.environ[\"SOCIALDATAKIT_API_KEY\"]},\n    timeout=30,\n)\nresponse.raise_for_status()\nresult = response.json()"}],"x-response-fields":{"id":{"type":"string","description":"Platform comment ID, retained as a string."},"content_id":{"type":"string","description":"Parent video/post ID when known."},"parent_comment_id":{"type":"string","description":"Top-level comment ID for a reply; null for a top-level comment or unknown parent."},"text":{"type":"string","description":"Public comment text. YouTube requests plainText formatting; no owner-only textOriginal."},"likes":{"type":"number","description":"Observed comment likes."},"reply_count":{"type":"number","description":"Observed total reply count; not the number of replies returned."},"author_id":{"type":"string","description":"Public author account ID."},"author_username":{"type":"string","description":"Public author handle."},"author_display_name":{"type":"string","description":"Public display name."},"author_avatar_url":{"type":"string","description":"Public avatar URL."},"author_profile_url":{"type":"string","description":"Public author profile URL."},"published_at":{"type":"string","description":"Comment publication timestamp."},"updated_at":{"type":"string","description":"Source edit timestamp when available."}}}},"/v1/tiktok/user/showcase":{"get":{"operationId":"tiktok_v1_user_showcase","summary":"TikTok showcase","description":"Get products showcased on a public profile. Planned: returns 501 SOURCE_NOT_IMPLEMENTED; no collector or sample response is available and no credits are charged.","tags":["tiktok"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"handle","in":"query","required":true,"schema":{"type":"string","pattern":"^@?[A-Za-z0-9._]{2,24}$","example":"tiktok"},"description":"Required tiktok handle."},{"name":"cache_max_age","in":"query","required":false,"schema":{"type":"string","enum":["1d","3d","7d","14d","30d"]},"description":"Maximum acceptable cache age. Valid cache hits cost zero credits."},{"name":"fields","in":"query","required":false,"schema":{"type":"string","example":"items"},"description":"Comma-separated fields or dot paths, including inside arrays such as items.id. Response identity and pagination are retained."},{"name":"trim","in":"query","required":false,"schema":{"type":"boolean","default":false},"description":"Remove null and empty values. Meaningful empty YouTube region-restriction lists are retained."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":20,"default":3},"description":"Number of items to return."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"},"description":"Opaque pagination value returned as data.pagination.next_cursor. Keep the identifier, filters and limit unchanged."}],"responses":{"200":{"description":"Normalized resource","headers":{"x-request-id":{"schema":{"type":"string"}},"x-data-mode":{"schema":{"type":"string","enum":["live","sandbox"]}},"x-cache":{"schema":{"type":"string","enum":["HIT","MISS"]}},"x-credits-charged":{"schema":{"type":"integer"}},"x-credits-remaining":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"data":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","additionalProperties":true,"properties":{"id":{"type":["string","null"],"description":"Resource identifier used by this endpoint."},"author":{"type":["string","null"],"description":"Public creator name or handle."},"published_at":{"type":["string","null"],"description":"Source publication date or timestamp; null when absent."},"views":{"type":["number","null"],"description":"Observed views, where exposed by this source."},"likes":{"type":["number","null"],"description":"Observed likes."},"comments":{"type":["number","null"],"description":"Observed comment count, not comment rows."},"media_url":{"type":["string","null"],"description":"Preview image URL; not a guaranteed downloadable video."},"permalink":{"type":["string","null"],"description":"Public content URL."},"duration_seconds":{"type":["number","null"],"description":"Duration in seconds when returned."},"hashtags":{"type":["array","null"],"description":"Hashtags with platform or derived_text provenance.","items":{"type":["object","null"],"description":"Entity observed at source or derived from text.","properties":{"name":{"type":["string","null"],"description":"Hashtag or account name."},"id":{"type":["string","null"],"description":"Platform ID when supplied."},"source":{"type":["string","null"],"description":"platform or derived_text."}}}},"mentions":{"type":["array","null"],"description":"Mentions with platform or derived_text provenance; text is not proof of an account relationship.","items":{"type":["object","null"],"description":"Entity observed at source or derived from text.","properties":{"name":{"type":["string","null"],"description":"Hashtag or account name."},"id":{"type":["string","null"],"description":"Platform ID when supplied."},"source":{"type":["string","null"],"description":"platform or derived_text."}}}},"caption":{"type":["string","null"],"description":"Public video description."},"shares":{"type":["number","null"],"description":"Observed shares."},"favorites":{"type":["number","null"],"description":"Observed collect count; null when absent."},"width":{"type":["number","null"],"description":"Video width in pixels."},"height":{"type":["number","null"],"description":"Video height in pixels."},"author_id":{"type":["string","null"],"description":"Stable creator ID when returned."},"author_display_name":{"type":["string","null"],"description":"Public display name."},"author_verified":{"type":["boolean","null"],"description":"Explicit creator verification state."},"author_avatar_url":{"type":["string","null"],"description":"Public creator avatar URL."},"region_code":{"type":["string","null"],"description":"Source content region code when exposed; not proof of creator residence."},"video_url":{"type":["string","null"],"description":"Public playback URL when supplied; may expire or require source request headers."},"subtitle_tracks":{"type":["array","null"],"description":"Subtitle links exposed by the public video; does not run transcription.","items":{"type":["object","null"],"description":"Subtitle track.","properties":{"language":{"type":["string","null"],"description":"Source language code."},"language_id":{"type":["string","null"],"description":"Source language identifier."},"url":{"type":["string","null"],"description":"Source subtitle URL."},"format":{"type":["string","null"],"description":"Subtitle format."}}}},"effects":{"type":["array","null"],"description":"Effect metadata exposed by the public page.","items":{"type":["object","null"],"description":"Effect.","properties":{"id":{"type":["string","null"],"description":"Effect ID."},"name":{"type":["string","null"],"description":"Effect name."}}}},"stickers":{"type":["array","null"],"description":"Sticker metadata exposed by the public page.","items":{"type":["object","null"],"description":"Sticker.","properties":{"type":{"type":["number","null"],"description":"Source sticker type."},"texts":{"type":["array","null"],"description":"Returned sticker text.","items":{"type":["string","null"],"description":"Text."}}}}},"music":{"type":["object","null"],"description":"Sound metadata from the public video.","properties":{"id":{"type":["string","null"],"description":"Sound ID."},"title":{"type":["string","null"],"description":"Sound title."},"author":{"type":["string","null"],"description":"Sound author."},"original":{"type":["boolean","null"],"description":"Source original-sound flag."},"duration_seconds":{"type":["number","null"],"description":"Sound duration."},"cover_url":{"type":["string","null"],"description":"Sound cover URL."},"play_url":{"type":["string","null"],"description":"Sound preview URL."}}},"playlist_id":{"type":["string","null"],"description":"Source playlist ID when returned."},"pinned":{"type":["boolean","null"],"description":"Explicit pinned-item state when returned."},"media_assets":{"type":["array","null"],"description":"Returned cover variants.","items":{"type":["object","null"],"description":"One source media variant; URLs may expire.","properties":{"url":{"type":["string","null"],"description":"Source URL."},"width":{"type":["number","null"],"description":"Width in pixels."},"height":{"type":["number","null"],"description":"Height in pixels."},"asset_type":{"type":["string","null"],"description":"image, video, thumbnail or avatar."},"variant":{"type":["string","null"],"description":"Source variant when known."},"expires_at":{"type":["string","null"],"description":"Expiry timestamp when known."}}}}}}}}}}}]}}}},"400":{"$ref":"#/components/responses/InvalidInput"},"401":{"$ref":"#/components/responses/InvalidApiKey"},"402":{"$ref":"#/components/responses/InsufficientCredits"},"403":{"$ref":"#/components/responses/SourceRestricted"},"404":{"$ref":"#/components/responses/ResourceNotFound"},"408":{"$ref":"#/components/responses/SourceTimeout"},"422":{"$ref":"#/components/responses/SourceResponseChanged"},"429":{"$ref":"#/components/responses/TemporaryCapacity"},"501":{"$ref":"#/components/responses/SourceNotImplemented"},"503":{"$ref":"#/components/responses/SourceUnavailable"}},"x-availability":"planned","x-identifier-one-of":["handle"],"x-credits":2,"x-source-access":"public_page","x-preview":true,"x-codeSamples":[{"lang":"curl","source":"curl 'https://api.socialdatakit.com/v1/tiktok/user/showcase?handle=tiktok' \\\n  -H 'x-api-key: YOUR_API_KEY'"},{"lang":"javascript","source":"const response = await fetch(\"https://api.socialdatakit.com/v1/tiktok/user/showcase?handle=tiktok\", {\n  headers: { \"x-api-key\": process.env.SOCIALDATAKIT_API_KEY }\n});\nif (!response.ok) throw new Error(await response.text());\nconst result = await response.json();"},{"lang":"python","source":"import os\nimport requests\n\nresponse = requests.get(\n    \"https://api.socialdatakit.com/v1/tiktok/user/showcase?handle=tiktok\",\n    headers={\"x-api-key\": os.environ[\"SOCIALDATAKIT_API_KEY\"]},\n    timeout=30,\n)\nresponse.raise_for_status()\nresult = response.json()"}],"x-response-fields":{"id":{"type":"string","description":"Resource identifier used by this endpoint."},"author":{"type":"string","description":"Public creator name or handle."},"published_at":{"type":"string","description":"Source publication date or timestamp; null when absent."},"views":{"type":"number","description":"Observed views, where exposed by this source."},"likes":{"type":"number","description":"Observed likes."},"comments":{"type":"number","description":"Observed comment count, not comment rows."},"media_url":{"type":"string","description":"Preview image URL; not a guaranteed downloadable video."},"permalink":{"type":"string","description":"Public content URL."},"duration_seconds":{"type":"number","description":"Duration in seconds when returned."},"hashtags":{"type":"array","description":"Hashtags with platform or derived_text provenance.","items":{"type":"object","description":"Entity observed at source or derived from text.","properties":{"name":{"type":"string","description":"Hashtag or account name."},"id":{"type":"string","description":"Platform ID when supplied."},"source":{"type":"string","description":"platform or derived_text."}}}},"mentions":{"type":"array","description":"Mentions with platform or derived_text provenance; text is not proof of an account relationship.","items":{"type":"object","description":"Entity observed at source or derived from text.","properties":{"name":{"type":"string","description":"Hashtag or account name."},"id":{"type":"string","description":"Platform ID when supplied."},"source":{"type":"string","description":"platform or derived_text."}}}},"caption":{"type":"string","description":"Public video description."},"shares":{"type":"number","description":"Observed shares."},"favorites":{"type":"number","description":"Observed collect count; null when absent."},"width":{"type":"number","description":"Video width in pixels."},"height":{"type":"number","description":"Video height in pixels."},"author_id":{"type":"string","description":"Stable creator ID when returned."},"author_display_name":{"type":"string","description":"Public display name."},"author_verified":{"type":"boolean","description":"Explicit creator verification state."},"author_avatar_url":{"type":"string","description":"Public creator avatar URL."},"region_code":{"type":"string","description":"Source content region code when exposed; not proof of creator residence."},"video_url":{"type":"string","description":"Public playback URL when supplied; may expire or require source request headers."},"subtitle_tracks":{"type":"array","description":"Subtitle links exposed by the public video; does not run transcription.","items":{"type":"object","description":"Subtitle track.","properties":{"language":{"type":"string","description":"Source language code."},"language_id":{"type":"string","description":"Source language identifier."},"url":{"type":"string","description":"Source subtitle URL."},"format":{"type":"string","description":"Subtitle format."}}}},"effects":{"type":"array","description":"Effect metadata exposed by the public page.","items":{"type":"object","description":"Effect.","properties":{"id":{"type":"string","description":"Effect ID."},"name":{"type":"string","description":"Effect name."}}}},"stickers":{"type":"array","description":"Sticker metadata exposed by the public page.","items":{"type":"object","description":"Sticker.","properties":{"type":{"type":"number","description":"Source sticker type."},"texts":{"type":"array","description":"Returned sticker text.","items":{"type":"string","description":"Text."}}}}},"music":{"type":"object","description":"Sound metadata from the public video.","properties":{"id":{"type":"string","description":"Sound ID."},"title":{"type":"string","description":"Sound title."},"author":{"type":"string","description":"Sound author."},"original":{"type":"boolean","description":"Source original-sound flag."},"duration_seconds":{"type":"number","description":"Sound duration."},"cover_url":{"type":"string","description":"Sound cover URL."},"play_url":{"type":"string","description":"Sound preview URL."}}},"playlist_id":{"type":"string","description":"Source playlist ID when returned."},"pinned":{"type":"boolean","description":"Explicit pinned-item state when returned."},"media_assets":{"type":"array","description":"Returned cover variants.","items":{"type":"object","description":"One source media variant; URLs may expire.","properties":{"url":{"type":"string","description":"Source URL."},"width":{"type":"number","description":"Width in pixels."},"height":{"type":"number","description":"Height in pixels."},"asset_type":{"type":"string","description":"image, video, thumbnail or avatar."},"variant":{"type":"string","description":"Source variant when known."},"expires_at":{"type":"string","description":"Expiry timestamp when known."}}}}}}},"/v1/youtube/channel/shorts":{"get":{"operationId":"youtube_v1_channel_shorts","summary":"YouTube channel shorts","description":"Get shorts uploaded by a public channel. Planned: returns 501 SOURCE_NOT_IMPLEMENTED; no collector or sample response is available and no credits are charged.","tags":["youtube"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"handle","in":"query","required":true,"schema":{"type":"string","pattern":"^@?[\\p{L}\\p{N}_.-]{3,30}$","example":"RickAstleyYT"},"description":"Required youtube handle."},{"name":"cache_max_age","in":"query","required":false,"schema":{"type":"string","enum":["1d","3d","7d","14d","30d"]},"description":"Maximum acceptable cache age. Valid cache hits cost zero credits."},{"name":"fields","in":"query","required":false,"schema":{"type":"string","example":"items"},"description":"Comma-separated fields or dot paths, including inside arrays such as items.id. Response identity and pagination are retained."},{"name":"trim","in":"query","required":false,"schema":{"type":"boolean","default":false},"description":"Remove null and empty values. Meaningful empty YouTube region-restriction lists are retained."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":20,"default":3},"description":"Number of items to return."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"},"description":"Opaque pagination value returned as data.pagination.next_cursor. Keep the identifier, filters and limit unchanged."}],"responses":{"200":{"description":"Normalized resource","headers":{"x-request-id":{"schema":{"type":"string"}},"x-data-mode":{"schema":{"type":"string","enum":["live","sandbox"]}},"x-cache":{"schema":{"type":"string","enum":["HIT","MISS"]}},"x-credits-charged":{"schema":{"type":"integer"}},"x-credits-remaining":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"data":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","additionalProperties":true,"properties":{"id":{"type":["string","null"],"description":"Resource identifier used by this endpoint."},"author":{"type":["string","null"],"description":"Public creator name or handle."},"published_at":{"type":["string","null"],"description":"Source publication date or timestamp; null when absent."},"views":{"type":["number","null"],"description":"Observed views, where exposed by this source."},"likes":{"type":["number","null"],"description":"Observed likes."},"comments":{"type":["number","null"],"description":"Observed comment count, not comment rows."},"media_url":{"type":["string","null"],"description":"Preview image URL; not a guaranteed downloadable video."},"permalink":{"type":["string","null"],"description":"Public content URL."},"duration_seconds":{"type":["number","null"],"description":"Duration in seconds when returned."},"hashtags":{"type":["array","null"],"description":"Hashtags with platform or derived_text provenance.","items":{"type":["object","null"],"description":"Entity observed at source or derived from text.","properties":{"name":{"type":["string","null"],"description":"Hashtag or account name."},"id":{"type":["string","null"],"description":"Platform ID when supplied."},"source":{"type":["string","null"],"description":"platform or derived_text."}}}},"mentions":{"type":["array","null"],"description":"Mentions with platform or derived_text provenance; text is not proof of an account relationship.","items":{"type":["object","null"],"description":"Entity observed at source or derived from text.","properties":{"name":{"type":["string","null"],"description":"Hashtag or account name."},"id":{"type":["string","null"],"description":"Platform ID when supplied."},"source":{"type":["string","null"],"description":"platform or derived_text."}}}},"category_id":{"type":["string","null"],"description":"YouTube category ID."},"language":{"type":["string","null"],"description":"Default metadata language."},"audio_language":{"type":["string","null"],"description":"Default audio language."},"localized":{"type":["object","null"],"description":"Selected localized text.","properties":{"title":{"type":["string","null"],"description":"Title."},"description":{"type":["string","null"],"description":"Description."}}},"localizations":{"type":["object","null"],"description":"Returned language-to-title/description map."},"duration_iso8601":{"type":["string","null"],"description":"Source ISO 8601 duration."},"dimension":{"type":["string","null"],"description":"2d or 3d."},"definition":{"type":["string","null"],"description":"hd or sd."},"licensed_content":{"type":["boolean","null"],"description":"Source licensed-content flag."},"region_restriction":{"type":["object","null"],"description":"An omitted list differs from an empty list. An empty allowed list blocks everywhere; an empty blocked list blocks nowhere.","properties":{"allowed":{"type":["array","null"],"description":"Countries where viewing is permitted.","items":{"type":["string","null"],"description":"Source value."}},"blocked":{"type":["array","null"],"description":"Countries where viewing is blocked.","items":{"type":["string","null"],"description":"Source value."}}}},"content_rating":{"type":["object","null"],"description":"Country/authority rating map retained without enumerating columns."},"projection":{"type":["string","null"],"description":"Projection format."},"privacy_status":{"type":["string","null"],"description":"Source public/unlisted status when returned without account authorization."},"license":{"type":["string","null"],"description":"Source license."},"public_stats_viewable":{"type":["boolean","null"],"description":"Source public-statistics setting."},"made_for_kids":{"type":["boolean","null"],"description":"Current source designation when publicly returned; not the owner-only self-declared setting."},"contains_synthetic_media":{"type":["boolean","null"],"description":"Source altered/synthetic-media disclosure when publicly returned; not an AI prediction."},"paid_partnership":{"type":["boolean","null"],"description":"Explicit source paid-product-placement flag when publicly returned."},"topic_ids":{"type":["array","null"],"description":"Legacy source topic IDs, when returned.","items":{"type":["string","null"],"description":"Source value."}},"topic_categories":{"type":["array","null"],"description":"Topic-category URLs.","items":{"type":["string","null"],"description":"Source value."}},"recording_date":{"type":["string","null"],"description":"Public recording date, when returned."},"embed_html":{"type":["string","null"],"description":"Source embed markup as a string. Never execute returned HTML without sanitizing."},"embed_height":{"type":["number","null"],"description":"Source embed height."},"embed_width":{"type":["number","null"],"description":"Source embed width."},"live_status":{"type":["string","null"],"description":"live, upcoming or none when supplied."},"title":{"type":["string","null"],"description":"Video title."},"description":{"type":["string","null"],"description":"Video description."},"channel_id":{"type":["string","null"],"description":"Owning channel ID."},"tags":{"type":["array","null"],"description":"Keyword tags; distinct from hashtags.","items":{"type":["string","null"],"description":"Keyword tag."}},"thumbnails":{"type":["array","null"],"description":"Returned thumbnail variants and dimensions.","items":{"type":["object","null"],"description":"One source media variant; URLs may expire.","properties":{"url":{"type":["string","null"],"description":"Source URL."},"width":{"type":["number","null"],"description":"Width in pixels."},"height":{"type":["number","null"],"description":"Height in pixels."},"asset_type":{"type":["string","null"],"description":"image, video, thumbnail or avatar."},"variant":{"type":["string","null"],"description":"Source variant when known."},"expires_at":{"type":["string","null"],"description":"Expiry timestamp when known."}}}},"author_avatar_url":{"type":["string","null"],"description":"Channel avatar from the watch page."},"channel_url":{"type":["string","null"],"description":"Channel URL built from the observed channel ID."},"upload_date":{"type":["string","null"],"description":"Source upload date, separate from publication date."},"available_countries":{"type":["array","null"],"description":"Allowed country list when the player exposes it; no inferred blocked countries.","items":{"type":["string","null"],"description":"Country code."}},"unlisted":{"type":["boolean","null"],"description":"Source unlisted flag."},"family_safe":{"type":["boolean","null"],"description":"Source family-safe flag; not the made-for-kids designation."},"counts_rounded":{"type":["object","null"],"description":"Precision of observed counters. Unknown precision is null.","properties":{"views":{"type":["boolean","null"],"description":"Views rounded."},"likes":{"type":["boolean","null"],"description":"Likes rounded."},"comments":{"type":["boolean","null"],"description":"Comments rounded."}}},"caption_tracks":{"type":["array","null"],"description":"Caption-track metadata without caption text.","items":{"type":["object","null"],"description":"One available caption language; URLs are not returned.","properties":{"language":{"type":["string","null"],"description":"Source language code."},"language_name":{"type":["string","null"],"description":"Source language label."},"generated":{"type":["boolean","null"],"description":"True for an automatic caption track."},"translatable":{"type":["boolean","null"],"description":"Source translation capability."}}}},"category":{"type":["string","null"],"description":"Source category name."},"is_live":{"type":["boolean","null"],"description":"Explicit current live state."},"is_live_content":{"type":["boolean","null"],"description":"Explicit live-content classification."},"captions_available":{"type":["boolean","null"],"description":"Caption-track availability when observable."},"embeddable":{"type":["boolean","null"],"description":"Player embed permission when returned."},"live":{"type":["object","null"],"description":"Returned broadcast start/end times and live-now state.","properties":{"actual_start_time":{"type":["string","null"],"description":"Source broadcast start time."},"actual_end_time":{"type":["string","null"],"description":"Source broadcast end time."},"is_live_now":{"type":["boolean","null"],"description":"Explicit live-now state."},"scheduled_start_time":{"type":["string","null"],"description":"Scheduled start time."},"scheduled_end_time":{"type":["string","null"],"description":"Scheduled end time."},"concurrent_viewers":{"type":["number","null"],"description":"Current live viewers, when public."},"active_live_chat_id":{"type":["string","null"],"description":"Active public live-chat ID when supplied."}}}}}}}}}}]}}}},"400":{"$ref":"#/components/responses/InvalidInput"},"401":{"$ref":"#/components/responses/InvalidApiKey"},"402":{"$ref":"#/components/responses/InsufficientCredits"},"403":{"$ref":"#/components/responses/SourceRestricted"},"404":{"$ref":"#/components/responses/ResourceNotFound"},"408":{"$ref":"#/components/responses/SourceTimeout"},"422":{"$ref":"#/components/responses/SourceResponseChanged"},"429":{"$ref":"#/components/responses/TemporaryCapacity"},"501":{"$ref":"#/components/responses/SourceNotImplemented"},"503":{"$ref":"#/components/responses/SourceUnavailable"}},"x-availability":"planned","x-identifier-one-of":["handle"],"x-credits":3,"x-source-access":"public_page","x-preview":true,"x-codeSamples":[{"lang":"curl","source":"curl 'https://api.socialdatakit.com/v1/youtube/channel/shorts?handle=RickAstleyYT' \\\n  -H 'x-api-key: YOUR_API_KEY'"},{"lang":"javascript","source":"const response = await fetch(\"https://api.socialdatakit.com/v1/youtube/channel/shorts?handle=RickAstleyYT\", {\n  headers: { \"x-api-key\": process.env.SOCIALDATAKIT_API_KEY }\n});\nif (!response.ok) throw new Error(await response.text());\nconst result = await response.json();"},{"lang":"python","source":"import os\nimport requests\n\nresponse = requests.get(\n    \"https://api.socialdatakit.com/v1/youtube/channel/shorts?handle=RickAstleyYT\",\n    headers={\"x-api-key\": os.environ[\"SOCIALDATAKIT_API_KEY\"]},\n    timeout=30,\n)\nresponse.raise_for_status()\nresult = response.json()"}],"x-response-fields":{"id":{"type":"string","description":"Resource identifier used by this endpoint."},"author":{"type":"string","description":"Public creator name or handle."},"published_at":{"type":"string","description":"Source publication date or timestamp; null when absent."},"views":{"type":"number","description":"Observed views, where exposed by this source."},"likes":{"type":"number","description":"Observed likes."},"comments":{"type":"number","description":"Observed comment count, not comment rows."},"media_url":{"type":"string","description":"Preview image URL; not a guaranteed downloadable video."},"permalink":{"type":"string","description":"Public content URL."},"duration_seconds":{"type":"number","description":"Duration in seconds when returned."},"hashtags":{"type":"array","description":"Hashtags with platform or derived_text provenance.","items":{"type":"object","description":"Entity observed at source or derived from text.","properties":{"name":{"type":"string","description":"Hashtag or account name."},"id":{"type":"string","description":"Platform ID when supplied."},"source":{"type":"string","description":"platform or derived_text."}}}},"mentions":{"type":"array","description":"Mentions with platform or derived_text provenance; text is not proof of an account relationship.","items":{"type":"object","description":"Entity observed at source or derived from text.","properties":{"name":{"type":"string","description":"Hashtag or account name."},"id":{"type":"string","description":"Platform ID when supplied."},"source":{"type":"string","description":"platform or derived_text."}}}},"category_id":{"type":"string","description":"YouTube category ID."},"language":{"type":"string","description":"Default metadata language."},"audio_language":{"type":"string","description":"Default audio language."},"localized":{"type":"object","description":"Selected localized text.","properties":{"title":{"type":"string","description":"Title."},"description":{"type":"string","description":"Description."}}},"localizations":{"type":"object","description":"Returned language-to-title/description map."},"duration_iso8601":{"type":"string","description":"Source ISO 8601 duration."},"dimension":{"type":"string","description":"2d or 3d."},"definition":{"type":"string","description":"hd or sd."},"licensed_content":{"type":"boolean","description":"Source licensed-content flag."},"region_restriction":{"type":"object","description":"An omitted list differs from an empty list. An empty allowed list blocks everywhere; an empty blocked list blocks nowhere.","properties":{"allowed":{"type":"array","description":"Countries where viewing is permitted.","items":{"type":"string","description":"Source value."}},"blocked":{"type":"array","description":"Countries where viewing is blocked.","items":{"type":"string","description":"Source value."}}}},"content_rating":{"type":"object","description":"Country/authority rating map retained without enumerating columns."},"projection":{"type":"string","description":"Projection format."},"privacy_status":{"type":"string","description":"Source public/unlisted status when returned without account authorization."},"license":{"type":"string","description":"Source license."},"public_stats_viewable":{"type":"boolean","description":"Source public-statistics setting."},"made_for_kids":{"type":"boolean","description":"Current source designation when publicly returned; not the owner-only self-declared setting."},"contains_synthetic_media":{"type":"boolean","description":"Source altered/synthetic-media disclosure when publicly returned; not an AI prediction."},"paid_partnership":{"type":"boolean","description":"Explicit source paid-product-placement flag when publicly returned."},"topic_ids":{"type":"array","description":"Legacy source topic IDs, when returned.","items":{"type":"string","description":"Source value."}},"topic_categories":{"type":"array","description":"Topic-category URLs.","items":{"type":"string","description":"Source value."}},"recording_date":{"type":"string","description":"Public recording date, when returned."},"embed_html":{"type":"string","description":"Source embed markup as a string. Never execute returned HTML without sanitizing."},"embed_height":{"type":"number","description":"Source embed height."},"embed_width":{"type":"number","description":"Source embed width."},"live_status":{"type":"string","description":"live, upcoming or none when supplied."},"title":{"type":"string","description":"Video title."},"description":{"type":"string","description":"Video description."},"channel_id":{"type":"string","description":"Owning channel ID."},"tags":{"type":"array","description":"Keyword tags; distinct from hashtags.","items":{"type":"string","description":"Keyword tag."}},"thumbnails":{"type":"array","description":"Returned thumbnail variants and dimensions.","items":{"type":"object","description":"One source media variant; URLs may expire.","properties":{"url":{"type":"string","description":"Source URL."},"width":{"type":"number","description":"Width in pixels."},"height":{"type":"number","description":"Height in pixels."},"asset_type":{"type":"string","description":"image, video, thumbnail or avatar."},"variant":{"type":"string","description":"Source variant when known."},"expires_at":{"type":"string","description":"Expiry timestamp when known."}}}},"author_avatar_url":{"type":"string","description":"Channel avatar from the watch page."},"channel_url":{"type":"string","description":"Channel URL built from the observed channel ID."},"upload_date":{"type":"string","description":"Source upload date, separate from publication date."},"available_countries":{"type":"array","description":"Allowed country list when the player exposes it; no inferred blocked countries.","items":{"type":"string","description":"Country code."}},"unlisted":{"type":"boolean","description":"Source unlisted flag."},"family_safe":{"type":"boolean","description":"Source family-safe flag; not the made-for-kids designation."},"counts_rounded":{"type":"object","description":"Precision of observed counters. Unknown precision is null.","properties":{"views":{"type":"boolean","description":"Views rounded."},"likes":{"type":"boolean","description":"Likes rounded."},"comments":{"type":"boolean","description":"Comments rounded."}}},"caption_tracks":{"type":"array","description":"Caption-track metadata without caption text.","items":{"type":"object","description":"One available caption language; URLs are not returned.","properties":{"language":{"type":"string","description":"Source language code."},"language_name":{"type":"string","description":"Source language label."},"generated":{"type":"boolean","description":"True for an automatic caption track."},"translatable":{"type":"boolean","description":"Source translation capability."}}}},"category":{"type":"string","description":"Source category name."},"is_live":{"type":"boolean","description":"Explicit current live state."},"is_live_content":{"type":"boolean","description":"Explicit live-content classification."},"captions_available":{"type":"boolean","description":"Caption-track availability when observable."},"embeddable":{"type":"boolean","description":"Player embed permission when returned."},"live":{"type":"object","description":"Returned broadcast start/end times and live-now state.","properties":{"actual_start_time":{"type":"string","description":"Source broadcast start time."},"actual_end_time":{"type":"string","description":"Source broadcast end time."},"is_live_now":{"type":"boolean","description":"Explicit live-now state."},"scheduled_start_time":{"type":"string","description":"Scheduled start time."},"scheduled_end_time":{"type":"string","description":"Scheduled end time."},"concurrent_viewers":{"type":"number","description":"Current live viewers, when public."},"active_live_chat_id":{"type":"string","description":"Active public live-chat ID when supplied."}}}}}},"/v1/youtube/video/transcript":{"get":{"operationId":"youtube_v1_video_transcript","summary":"YouTube video transcript","description":"Get available captions as text and timed sections. Preview: evaluate live availability and source coverage before customer use.","tags":["youtube"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"url","in":"query","required":true,"schema":{"type":"string","pattern":"^https?://[^\\s]{5,400}$","example":"https://www.youtube.com/watch?v=dQw4w9WgXcQ"},"description":"Required youtube url."},{"name":"cache_max_age","in":"query","required":false,"schema":{"type":"string","enum":["1d","3d","7d","14d","30d"]},"description":"Maximum acceptable cache age. Valid cache hits cost zero credits."},{"name":"fields","in":"query","required":false,"schema":{"type":"string","example":"item"},"description":"Comma-separated fields or dot paths, including inside arrays such as items.id. Response identity and pagination are retained."},{"name":"trim","in":"query","required":false,"schema":{"type":"boolean","default":false},"description":"Remove null and empty values. Meaningful empty YouTube region-restriction lists are retained."}],"responses":{"200":{"description":"Normalized resource","headers":{"x-request-id":{"schema":{"type":"string"}},"x-data-mode":{"schema":{"type":"string","enum":["live","sandbox"]}},"x-cache":{"schema":{"type":"string","enum":["HIT","MISS"]}},"x-credits-charged":{"schema":{"type":"integer"}},"x-credits-remaining":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"data":{"type":"object","properties":{"item":{"type":"object","additionalProperties":true,"properties":{"id":{"type":["string","null"],"description":"Resource identifier used by this endpoint."},"author":{"type":["string","null"],"description":"Public creator name or handle."},"published_at":{"type":["string","null"],"description":"Source publication date or timestamp; null when absent."},"views":{"type":["number","null"],"description":"Observed views, where exposed by this source."},"likes":{"type":["number","null"],"description":"Observed likes."},"comments":{"type":["number","null"],"description":"Observed comment count, not comment rows."},"media_url":{"type":["string","null"],"description":"Preview image URL; not a guaranteed downloadable video."},"permalink":{"type":["string","null"],"description":"Public content URL."},"duration_seconds":{"type":["number","null"],"description":"Duration in seconds when returned."},"hashtags":{"type":["array","null"],"description":"Hashtags with platform or derived_text provenance.","items":{"type":["object","null"],"description":"Entity observed at source or derived from text.","properties":{"name":{"type":["string","null"],"description":"Hashtag or account name."},"id":{"type":["string","null"],"description":"Platform ID when supplied."},"source":{"type":["string","null"],"description":"platform or derived_text."}}}},"mentions":{"type":["array","null"],"description":"Mentions with platform or derived_text provenance; text is not proof of an account relationship.","items":{"type":["object","null"],"description":"Entity observed at source or derived from text.","properties":{"name":{"type":["string","null"],"description":"Hashtag or account name."},"id":{"type":["string","null"],"description":"Platform ID when supplied."},"source":{"type":["string","null"],"description":"platform or derived_text."}}}},"category_id":{"type":["string","null"],"description":"YouTube category ID."},"language":{"type":["string","null"],"description":"Default metadata language."},"audio_language":{"type":["string","null"],"description":"Default audio language."},"localized":{"type":["object","null"],"description":"Selected localized text.","properties":{"title":{"type":["string","null"],"description":"Title."},"description":{"type":["string","null"],"description":"Description."}}},"localizations":{"type":["object","null"],"description":"Returned language-to-title/description map."},"duration_iso8601":{"type":["string","null"],"description":"Source ISO 8601 duration."},"dimension":{"type":["string","null"],"description":"2d or 3d."},"definition":{"type":["string","null"],"description":"hd or sd."},"licensed_content":{"type":["boolean","null"],"description":"Source licensed-content flag."},"region_restriction":{"type":["object","null"],"description":"An omitted list differs from an empty list. An empty allowed list blocks everywhere; an empty blocked list blocks nowhere.","properties":{"allowed":{"type":["array","null"],"description":"Countries where viewing is permitted.","items":{"type":["string","null"],"description":"Source value."}},"blocked":{"type":["array","null"],"description":"Countries where viewing is blocked.","items":{"type":["string","null"],"description":"Source value."}}}},"content_rating":{"type":["object","null"],"description":"Country/authority rating map retained without enumerating columns."},"projection":{"type":["string","null"],"description":"Projection format."},"privacy_status":{"type":["string","null"],"description":"Source public/unlisted status when returned without account authorization."},"license":{"type":["string","null"],"description":"Source license."},"public_stats_viewable":{"type":["boolean","null"],"description":"Source public-statistics setting."},"made_for_kids":{"type":["boolean","null"],"description":"Current source designation when publicly returned; not the owner-only self-declared setting."},"contains_synthetic_media":{"type":["boolean","null"],"description":"Source altered/synthetic-media disclosure when publicly returned; not an AI prediction."},"paid_partnership":{"type":["boolean","null"],"description":"Explicit source paid-product-placement flag when publicly returned."},"topic_ids":{"type":["array","null"],"description":"Legacy source topic IDs, when returned.","items":{"type":["string","null"],"description":"Source value."}},"topic_categories":{"type":["array","null"],"description":"Topic-category URLs.","items":{"type":["string","null"],"description":"Source value."}},"recording_date":{"type":["string","null"],"description":"Public recording date, when returned."},"embed_html":{"type":["string","null"],"description":"Source embed markup as a string. Never execute returned HTML without sanitizing."},"embed_height":{"type":["number","null"],"description":"Source embed height."},"embed_width":{"type":["number","null"],"description":"Source embed width."},"live_status":{"type":["string","null"],"description":"live, upcoming or none when supplied."},"title":{"type":["string","null"],"description":"Video title."},"description":{"type":["string","null"],"description":"Video description."},"channel_id":{"type":["string","null"],"description":"Owning channel ID."},"tags":{"type":["array","null"],"description":"Keyword tags; distinct from hashtags.","items":{"type":["string","null"],"description":"Keyword tag."}},"thumbnails":{"type":["array","null"],"description":"Returned thumbnail variants and dimensions.","items":{"type":["object","null"],"description":"One source media variant; URLs may expire.","properties":{"url":{"type":["string","null"],"description":"Source URL."},"width":{"type":["number","null"],"description":"Width in pixels."},"height":{"type":["number","null"],"description":"Height in pixels."},"asset_type":{"type":["string","null"],"description":"image, video, thumbnail or avatar."},"variant":{"type":["string","null"],"description":"Source variant when known."},"expires_at":{"type":["string","null"],"description":"Expiry timestamp when known."}}}},"author_avatar_url":{"type":["string","null"],"description":"Channel avatar from the watch page."},"channel_url":{"type":["string","null"],"description":"Channel URL built from the observed channel ID."},"upload_date":{"type":["string","null"],"description":"Source upload date, separate from publication date."},"available_countries":{"type":["array","null"],"description":"Allowed country list when the player exposes it; no inferred blocked countries.","items":{"type":["string","null"],"description":"Country code."}},"unlisted":{"type":["boolean","null"],"description":"Source unlisted flag."},"family_safe":{"type":["boolean","null"],"description":"Source family-safe flag; not the made-for-kids designation."},"counts_rounded":{"type":["object","null"],"description":"Precision of observed counters. Unknown precision is null.","properties":{"views":{"type":["boolean","null"],"description":"Views rounded."},"likes":{"type":["boolean","null"],"description":"Likes rounded."},"comments":{"type":["boolean","null"],"description":"Comments rounded."}}},"caption_tracks":{"type":["array","null"],"description":"Caption-track metadata without caption text.","items":{"type":["object","null"],"description":"One available caption language; URLs are not returned.","properties":{"language":{"type":["string","null"],"description":"Source language code."},"language_name":{"type":["string","null"],"description":"Source language label."},"generated":{"type":["boolean","null"],"description":"True for an automatic caption track."},"translatable":{"type":["boolean","null"],"description":"Source translation capability."}}}},"category":{"type":["string","null"],"description":"Source category name."},"is_live":{"type":["boolean","null"],"description":"Explicit current live state."},"is_live_content":{"type":["boolean","null"],"description":"Explicit live-content classification."},"captions_available":{"type":["boolean","null"],"description":"Caption-track availability when observable."},"embeddable":{"type":["boolean","null"],"description":"Player embed permission when returned."},"live":{"type":["object","null"],"description":"Returned broadcast start/end times and live-now state.","properties":{"actual_start_time":{"type":["string","null"],"description":"Source broadcast start time."},"actual_end_time":{"type":["string","null"],"description":"Source broadcast end time."},"is_live_now":{"type":["boolean","null"],"description":"Explicit live-now state."},"scheduled_start_time":{"type":["string","null"],"description":"Scheduled start time."},"scheduled_end_time":{"type":["string","null"],"description":"Scheduled end time."},"concurrent_viewers":{"type":["number","null"],"description":"Current live viewers, when public."},"active_live_chat_id":{"type":["string","null"],"description":"Active public live-chat ID when supplied."}}}}}}}}}]}}}},"400":{"$ref":"#/components/responses/InvalidInput"},"401":{"$ref":"#/components/responses/InvalidApiKey"},"402":{"$ref":"#/components/responses/InsufficientCredits"},"403":{"$ref":"#/components/responses/SourceRestricted"},"404":{"$ref":"#/components/responses/ResourceNotFound"},"408":{"$ref":"#/components/responses/SourceTimeout"},"422":{"$ref":"#/components/responses/SourceResponseChanged"},"429":{"$ref":"#/components/responses/TemporaryCapacity"},"501":{"$ref":"#/components/responses/SourceNotImplemented"},"503":{"$ref":"#/components/responses/SourceUnavailable"}},"x-availability":"preview","x-identifier-one-of":["url"],"x-credits":4,"x-source-access":"public_page","x-preview":true,"x-codeSamples":[{"lang":"curl","source":"curl 'https://api.socialdatakit.com/v1/youtube/video/transcript?url=https%3A%2F%2Fwww.youtube.com%2Fwatch%3Fv%3DdQw4w9WgXcQ' \\\n  -H 'x-api-key: YOUR_API_KEY'"},{"lang":"javascript","source":"const response = await fetch(\"https://api.socialdatakit.com/v1/youtube/video/transcript?url=https%3A%2F%2Fwww.youtube.com%2Fwatch%3Fv%3DdQw4w9WgXcQ\", {\n  headers: { \"x-api-key\": process.env.SOCIALDATAKIT_API_KEY }\n});\nif (!response.ok) throw new Error(await response.text());\nconst result = await response.json();"},{"lang":"python","source":"import os\nimport requests\n\nresponse = requests.get(\n    \"https://api.socialdatakit.com/v1/youtube/video/transcript?url=https%3A%2F%2Fwww.youtube.com%2Fwatch%3Fv%3DdQw4w9WgXcQ\",\n    headers={\"x-api-key\": os.environ[\"SOCIALDATAKIT_API_KEY\"]},\n    timeout=30,\n)\nresponse.raise_for_status()\nresult = response.json()"}],"x-response-fields":{"id":{"type":"string","description":"Resource identifier used by this endpoint."},"author":{"type":"string","description":"Public creator name or handle."},"published_at":{"type":"string","description":"Source publication date or timestamp; null when absent."},"views":{"type":"number","description":"Observed views, where exposed by this source."},"likes":{"type":"number","description":"Observed likes."},"comments":{"type":"number","description":"Observed comment count, not comment rows."},"media_url":{"type":"string","description":"Preview image URL; not a guaranteed downloadable video."},"permalink":{"type":"string","description":"Public content URL."},"duration_seconds":{"type":"number","description":"Duration in seconds when returned."},"hashtags":{"type":"array","description":"Hashtags with platform or derived_text provenance.","items":{"type":"object","description":"Entity observed at source or derived from text.","properties":{"name":{"type":"string","description":"Hashtag or account name."},"id":{"type":"string","description":"Platform ID when supplied."},"source":{"type":"string","description":"platform or derived_text."}}}},"mentions":{"type":"array","description":"Mentions with platform or derived_text provenance; text is not proof of an account relationship.","items":{"type":"object","description":"Entity observed at source or derived from text.","properties":{"name":{"type":"string","description":"Hashtag or account name."},"id":{"type":"string","description":"Platform ID when supplied."},"source":{"type":"string","description":"platform or derived_text."}}}},"category_id":{"type":"string","description":"YouTube category ID."},"language":{"type":"string","description":"Default metadata language."},"audio_language":{"type":"string","description":"Default audio language."},"localized":{"type":"object","description":"Selected localized text.","properties":{"title":{"type":"string","description":"Title."},"description":{"type":"string","description":"Description."}}},"localizations":{"type":"object","description":"Returned language-to-title/description map."},"duration_iso8601":{"type":"string","description":"Source ISO 8601 duration."},"dimension":{"type":"string","description":"2d or 3d."},"definition":{"type":"string","description":"hd or sd."},"licensed_content":{"type":"boolean","description":"Source licensed-content flag."},"region_restriction":{"type":"object","description":"An omitted list differs from an empty list. An empty allowed list blocks everywhere; an empty blocked list blocks nowhere.","properties":{"allowed":{"type":"array","description":"Countries where viewing is permitted.","items":{"type":"string","description":"Source value."}},"blocked":{"type":"array","description":"Countries where viewing is blocked.","items":{"type":"string","description":"Source value."}}}},"content_rating":{"type":"object","description":"Country/authority rating map retained without enumerating columns."},"projection":{"type":"string","description":"Projection format."},"privacy_status":{"type":"string","description":"Source public/unlisted status when returned without account authorization."},"license":{"type":"string","description":"Source license."},"public_stats_viewable":{"type":"boolean","description":"Source public-statistics setting."},"made_for_kids":{"type":"boolean","description":"Current source designation when publicly returned; not the owner-only self-declared setting."},"contains_synthetic_media":{"type":"boolean","description":"Source altered/synthetic-media disclosure when publicly returned; not an AI prediction."},"paid_partnership":{"type":"boolean","description":"Explicit source paid-product-placement flag when publicly returned."},"topic_ids":{"type":"array","description":"Legacy source topic IDs, when returned.","items":{"type":"string","description":"Source value."}},"topic_categories":{"type":"array","description":"Topic-category URLs.","items":{"type":"string","description":"Source value."}},"recording_date":{"type":"string","description":"Public recording date, when returned."},"embed_html":{"type":"string","description":"Source embed markup as a string. Never execute returned HTML without sanitizing."},"embed_height":{"type":"number","description":"Source embed height."},"embed_width":{"type":"number","description":"Source embed width."},"live_status":{"type":"string","description":"live, upcoming or none when supplied."},"title":{"type":"string","description":"Video title."},"description":{"type":"string","description":"Video description."},"channel_id":{"type":"string","description":"Owning channel ID."},"tags":{"type":"array","description":"Keyword tags; distinct from hashtags.","items":{"type":"string","description":"Keyword tag."}},"thumbnails":{"type":"array","description":"Returned thumbnail variants and dimensions.","items":{"type":"object","description":"One source media variant; URLs may expire.","properties":{"url":{"type":"string","description":"Source URL."},"width":{"type":"number","description":"Width in pixels."},"height":{"type":"number","description":"Height in pixels."},"asset_type":{"type":"string","description":"image, video, thumbnail or avatar."},"variant":{"type":"string","description":"Source variant when known."},"expires_at":{"type":"string","description":"Expiry timestamp when known."}}}},"author_avatar_url":{"type":"string","description":"Channel avatar from the watch page."},"channel_url":{"type":"string","description":"Channel URL built from the observed channel ID."},"upload_date":{"type":"string","description":"Source upload date, separate from publication date."},"available_countries":{"type":"array","description":"Allowed country list when the player exposes it; no inferred blocked countries.","items":{"type":"string","description":"Country code."}},"unlisted":{"type":"boolean","description":"Source unlisted flag."},"family_safe":{"type":"boolean","description":"Source family-safe flag; not the made-for-kids designation."},"counts_rounded":{"type":"object","description":"Precision of observed counters. Unknown precision is null.","properties":{"views":{"type":"boolean","description":"Views rounded."},"likes":{"type":"boolean","description":"Likes rounded."},"comments":{"type":"boolean","description":"Comments rounded."}}},"caption_tracks":{"type":"array","description":"Caption-track metadata without caption text.","items":{"type":"object","description":"One available caption language; URLs are not returned.","properties":{"language":{"type":"string","description":"Source language code."},"language_name":{"type":"string","description":"Source language label."},"generated":{"type":"boolean","description":"True for an automatic caption track."},"translatable":{"type":"boolean","description":"Source translation capability."}}}},"category":{"type":"string","description":"Source category name."},"is_live":{"type":"boolean","description":"Explicit current live state."},"is_live_content":{"type":"boolean","description":"Explicit live-content classification."},"captions_available":{"type":"boolean","description":"Caption-track availability when observable."},"embeddable":{"type":"boolean","description":"Player embed permission when returned."},"live":{"type":"object","description":"Returned broadcast start/end times and live-now state.","properties":{"actual_start_time":{"type":"string","description":"Source broadcast start time."},"actual_end_time":{"type":"string","description":"Source broadcast end time."},"is_live_now":{"type":"boolean","description":"Explicit live-now state."},"scheduled_start_time":{"type":"string","description":"Scheduled start time."},"scheduled_end_time":{"type":"string","description":"Scheduled end time."},"concurrent_viewers":{"type":"number","description":"Current live viewers, when public."},"active_live_chat_id":{"type":"string","description":"Active public live-chat ID when supplied."}}}}}},"/v1/youtube/video/comments":{"get":{"operationId":"youtube_v1_video_comments","summary":"YouTube video comments","description":"Get public top-level comments on a video. Preview: evaluate live availability and source coverage before customer use.","tags":["youtube"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"url","in":"query","required":true,"schema":{"type":"string","pattern":"^https?://[^\\s]{5,400}$","example":"https://www.youtube.com/watch?v=dQw4w9WgXcQ"},"description":"Required youtube url."},{"name":"cache_max_age","in":"query","required":false,"schema":{"type":"string","enum":["1d","3d","7d","14d","30d"]},"description":"Maximum acceptable cache age. Valid cache hits cost zero credits."},{"name":"fields","in":"query","required":false,"schema":{"type":"string","example":"items"},"description":"Comma-separated fields or dot paths, including inside arrays such as items.id. Response identity and pagination are retained."},{"name":"trim","in":"query","required":false,"schema":{"type":"boolean","default":false},"description":"Remove null and empty values. Meaningful empty YouTube region-restriction lists are retained."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":20,"default":3},"description":"Number of items to return."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"},"description":"Opaque pagination value returned as data.pagination.next_cursor. Keep the identifier, filters and limit unchanged."}],"responses":{"200":{"description":"Normalized resource","headers":{"x-request-id":{"schema":{"type":"string"}},"x-data-mode":{"schema":{"type":"string","enum":["live","sandbox"]}},"x-cache":{"schema":{"type":"string","enum":["HIT","MISS"]}},"x-credits-charged":{"schema":{"type":"integer"}},"x-credits-remaining":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"data":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","additionalProperties":true,"properties":{"id":{"type":["string","null"],"description":"Platform comment ID, retained as a string."},"content_id":{"type":["string","null"],"description":"Parent video/post ID when known."},"parent_comment_id":{"type":["string","null"],"description":"Top-level comment ID for a reply; null for a top-level comment or unknown parent."},"text":{"type":["string","null"],"description":"Public comment text. YouTube requests plainText formatting; no owner-only textOriginal."},"likes":{"type":["number","null"],"description":"Observed comment likes."},"reply_count":{"type":["number","null"],"description":"Observed total reply count; not the number of replies returned."},"author_id":{"type":["string","null"],"description":"Public author account ID."},"author_username":{"type":["string","null"],"description":"Public author handle."},"author_display_name":{"type":["string","null"],"description":"Public display name."},"author_avatar_url":{"type":["string","null"],"description":"Public avatar URL."},"author_profile_url":{"type":["string","null"],"description":"Public author profile URL."},"published_at":{"type":["string","null"],"description":"Comment publication timestamp."},"updated_at":{"type":["string","null"],"description":"Source edit timestamp when available."},"image_url":{"type":["string","null"],"description":"Optional image/GIF attachment URL; null when absent. Signed URL expires six hours after retrieval."},"image_url_retrieved_at":{"type":["string","null"],"description":"UTC timestamp when the attachment URL was retrieved; null without an attachment."},"image_url_expires_at":{"type":["string","null"],"description":"UTC expiry of the signed attachment URL. Refresh the comment after expiry; historical archives do not refresh links."}}}}}}}}]}}}},"400":{"$ref":"#/components/responses/InvalidInput"},"401":{"$ref":"#/components/responses/InvalidApiKey"},"402":{"$ref":"#/components/responses/InsufficientCredits"},"403":{"$ref":"#/components/responses/SourceRestricted"},"404":{"$ref":"#/components/responses/ResourceNotFound"},"408":{"$ref":"#/components/responses/SourceTimeout"},"422":{"$ref":"#/components/responses/SourceResponseChanged"},"429":{"$ref":"#/components/responses/TemporaryCapacity"},"501":{"$ref":"#/components/responses/SourceNotImplemented"},"503":{"$ref":"#/components/responses/SourceUnavailable"}},"x-availability":"preview","x-identifier-one-of":["url"],"x-credits":2,"x-source-access":"public_page","x-preview":true,"x-codeSamples":[{"lang":"curl","source":"curl 'https://api.socialdatakit.com/v1/youtube/video/comments?url=https%3A%2F%2Fwww.youtube.com%2Fwatch%3Fv%3DdQw4w9WgXcQ' \\\n  -H 'x-api-key: YOUR_API_KEY'"},{"lang":"javascript","source":"const response = await fetch(\"https://api.socialdatakit.com/v1/youtube/video/comments?url=https%3A%2F%2Fwww.youtube.com%2Fwatch%3Fv%3DdQw4w9WgXcQ\", {\n  headers: { \"x-api-key\": process.env.SOCIALDATAKIT_API_KEY }\n});\nif (!response.ok) throw new Error(await response.text());\nconst result = await response.json();"},{"lang":"python","source":"import os\nimport requests\n\nresponse = requests.get(\n    \"https://api.socialdatakit.com/v1/youtube/video/comments?url=https%3A%2F%2Fwww.youtube.com%2Fwatch%3Fv%3DdQw4w9WgXcQ\",\n    headers={\"x-api-key\": os.environ[\"SOCIALDATAKIT_API_KEY\"]},\n    timeout=30,\n)\nresponse.raise_for_status()\nresult = response.json()"}],"x-response-fields":{"id":{"type":"string","description":"Platform comment ID, retained as a string."},"content_id":{"type":"string","description":"Parent video/post ID when known."},"parent_comment_id":{"type":"string","description":"Top-level comment ID for a reply; null for a top-level comment or unknown parent."},"text":{"type":"string","description":"Public comment text. YouTube requests plainText formatting; no owner-only textOriginal."},"likes":{"type":"number","description":"Observed comment likes."},"reply_count":{"type":"number","description":"Observed total reply count; not the number of replies returned."},"author_id":{"type":"string","description":"Public author account ID."},"author_username":{"type":"string","description":"Public author handle."},"author_display_name":{"type":"string","description":"Public display name."},"author_avatar_url":{"type":"string","description":"Public avatar URL."},"author_profile_url":{"type":"string","description":"Public author profile URL."},"published_at":{"type":"string","description":"Comment publication timestamp."},"updated_at":{"type":"string","description":"Source edit timestamp when available."},"image_url":{"type":"string","description":"Optional image/GIF attachment URL; null when absent. Signed URL expires six hours after retrieval."},"image_url_retrieved_at":{"type":"string","description":"UTC timestamp when the attachment URL was retrieved; null without an attachment."},"image_url_expires_at":{"type":"string","description":"UTC expiry of the signed attachment URL. Refresh the comment after expiry; historical archives do not refresh links."}}}},"/v1/youtube/community-post":{"get":{"operationId":"youtube_v1_community-post","summary":"YouTube community post","description":"Get a public community post. Planned: returns 501 SOURCE_NOT_IMPLEMENTED; no collector or sample response is available and no credits are charged.","tags":["youtube"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"url","in":"query","required":true,"schema":{"type":"string","pattern":"^https?://[^\\s]{5,400}$","example":"https://www.youtube.com/post/UgkxDemo"},"description":"Required youtube url."},{"name":"cache_max_age","in":"query","required":false,"schema":{"type":"string","enum":["1d","3d","7d","14d","30d"]},"description":"Maximum acceptable cache age. Valid cache hits cost zero credits."},{"name":"fields","in":"query","required":false,"schema":{"type":"string","example":"item"},"description":"Comma-separated fields or dot paths, including inside arrays such as items.id. Response identity and pagination are retained."},{"name":"trim","in":"query","required":false,"schema":{"type":"boolean","default":false},"description":"Remove null and empty values. Meaningful empty YouTube region-restriction lists are retained."}],"responses":{"200":{"description":"Normalized resource","headers":{"x-request-id":{"schema":{"type":"string"}},"x-data-mode":{"schema":{"type":"string","enum":["live","sandbox"]}},"x-cache":{"schema":{"type":"string","enum":["HIT","MISS"]}},"x-credits-charged":{"schema":{"type":"integer"}},"x-credits-remaining":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"data":{"type":"object","properties":{"item":{"type":"object","additionalProperties":true,"properties":{"id":{"type":["string","null"],"description":"Resource identifier used by this endpoint."},"author":{"type":["string","null"],"description":"Public creator name or handle."},"published_at":{"type":["string","null"],"description":"Source publication date or timestamp; null when absent."},"views":{"type":["number","null"],"description":"Observed views, where exposed by this source."},"likes":{"type":["number","null"],"description":"Observed likes."},"comments":{"type":["number","null"],"description":"Observed comment count, not comment rows."},"media_url":{"type":["string","null"],"description":"Preview image URL; not a guaranteed downloadable video."},"permalink":{"type":["string","null"],"description":"Public content URL."},"duration_seconds":{"type":["number","null"],"description":"Duration in seconds when returned."},"hashtags":{"type":["array","null"],"description":"Hashtags with platform or derived_text provenance.","items":{"type":["object","null"],"description":"Entity observed at source or derived from text.","properties":{"name":{"type":["string","null"],"description":"Hashtag or account name."},"id":{"type":["string","null"],"description":"Platform ID when supplied."},"source":{"type":["string","null"],"description":"platform or derived_text."}}}},"mentions":{"type":["array","null"],"description":"Mentions with platform or derived_text provenance; text is not proof of an account relationship.","items":{"type":["object","null"],"description":"Entity observed at source or derived from text.","properties":{"name":{"type":["string","null"],"description":"Hashtag or account name."},"id":{"type":["string","null"],"description":"Platform ID when supplied."},"source":{"type":["string","null"],"description":"platform or derived_text."}}}},"category_id":{"type":["string","null"],"description":"YouTube category ID."},"language":{"type":["string","null"],"description":"Default metadata language."},"audio_language":{"type":["string","null"],"description":"Default audio language."},"localized":{"type":["object","null"],"description":"Selected localized text.","properties":{"title":{"type":["string","null"],"description":"Title."},"description":{"type":["string","null"],"description":"Description."}}},"localizations":{"type":["object","null"],"description":"Returned language-to-title/description map."},"duration_iso8601":{"type":["string","null"],"description":"Source ISO 8601 duration."},"dimension":{"type":["string","null"],"description":"2d or 3d."},"definition":{"type":["string","null"],"description":"hd or sd."},"licensed_content":{"type":["boolean","null"],"description":"Source licensed-content flag."},"region_restriction":{"type":["object","null"],"description":"An omitted list differs from an empty list. An empty allowed list blocks everywhere; an empty blocked list blocks nowhere.","properties":{"allowed":{"type":["array","null"],"description":"Countries where viewing is permitted.","items":{"type":["string","null"],"description":"Source value."}},"blocked":{"type":["array","null"],"description":"Countries where viewing is blocked.","items":{"type":["string","null"],"description":"Source value."}}}},"content_rating":{"type":["object","null"],"description":"Country/authority rating map retained without enumerating columns."},"projection":{"type":["string","null"],"description":"Projection format."},"privacy_status":{"type":["string","null"],"description":"Source public/unlisted status when returned without account authorization."},"license":{"type":["string","null"],"description":"Source license."},"public_stats_viewable":{"type":["boolean","null"],"description":"Source public-statistics setting."},"made_for_kids":{"type":["boolean","null"],"description":"Current source designation when publicly returned; not the owner-only self-declared setting."},"contains_synthetic_media":{"type":["boolean","null"],"description":"Source altered/synthetic-media disclosure when publicly returned; not an AI prediction."},"paid_partnership":{"type":["boolean","null"],"description":"Explicit source paid-product-placement flag when publicly returned."},"topic_ids":{"type":["array","null"],"description":"Legacy source topic IDs, when returned.","items":{"type":["string","null"],"description":"Source value."}},"topic_categories":{"type":["array","null"],"description":"Topic-category URLs.","items":{"type":["string","null"],"description":"Source value."}},"recording_date":{"type":["string","null"],"description":"Public recording date, when returned."},"embed_html":{"type":["string","null"],"description":"Source embed markup as a string. Never execute returned HTML without sanitizing."},"embed_height":{"type":["number","null"],"description":"Source embed height."},"embed_width":{"type":["number","null"],"description":"Source embed width."},"live_status":{"type":["string","null"],"description":"live, upcoming or none when supplied."},"title":{"type":["string","null"],"description":"Video title."},"description":{"type":["string","null"],"description":"Video description."},"channel_id":{"type":["string","null"],"description":"Owning channel ID."},"tags":{"type":["array","null"],"description":"Keyword tags; distinct from hashtags.","items":{"type":["string","null"],"description":"Keyword tag."}},"thumbnails":{"type":["array","null"],"description":"Returned thumbnail variants and dimensions.","items":{"type":["object","null"],"description":"One source media variant; URLs may expire.","properties":{"url":{"type":["string","null"],"description":"Source URL."},"width":{"type":["number","null"],"description":"Width in pixels."},"height":{"type":["number","null"],"description":"Height in pixels."},"asset_type":{"type":["string","null"],"description":"image, video, thumbnail or avatar."},"variant":{"type":["string","null"],"description":"Source variant when known."},"expires_at":{"type":["string","null"],"description":"Expiry timestamp when known."}}}},"author_avatar_url":{"type":["string","null"],"description":"Channel avatar from the watch page."},"channel_url":{"type":["string","null"],"description":"Channel URL built from the observed channel ID."},"upload_date":{"type":["string","null"],"description":"Source upload date, separate from publication date."},"available_countries":{"type":["array","null"],"description":"Allowed country list when the player exposes it; no inferred blocked countries.","items":{"type":["string","null"],"description":"Country code."}},"unlisted":{"type":["boolean","null"],"description":"Source unlisted flag."},"family_safe":{"type":["boolean","null"],"description":"Source family-safe flag; not the made-for-kids designation."},"counts_rounded":{"type":["object","null"],"description":"Precision of observed counters. Unknown precision is null.","properties":{"views":{"type":["boolean","null"],"description":"Views rounded."},"likes":{"type":["boolean","null"],"description":"Likes rounded."},"comments":{"type":["boolean","null"],"description":"Comments rounded."}}},"caption_tracks":{"type":["array","null"],"description":"Caption-track metadata without caption text.","items":{"type":["object","null"],"description":"One available caption language; URLs are not returned.","properties":{"language":{"type":["string","null"],"description":"Source language code."},"language_name":{"type":["string","null"],"description":"Source language label."},"generated":{"type":["boolean","null"],"description":"True for an automatic caption track."},"translatable":{"type":["boolean","null"],"description":"Source translation capability."}}}},"category":{"type":["string","null"],"description":"Source category name."},"is_live":{"type":["boolean","null"],"description":"Explicit current live state."},"is_live_content":{"type":["boolean","null"],"description":"Explicit live-content classification."},"captions_available":{"type":["boolean","null"],"description":"Caption-track availability when observable."},"embeddable":{"type":["boolean","null"],"description":"Player embed permission when returned."},"live":{"type":["object","null"],"description":"Returned broadcast start/end times and live-now state.","properties":{"actual_start_time":{"type":["string","null"],"description":"Source broadcast start time."},"actual_end_time":{"type":["string","null"],"description":"Source broadcast end time."},"is_live_now":{"type":["boolean","null"],"description":"Explicit live-now state."},"scheduled_start_time":{"type":["string","null"],"description":"Scheduled start time."},"scheduled_end_time":{"type":["string","null"],"description":"Scheduled end time."},"concurrent_viewers":{"type":["number","null"],"description":"Current live viewers, when public."},"active_live_chat_id":{"type":["string","null"],"description":"Active public live-chat ID when supplied."}}}}}}}}}]}}}},"400":{"$ref":"#/components/responses/InvalidInput"},"401":{"$ref":"#/components/responses/InvalidApiKey"},"402":{"$ref":"#/components/responses/InsufficientCredits"},"403":{"$ref":"#/components/responses/SourceRestricted"},"404":{"$ref":"#/components/responses/ResourceNotFound"},"408":{"$ref":"#/components/responses/SourceTimeout"},"422":{"$ref":"#/components/responses/SourceResponseChanged"},"429":{"$ref":"#/components/responses/TemporaryCapacity"},"501":{"$ref":"#/components/responses/SourceNotImplemented"},"503":{"$ref":"#/components/responses/SourceUnavailable"}},"x-availability":"planned","x-identifier-one-of":["url"],"x-credits":1,"x-source-access":"public_page","x-preview":true,"x-codeSamples":[{"lang":"curl","source":"curl 'https://api.socialdatakit.com/v1/youtube/community-post?url=https%3A%2F%2Fwww.youtube.com%2Fpost%2FUgkxDemo' \\\n  -H 'x-api-key: YOUR_API_KEY'"},{"lang":"javascript","source":"const response = await fetch(\"https://api.socialdatakit.com/v1/youtube/community-post?url=https%3A%2F%2Fwww.youtube.com%2Fpost%2FUgkxDemo\", {\n  headers: { \"x-api-key\": process.env.SOCIALDATAKIT_API_KEY }\n});\nif (!response.ok) throw new Error(await response.text());\nconst result = await response.json();"},{"lang":"python","source":"import os\nimport requests\n\nresponse = requests.get(\n    \"https://api.socialdatakit.com/v1/youtube/community-post?url=https%3A%2F%2Fwww.youtube.com%2Fpost%2FUgkxDemo\",\n    headers={\"x-api-key\": os.environ[\"SOCIALDATAKIT_API_KEY\"]},\n    timeout=30,\n)\nresponse.raise_for_status()\nresult = response.json()"}],"x-response-fields":{"id":{"type":"string","description":"Resource identifier used by this endpoint."},"author":{"type":"string","description":"Public creator name or handle."},"published_at":{"type":"string","description":"Source publication date or timestamp; null when absent."},"views":{"type":"number","description":"Observed views, where exposed by this source."},"likes":{"type":"number","description":"Observed likes."},"comments":{"type":"number","description":"Observed comment count, not comment rows."},"media_url":{"type":"string","description":"Preview image URL; not a guaranteed downloadable video."},"permalink":{"type":"string","description":"Public content URL."},"duration_seconds":{"type":"number","description":"Duration in seconds when returned."},"hashtags":{"type":"array","description":"Hashtags with platform or derived_text provenance.","items":{"type":"object","description":"Entity observed at source or derived from text.","properties":{"name":{"type":"string","description":"Hashtag or account name."},"id":{"type":"string","description":"Platform ID when supplied."},"source":{"type":"string","description":"platform or derived_text."}}}},"mentions":{"type":"array","description":"Mentions with platform or derived_text provenance; text is not proof of an account relationship.","items":{"type":"object","description":"Entity observed at source or derived from text.","properties":{"name":{"type":"string","description":"Hashtag or account name."},"id":{"type":"string","description":"Platform ID when supplied."},"source":{"type":"string","description":"platform or derived_text."}}}},"category_id":{"type":"string","description":"YouTube category ID."},"language":{"type":"string","description":"Default metadata language."},"audio_language":{"type":"string","description":"Default audio language."},"localized":{"type":"object","description":"Selected localized text.","properties":{"title":{"type":"string","description":"Title."},"description":{"type":"string","description":"Description."}}},"localizations":{"type":"object","description":"Returned language-to-title/description map."},"duration_iso8601":{"type":"string","description":"Source ISO 8601 duration."},"dimension":{"type":"string","description":"2d or 3d."},"definition":{"type":"string","description":"hd or sd."},"licensed_content":{"type":"boolean","description":"Source licensed-content flag."},"region_restriction":{"type":"object","description":"An omitted list differs from an empty list. An empty allowed list blocks everywhere; an empty blocked list blocks nowhere.","properties":{"allowed":{"type":"array","description":"Countries where viewing is permitted.","items":{"type":"string","description":"Source value."}},"blocked":{"type":"array","description":"Countries where viewing is blocked.","items":{"type":"string","description":"Source value."}}}},"content_rating":{"type":"object","description":"Country/authority rating map retained without enumerating columns."},"projection":{"type":"string","description":"Projection format."},"privacy_status":{"type":"string","description":"Source public/unlisted status when returned without account authorization."},"license":{"type":"string","description":"Source license."},"public_stats_viewable":{"type":"boolean","description":"Source public-statistics setting."},"made_for_kids":{"type":"boolean","description":"Current source designation when publicly returned; not the owner-only self-declared setting."},"contains_synthetic_media":{"type":"boolean","description":"Source altered/synthetic-media disclosure when publicly returned; not an AI prediction."},"paid_partnership":{"type":"boolean","description":"Explicit source paid-product-placement flag when publicly returned."},"topic_ids":{"type":"array","description":"Legacy source topic IDs, when returned.","items":{"type":"string","description":"Source value."}},"topic_categories":{"type":"array","description":"Topic-category URLs.","items":{"type":"string","description":"Source value."}},"recording_date":{"type":"string","description":"Public recording date, when returned."},"embed_html":{"type":"string","description":"Source embed markup as a string. Never execute returned HTML without sanitizing."},"embed_height":{"type":"number","description":"Source embed height."},"embed_width":{"type":"number","description":"Source embed width."},"live_status":{"type":"string","description":"live, upcoming or none when supplied."},"title":{"type":"string","description":"Video title."},"description":{"type":"string","description":"Video description."},"channel_id":{"type":"string","description":"Owning channel ID."},"tags":{"type":"array","description":"Keyword tags; distinct from hashtags.","items":{"type":"string","description":"Keyword tag."}},"thumbnails":{"type":"array","description":"Returned thumbnail variants and dimensions.","items":{"type":"object","description":"One source media variant; URLs may expire.","properties":{"url":{"type":"string","description":"Source URL."},"width":{"type":"number","description":"Width in pixels."},"height":{"type":"number","description":"Height in pixels."},"asset_type":{"type":"string","description":"image, video, thumbnail or avatar."},"variant":{"type":"string","description":"Source variant when known."},"expires_at":{"type":"string","description":"Expiry timestamp when known."}}}},"author_avatar_url":{"type":"string","description":"Channel avatar from the watch page."},"channel_url":{"type":"string","description":"Channel URL built from the observed channel ID."},"upload_date":{"type":"string","description":"Source upload date, separate from publication date."},"available_countries":{"type":"array","description":"Allowed country list when the player exposes it; no inferred blocked countries.","items":{"type":"string","description":"Country code."}},"unlisted":{"type":"boolean","description":"Source unlisted flag."},"family_safe":{"type":"boolean","description":"Source family-safe flag; not the made-for-kids designation."},"counts_rounded":{"type":"object","description":"Precision of observed counters. Unknown precision is null.","properties":{"views":{"type":"boolean","description":"Views rounded."},"likes":{"type":"boolean","description":"Likes rounded."},"comments":{"type":"boolean","description":"Comments rounded."}}},"caption_tracks":{"type":"array","description":"Caption-track metadata without caption text.","items":{"type":"object","description":"One available caption language; URLs are not returned.","properties":{"language":{"type":"string","description":"Source language code."},"language_name":{"type":"string","description":"Source language label."},"generated":{"type":"boolean","description":"True for an automatic caption track."},"translatable":{"type":"boolean","description":"Source translation capability."}}}},"category":{"type":"string","description":"Source category name."},"is_live":{"type":"boolean","description":"Explicit current live state."},"is_live_content":{"type":"boolean","description":"Explicit live-content classification."},"captions_available":{"type":"boolean","description":"Caption-track availability when observable."},"embeddable":{"type":"boolean","description":"Player embed permission when returned."},"live":{"type":"object","description":"Returned broadcast start/end times and live-now state.","properties":{"actual_start_time":{"type":"string","description":"Source broadcast start time."},"actual_end_time":{"type":"string","description":"Source broadcast end time."},"is_live_now":{"type":"boolean","description":"Explicit live-now state."},"scheduled_start_time":{"type":"string","description":"Scheduled start time."},"scheduled_end_time":{"type":"string","description":"Scheduled end time."},"concurrent_viewers":{"type":"number","description":"Current live viewers, when public."},"active_live_chat_id":{"type":"string","description":"Active public live-chat ID when supplied."}}}}}},"/v1/youtube/search/hashtag":{"get":{"operationId":"youtube_v1_search_hashtag","summary":"YouTube hashtag search","description":"Get public videos for a hashtag. Planned: returns 501 SOURCE_NOT_IMPLEMENTED; no collector or sample response is available and no credits are charged.","tags":["youtube"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"hashtag","in":"query","required":true,"schema":{"type":"string","pattern":"^[\\p{L}\\p{N}_]{1,100}$","example":"shorts"},"description":"Required youtube hashtag."},{"name":"cache_max_age","in":"query","required":false,"schema":{"type":"string","enum":["1d","3d","7d","14d","30d"]},"description":"Maximum acceptable cache age. Valid cache hits cost zero credits."},{"name":"fields","in":"query","required":false,"schema":{"type":"string","example":"items"},"description":"Comma-separated fields or dot paths, including inside arrays such as items.id. Response identity and pagination are retained."},{"name":"trim","in":"query","required":false,"schema":{"type":"boolean","default":false},"description":"Remove null and empty values. Meaningful empty YouTube region-restriction lists are retained."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":20,"default":3},"description":"Number of items to return."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"},"description":"Opaque pagination value returned as data.pagination.next_cursor. Keep the identifier, filters and limit unchanged."}],"responses":{"200":{"description":"Normalized resource","headers":{"x-request-id":{"schema":{"type":"string"}},"x-data-mode":{"schema":{"type":"string","enum":["live","sandbox"]}},"x-cache":{"schema":{"type":"string","enum":["HIT","MISS"]}},"x-credits-charged":{"schema":{"type":"integer"}},"x-credits-remaining":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"data":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","additionalProperties":true,"properties":{"id":{"type":["string","null"],"description":"Matched platform object ID."},"result_type":{"type":["string","null"],"description":"video, channel or playlist."},"title":{"type":["string","null"],"description":"Source title."},"description":{"type":["string","null"],"description":"Search snippet."},"channel_id":{"type":["string","null"],"description":"Owning channel ID."},"author":{"type":["string","null"],"description":"Channel name."},"published_at":{"type":["string","null"],"description":"Source publish time."},"thumbnails":{"type":["array","null"],"description":"All returned thumbnail variants; dimensions are source values.","items":{"type":["object","null"],"description":"Thumbnail.","properties":{"url":{"type":["string","null"],"description":"Source URL."},"variant":{"type":["string","null"],"description":"Source variant."},"width":{"type":["number","null"],"description":"Width."},"height":{"type":["number","null"],"description":"Height."},"asset_type":{"type":["string","null"],"description":"thumbnail."},"expires_at":{"type":["string","null"],"description":"Expiry when known."}}}},"live_status":{"type":["string","null"],"description":"Broadcast status."},"permalink":{"type":["string","null"],"description":"Public result URL."},"query":{"type":["string","null"],"description":"Query submitted."},"position":{"type":["number","null"],"description":"One-based position in this API result traversal, not personalized website ranking."},"region_code":{"type":["string","null"],"description":"Requested region, if specified."},"language":{"type":["string","null"],"description":"Requested relevance language, if specified."},"order":{"type":["string","null"],"description":"Requested sorting order."}}}}}}}}]}}}},"400":{"$ref":"#/components/responses/InvalidInput"},"401":{"$ref":"#/components/responses/InvalidApiKey"},"402":{"$ref":"#/components/responses/InsufficientCredits"},"403":{"$ref":"#/components/responses/SourceRestricted"},"404":{"$ref":"#/components/responses/ResourceNotFound"},"408":{"$ref":"#/components/responses/SourceTimeout"},"422":{"$ref":"#/components/responses/SourceResponseChanged"},"429":{"$ref":"#/components/responses/TemporaryCapacity"},"501":{"$ref":"#/components/responses/SourceNotImplemented"},"503":{"$ref":"#/components/responses/SourceUnavailable"}},"x-availability":"planned","x-identifier-one-of":["hashtag"],"x-credits":3,"x-source-access":"public_page","x-preview":true,"x-codeSamples":[{"lang":"curl","source":"curl 'https://api.socialdatakit.com/v1/youtube/search/hashtag?hashtag=shorts' \\\n  -H 'x-api-key: YOUR_API_KEY'"},{"lang":"javascript","source":"const response = await fetch(\"https://api.socialdatakit.com/v1/youtube/search/hashtag?hashtag=shorts\", {\n  headers: { \"x-api-key\": process.env.SOCIALDATAKIT_API_KEY }\n});\nif (!response.ok) throw new Error(await response.text());\nconst result = await response.json();"},{"lang":"python","source":"import os\nimport requests\n\nresponse = requests.get(\n    \"https://api.socialdatakit.com/v1/youtube/search/hashtag?hashtag=shorts\",\n    headers={\"x-api-key\": os.environ[\"SOCIALDATAKIT_API_KEY\"]},\n    timeout=30,\n)\nresponse.raise_for_status()\nresult = response.json()"}],"x-response-fields":{"id":{"type":"string","description":"Matched platform object ID."},"result_type":{"type":"string","description":"video, channel or playlist."},"title":{"type":"string","description":"Source title."},"description":{"type":"string","description":"Search snippet."},"channel_id":{"type":"string","description":"Owning channel ID."},"author":{"type":"string","description":"Channel name."},"published_at":{"type":"string","description":"Source publish time."},"thumbnails":{"type":"array","description":"All returned thumbnail variants; dimensions are source values.","items":{"type":"object","description":"Thumbnail.","properties":{"url":{"type":"string","description":"Source URL."},"variant":{"type":"string","description":"Source variant."},"width":{"type":"number","description":"Width."},"height":{"type":"number","description":"Height."},"asset_type":{"type":"string","description":"thumbnail."},"expires_at":{"type":"string","description":"Expiry when known."}}}},"live_status":{"type":"string","description":"Broadcast status."},"permalink":{"type":"string","description":"Public result URL."},"query":{"type":"string","description":"Query submitted."},"position":{"type":"number","description":"One-based position in this API result traversal, not personalized website ranking."},"region_code":{"type":"string","description":"Requested region, if specified."},"language":{"type":"string","description":"Requested relevance language, if specified."},"order":{"type":"string","description":"Requested sorting order."}}}},"/v1/youtube/shorts/trending":{"get":{"operationId":"youtube_v1_shorts_trending","summary":"YouTube trending shorts","description":"Get trending public shorts. Planned: returns 501 SOURCE_NOT_IMPLEMENTED; no collector or sample response is available and no credits are charged.","tags":["youtube"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"query","in":"query","required":true,"schema":{"type":"string","pattern":"^.{1,180}$","example":"GB"},"description":"Required youtube query."},{"name":"cache_max_age","in":"query","required":false,"schema":{"type":"string","enum":["1d","3d","7d","14d","30d"]},"description":"Maximum acceptable cache age. Valid cache hits cost zero credits."},{"name":"fields","in":"query","required":false,"schema":{"type":"string","example":"items"},"description":"Comma-separated fields or dot paths, including inside arrays such as items.id. Response identity and pagination are retained."},{"name":"trim","in":"query","required":false,"schema":{"type":"boolean","default":false},"description":"Remove null and empty values. Meaningful empty YouTube region-restriction lists are retained."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":20,"default":3},"description":"Number of items to return."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"},"description":"Opaque pagination value returned as data.pagination.next_cursor. Keep the identifier, filters and limit unchanged."}],"responses":{"200":{"description":"Normalized resource","headers":{"x-request-id":{"schema":{"type":"string"}},"x-data-mode":{"schema":{"type":"string","enum":["live","sandbox"]}},"x-cache":{"schema":{"type":"string","enum":["HIT","MISS"]}},"x-credits-charged":{"schema":{"type":"integer"}},"x-credits-remaining":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"data":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","additionalProperties":true,"properties":{"id":{"type":["string","null"],"description":"Resource identifier used by this endpoint."},"author":{"type":["string","null"],"description":"Public creator name or handle."},"published_at":{"type":["string","null"],"description":"Source publication date or timestamp; null when absent."},"views":{"type":["number","null"],"description":"Observed views, where exposed by this source."},"likes":{"type":["number","null"],"description":"Observed likes."},"comments":{"type":["number","null"],"description":"Observed comment count, not comment rows."},"media_url":{"type":["string","null"],"description":"Preview image URL; not a guaranteed downloadable video."},"permalink":{"type":["string","null"],"description":"Public content URL."},"duration_seconds":{"type":["number","null"],"description":"Duration in seconds when returned."},"hashtags":{"type":["array","null"],"description":"Hashtags with platform or derived_text provenance.","items":{"type":["object","null"],"description":"Entity observed at source or derived from text.","properties":{"name":{"type":["string","null"],"description":"Hashtag or account name."},"id":{"type":["string","null"],"description":"Platform ID when supplied."},"source":{"type":["string","null"],"description":"platform or derived_text."}}}},"mentions":{"type":["array","null"],"description":"Mentions with platform or derived_text provenance; text is not proof of an account relationship.","items":{"type":["object","null"],"description":"Entity observed at source or derived from text.","properties":{"name":{"type":["string","null"],"description":"Hashtag or account name."},"id":{"type":["string","null"],"description":"Platform ID when supplied."},"source":{"type":["string","null"],"description":"platform or derived_text."}}}},"category_id":{"type":["string","null"],"description":"YouTube category ID."},"language":{"type":["string","null"],"description":"Default metadata language."},"audio_language":{"type":["string","null"],"description":"Default audio language."},"localized":{"type":["object","null"],"description":"Selected localized text.","properties":{"title":{"type":["string","null"],"description":"Title."},"description":{"type":["string","null"],"description":"Description."}}},"localizations":{"type":["object","null"],"description":"Returned language-to-title/description map."},"duration_iso8601":{"type":["string","null"],"description":"Source ISO 8601 duration."},"dimension":{"type":["string","null"],"description":"2d or 3d."},"definition":{"type":["string","null"],"description":"hd or sd."},"licensed_content":{"type":["boolean","null"],"description":"Source licensed-content flag."},"region_restriction":{"type":["object","null"],"description":"An omitted list differs from an empty list. An empty allowed list blocks everywhere; an empty blocked list blocks nowhere.","properties":{"allowed":{"type":["array","null"],"description":"Countries where viewing is permitted.","items":{"type":["string","null"],"description":"Source value."}},"blocked":{"type":["array","null"],"description":"Countries where viewing is blocked.","items":{"type":["string","null"],"description":"Source value."}}}},"content_rating":{"type":["object","null"],"description":"Country/authority rating map retained without enumerating columns."},"projection":{"type":["string","null"],"description":"Projection format."},"privacy_status":{"type":["string","null"],"description":"Source public/unlisted status when returned without account authorization."},"license":{"type":["string","null"],"description":"Source license."},"public_stats_viewable":{"type":["boolean","null"],"description":"Source public-statistics setting."},"made_for_kids":{"type":["boolean","null"],"description":"Current source designation when publicly returned; not the owner-only self-declared setting."},"contains_synthetic_media":{"type":["boolean","null"],"description":"Source altered/synthetic-media disclosure when publicly returned; not an AI prediction."},"paid_partnership":{"type":["boolean","null"],"description":"Explicit source paid-product-placement flag when publicly returned."},"topic_ids":{"type":["array","null"],"description":"Legacy source topic IDs, when returned.","items":{"type":["string","null"],"description":"Source value."}},"topic_categories":{"type":["array","null"],"description":"Topic-category URLs.","items":{"type":["string","null"],"description":"Source value."}},"recording_date":{"type":["string","null"],"description":"Public recording date, when returned."},"embed_html":{"type":["string","null"],"description":"Source embed markup as a string. Never execute returned HTML without sanitizing."},"embed_height":{"type":["number","null"],"description":"Source embed height."},"embed_width":{"type":["number","null"],"description":"Source embed width."},"live_status":{"type":["string","null"],"description":"live, upcoming or none when supplied."},"title":{"type":["string","null"],"description":"Video title."},"description":{"type":["string","null"],"description":"Video description."},"channel_id":{"type":["string","null"],"description":"Owning channel ID."},"tags":{"type":["array","null"],"description":"Keyword tags; distinct from hashtags.","items":{"type":["string","null"],"description":"Keyword tag."}},"thumbnails":{"type":["array","null"],"description":"Returned thumbnail variants and dimensions.","items":{"type":["object","null"],"description":"One source media variant; URLs may expire.","properties":{"url":{"type":["string","null"],"description":"Source URL."},"width":{"type":["number","null"],"description":"Width in pixels."},"height":{"type":["number","null"],"description":"Height in pixels."},"asset_type":{"type":["string","null"],"description":"image, video, thumbnail or avatar."},"variant":{"type":["string","null"],"description":"Source variant when known."},"expires_at":{"type":["string","null"],"description":"Expiry timestamp when known."}}}},"author_avatar_url":{"type":["string","null"],"description":"Channel avatar from the watch page."},"channel_url":{"type":["string","null"],"description":"Channel URL built from the observed channel ID."},"upload_date":{"type":["string","null"],"description":"Source upload date, separate from publication date."},"available_countries":{"type":["array","null"],"description":"Allowed country list when the player exposes it; no inferred blocked countries.","items":{"type":["string","null"],"description":"Country code."}},"unlisted":{"type":["boolean","null"],"description":"Source unlisted flag."},"family_safe":{"type":["boolean","null"],"description":"Source family-safe flag; not the made-for-kids designation."},"counts_rounded":{"type":["object","null"],"description":"Precision of observed counters. Unknown precision is null.","properties":{"views":{"type":["boolean","null"],"description":"Views rounded."},"likes":{"type":["boolean","null"],"description":"Likes rounded."},"comments":{"type":["boolean","null"],"description":"Comments rounded."}}},"caption_tracks":{"type":["array","null"],"description":"Caption-track metadata without caption text.","items":{"type":["object","null"],"description":"One available caption language; URLs are not returned.","properties":{"language":{"type":["string","null"],"description":"Source language code."},"language_name":{"type":["string","null"],"description":"Source language label."},"generated":{"type":["boolean","null"],"description":"True for an automatic caption track."},"translatable":{"type":["boolean","null"],"description":"Source translation capability."}}}},"category":{"type":["string","null"],"description":"Source category name."},"is_live":{"type":["boolean","null"],"description":"Explicit current live state."},"is_live_content":{"type":["boolean","null"],"description":"Explicit live-content classification."},"captions_available":{"type":["boolean","null"],"description":"Caption-track availability when observable."},"embeddable":{"type":["boolean","null"],"description":"Player embed permission when returned."},"live":{"type":["object","null"],"description":"Returned broadcast start/end times and live-now state.","properties":{"actual_start_time":{"type":["string","null"],"description":"Source broadcast start time."},"actual_end_time":{"type":["string","null"],"description":"Source broadcast end time."},"is_live_now":{"type":["boolean","null"],"description":"Explicit live-now state."},"scheduled_start_time":{"type":["string","null"],"description":"Scheduled start time."},"scheduled_end_time":{"type":["string","null"],"description":"Scheduled end time."},"concurrent_viewers":{"type":["number","null"],"description":"Current live viewers, when public."},"active_live_chat_id":{"type":["string","null"],"description":"Active public live-chat ID when supplied."}}}}}}}}}}]}}}},"400":{"$ref":"#/components/responses/InvalidInput"},"401":{"$ref":"#/components/responses/InvalidApiKey"},"402":{"$ref":"#/components/responses/InsufficientCredits"},"403":{"$ref":"#/components/responses/SourceRestricted"},"404":{"$ref":"#/components/responses/ResourceNotFound"},"408":{"$ref":"#/components/responses/SourceTimeout"},"422":{"$ref":"#/components/responses/SourceResponseChanged"},"429":{"$ref":"#/components/responses/TemporaryCapacity"},"501":{"$ref":"#/components/responses/SourceNotImplemented"},"503":{"$ref":"#/components/responses/SourceUnavailable"}},"x-availability":"planned","x-identifier-one-of":["query"],"x-credits":2,"x-source-access":"public_page","x-preview":true,"x-codeSamples":[{"lang":"curl","source":"curl 'https://api.socialdatakit.com/v1/youtube/shorts/trending?query=GB' \\\n  -H 'x-api-key: YOUR_API_KEY'"},{"lang":"javascript","source":"const response = await fetch(\"https://api.socialdatakit.com/v1/youtube/shorts/trending?query=GB\", {\n  headers: { \"x-api-key\": process.env.SOCIALDATAKIT_API_KEY }\n});\nif (!response.ok) throw new Error(await response.text());\nconst result = await response.json();"},{"lang":"python","source":"import os\nimport requests\n\nresponse = requests.get(\n    \"https://api.socialdatakit.com/v1/youtube/shorts/trending?query=GB\",\n    headers={\"x-api-key\": os.environ[\"SOCIALDATAKIT_API_KEY\"]},\n    timeout=30,\n)\nresponse.raise_for_status()\nresult = response.json()"}],"x-response-fields":{"id":{"type":"string","description":"Resource identifier used by this endpoint."},"author":{"type":"string","description":"Public creator name or handle."},"published_at":{"type":"string","description":"Source publication date or timestamp; null when absent."},"views":{"type":"number","description":"Observed views, where exposed by this source."},"likes":{"type":"number","description":"Observed likes."},"comments":{"type":"number","description":"Observed comment count, not comment rows."},"media_url":{"type":"string","description":"Preview image URL; not a guaranteed downloadable video."},"permalink":{"type":"string","description":"Public content URL."},"duration_seconds":{"type":"number","description":"Duration in seconds when returned."},"hashtags":{"type":"array","description":"Hashtags with platform or derived_text provenance.","items":{"type":"object","description":"Entity observed at source or derived from text.","properties":{"name":{"type":"string","description":"Hashtag or account name."},"id":{"type":"string","description":"Platform ID when supplied."},"source":{"type":"string","description":"platform or derived_text."}}}},"mentions":{"type":"array","description":"Mentions with platform or derived_text provenance; text is not proof of an account relationship.","items":{"type":"object","description":"Entity observed at source or derived from text.","properties":{"name":{"type":"string","description":"Hashtag or account name."},"id":{"type":"string","description":"Platform ID when supplied."},"source":{"type":"string","description":"platform or derived_text."}}}},"category_id":{"type":"string","description":"YouTube category ID."},"language":{"type":"string","description":"Default metadata language."},"audio_language":{"type":"string","description":"Default audio language."},"localized":{"type":"object","description":"Selected localized text.","properties":{"title":{"type":"string","description":"Title."},"description":{"type":"string","description":"Description."}}},"localizations":{"type":"object","description":"Returned language-to-title/description map."},"duration_iso8601":{"type":"string","description":"Source ISO 8601 duration."},"dimension":{"type":"string","description":"2d or 3d."},"definition":{"type":"string","description":"hd or sd."},"licensed_content":{"type":"boolean","description":"Source licensed-content flag."},"region_restriction":{"type":"object","description":"An omitted list differs from an empty list. An empty allowed list blocks everywhere; an empty blocked list blocks nowhere.","properties":{"allowed":{"type":"array","description":"Countries where viewing is permitted.","items":{"type":"string","description":"Source value."}},"blocked":{"type":"array","description":"Countries where viewing is blocked.","items":{"type":"string","description":"Source value."}}}},"content_rating":{"type":"object","description":"Country/authority rating map retained without enumerating columns."},"projection":{"type":"string","description":"Projection format."},"privacy_status":{"type":"string","description":"Source public/unlisted status when returned without account authorization."},"license":{"type":"string","description":"Source license."},"public_stats_viewable":{"type":"boolean","description":"Source public-statistics setting."},"made_for_kids":{"type":"boolean","description":"Current source designation when publicly returned; not the owner-only self-declared setting."},"contains_synthetic_media":{"type":"boolean","description":"Source altered/synthetic-media disclosure when publicly returned; not an AI prediction."},"paid_partnership":{"type":"boolean","description":"Explicit source paid-product-placement flag when publicly returned."},"topic_ids":{"type":"array","description":"Legacy source topic IDs, when returned.","items":{"type":"string","description":"Source value."}},"topic_categories":{"type":"array","description":"Topic-category URLs.","items":{"type":"string","description":"Source value."}},"recording_date":{"type":"string","description":"Public recording date, when returned."},"embed_html":{"type":"string","description":"Source embed markup as a string. Never execute returned HTML without sanitizing."},"embed_height":{"type":"number","description":"Source embed height."},"embed_width":{"type":"number","description":"Source embed width."},"live_status":{"type":"string","description":"live, upcoming or none when supplied."},"title":{"type":"string","description":"Video title."},"description":{"type":"string","description":"Video description."},"channel_id":{"type":"string","description":"Owning channel ID."},"tags":{"type":"array","description":"Keyword tags; distinct from hashtags.","items":{"type":"string","description":"Keyword tag."}},"thumbnails":{"type":"array","description":"Returned thumbnail variants and dimensions.","items":{"type":"object","description":"One source media variant; URLs may expire.","properties":{"url":{"type":"string","description":"Source URL."},"width":{"type":"number","description":"Width in pixels."},"height":{"type":"number","description":"Height in pixels."},"asset_type":{"type":"string","description":"image, video, thumbnail or avatar."},"variant":{"type":"string","description":"Source variant when known."},"expires_at":{"type":"string","description":"Expiry timestamp when known."}}}},"author_avatar_url":{"type":"string","description":"Channel avatar from the watch page."},"channel_url":{"type":"string","description":"Channel URL built from the observed channel ID."},"upload_date":{"type":"string","description":"Source upload date, separate from publication date."},"available_countries":{"type":"array","description":"Allowed country list when the player exposes it; no inferred blocked countries.","items":{"type":"string","description":"Country code."}},"unlisted":{"type":"boolean","description":"Source unlisted flag."},"family_safe":{"type":"boolean","description":"Source family-safe flag; not the made-for-kids designation."},"counts_rounded":{"type":"object","description":"Precision of observed counters. Unknown precision is null.","properties":{"views":{"type":"boolean","description":"Views rounded."},"likes":{"type":"boolean","description":"Likes rounded."},"comments":{"type":"boolean","description":"Comments rounded."}}},"caption_tracks":{"type":"array","description":"Caption-track metadata without caption text.","items":{"type":"object","description":"One available caption language; URLs are not returned.","properties":{"language":{"type":"string","description":"Source language code."},"language_name":{"type":"string","description":"Source language label."},"generated":{"type":"boolean","description":"True for an automatic caption track."},"translatable":{"type":"boolean","description":"Source translation capability."}}}},"category":{"type":"string","description":"Source category name."},"is_live":{"type":"boolean","description":"Explicit current live state."},"is_live_content":{"type":"boolean","description":"Explicit live-content classification."},"captions_available":{"type":"boolean","description":"Caption-track availability when observable."},"embeddable":{"type":"boolean","description":"Player embed permission when returned."},"live":{"type":"object","description":"Returned broadcast start/end times and live-now state.","properties":{"actual_start_time":{"type":"string","description":"Source broadcast start time."},"actual_end_time":{"type":"string","description":"Source broadcast end time."},"is_live_now":{"type":"boolean","description":"Explicit live-now state."},"scheduled_start_time":{"type":"string","description":"Scheduled start time."},"scheduled_end_time":{"type":"string","description":"Scheduled end time."},"concurrent_viewers":{"type":"number","description":"Current live viewers, when public."},"active_live_chat_id":{"type":"string","description":"Active public live-chat ID when supplied."}}}}}},"/v1/twitter/profile":{"get":{"operationId":"twitter_v1_profile","summary":"Twitter/X profile","description":"Get a public profile. Planned: returns 501 SOURCE_NOT_IMPLEMENTED with no credits charged. Collector code is restricted to operator validation; no public collector or sample is enabled.","tags":["twitter"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"handle","in":"query","required":true,"schema":{"type":"string","pattern":"^@?[A-Za-z0-9_]{1,15}$","example":"nasa"},"description":"Required twitter handle."},{"name":"cache_max_age","in":"query","required":false,"schema":{"type":"string","enum":["1d","3d","7d","14d","30d"]},"description":"Maximum acceptable cache age. Valid cache hits cost zero credits."},{"name":"fields","in":"query","required":false,"schema":{"type":"string","example":"profile.username,profile.followers"},"description":"Comma-separated fields or dot paths, including inside arrays such as items.id. Response identity and pagination are retained."},{"name":"trim","in":"query","required":false,"schema":{"type":"boolean","default":false},"description":"Remove null and empty values. Meaningful empty YouTube region-restriction lists are retained."}],"responses":{"200":{"description":"Normalized resource","headers":{"x-request-id":{"schema":{"type":"string"}},"x-data-mode":{"schema":{"type":"string","enum":["live","sandbox"]}},"x-cache":{"schema":{"type":"string","enum":["HIT","MISS"]}},"x-credits-charged":{"schema":{"type":"integer"}},"x-credits-remaining":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"data":{"type":"object","properties":{"profile":{"type":"object","additionalProperties":true,"properties":{"id":{"type":["string","null"],"description":"Stable X user ID, preserved as a string."},"username":{"type":["string","null"],"description":"Current handle."},"display_name":{"type":["string","null"],"description":"Public display name."},"bio":{"type":["string","null"],"description":"Public biography."},"profile_url":{"type":["string","null"],"description":"Public X profile URL."},"created_at":{"type":["string","null"],"description":"Account creation timestamp."},"followers":{"type":["number","null"],"description":"Observed follower count."},"following":{"type":["number","null"],"description":"Observed following count."},"posts":{"type":["number","null"],"description":"Observed post count."},"listed_count":{"type":["number","null"],"description":"Public list membership count."},"verified":{"type":["boolean","null"],"description":"Source verification flag; not proof of cross-platform identity."},"verified_type":{"type":["string","null"],"description":"Source verification category."},"private":{"type":["boolean","null"],"description":"Explicit protected-account flag."},"avatar_url":{"type":["string","null"],"description":"Public profile image URL."},"external_url":{"type":["string","null"],"description":"Expanded public website URL when supplied."},"location":{"type":["string","null"],"description":"Self-described location, not verified residence."}}}}}}}]}}}},"400":{"$ref":"#/components/responses/InvalidInput"},"401":{"$ref":"#/components/responses/InvalidApiKey"},"402":{"$ref":"#/components/responses/InsufficientCredits"},"403":{"$ref":"#/components/responses/SourceRestricted"},"404":{"$ref":"#/components/responses/ResourceNotFound"},"408":{"$ref":"#/components/responses/SourceTimeout"},"422":{"$ref":"#/components/responses/SourceResponseChanged"},"429":{"$ref":"#/components/responses/TemporaryCapacity"},"501":{"$ref":"#/components/responses/SourceNotImplemented"},"503":{"$ref":"#/components/responses/SourceUnavailable"}},"x-availability":"planned","x-identifier-one-of":["handle"],"x-credits":1,"x-source-access":"x_api","x-preview":true,"x-codeSamples":[{"lang":"curl","source":"curl 'https://api.socialdatakit.com/v1/twitter/profile?handle=nasa' \\\n  -H 'x-api-key: YOUR_API_KEY'"},{"lang":"javascript","source":"const response = await fetch(\"https://api.socialdatakit.com/v1/twitter/profile?handle=nasa\", {\n  headers: { \"x-api-key\": process.env.SOCIALDATAKIT_API_KEY }\n});\nif (!response.ok) throw new Error(await response.text());\nconst result = await response.json();"},{"lang":"python","source":"import os\nimport requests\n\nresponse = requests.get(\n    \"https://api.socialdatakit.com/v1/twitter/profile?handle=nasa\",\n    headers={\"x-api-key\": os.environ[\"SOCIALDATAKIT_API_KEY\"]},\n    timeout=30,\n)\nresponse.raise_for_status()\nresult = response.json()"}],"x-response-fields":{"id":{"type":"string","description":"Stable X user ID, preserved as a string."},"username":{"type":"string","description":"Current handle."},"display_name":{"type":"string","description":"Public display name."},"bio":{"type":"string","description":"Public biography."},"profile_url":{"type":"string","description":"Public X profile URL."},"created_at":{"type":"string","description":"Account creation timestamp."},"followers":{"type":"number","description":"Observed follower count."},"following":{"type":"number","description":"Observed following count."},"posts":{"type":"number","description":"Observed post count."},"listed_count":{"type":"number","description":"Public list membership count."},"verified":{"type":"boolean","description":"Source verification flag; not proof of cross-platform identity."},"verified_type":{"type":"string","description":"Source verification category."},"private":{"type":"boolean","description":"Explicit protected-account flag."},"avatar_url":{"type":"string","description":"Public profile image URL."},"external_url":{"type":"string","description":"Expanded public website URL when supplied."},"location":{"type":"string","description":"Self-described location, not verified residence."}}}},"/v1/twitter/user/tweets":{"get":{"operationId":"twitter_v1_user_tweets","summary":"Twitter/X tweets","description":"Get public tweets from a profile. Planned: returns 501 SOURCE_NOT_IMPLEMENTED with no credits charged. Collector code is restricted to operator validation; no public collector or sample is enabled.","tags":["twitter"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"handle","in":"query","required":true,"schema":{"type":"string","pattern":"^@?[A-Za-z0-9_]{1,15}$","example":"nasa"},"description":"Required twitter handle."},{"name":"cache_max_age","in":"query","required":false,"schema":{"type":"string","enum":["1d","3d","7d","14d","30d"]},"description":"Maximum acceptable cache age. Valid cache hits cost zero credits."},{"name":"fields","in":"query","required":false,"schema":{"type":"string","example":"items"},"description":"Comma-separated fields or dot paths, including inside arrays such as items.id. Response identity and pagination are retained."},{"name":"trim","in":"query","required":false,"schema":{"type":"boolean","default":false},"description":"Remove null and empty values. Meaningful empty YouTube region-restriction lists are retained."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":20,"default":3},"description":"Number of items to return."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"},"description":"Opaque pagination value returned as data.pagination.next_cursor. Keep the identifier, filters and limit unchanged."}],"responses":{"200":{"description":"Normalized resource","headers":{"x-request-id":{"schema":{"type":"string"}},"x-data-mode":{"schema":{"type":"string","enum":["live","sandbox"]}},"x-cache":{"schema":{"type":"string","enum":["HIT","MISS"]}},"x-credits-charged":{"schema":{"type":"integer"}},"x-credits-remaining":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"data":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","additionalProperties":true,"properties":{"id":{"type":["string","null"],"description":"Stable post ID, preserved as a string."},"text":{"type":["string","null"],"description":"Post text; long-form text when supplied."},"author":{"type":["string","null"],"description":"Public author handle when expanded."},"author_id":{"type":["string","null"],"description":"Stable author ID."},"author_display_name":{"type":["string","null"],"description":"Expanded display name."},"author_verified":{"type":["boolean","null"],"description":"Explicit author verification flag."},"author_avatar_url":{"type":["string","null"],"description":"Expanded profile image URL."},"published_at":{"type":["string","null"],"description":"Publication timestamp."},"permalink":{"type":["string","null"],"description":"Public post URL."},"language":{"type":["string","null"],"description":"Source language code."},"conversation_id":{"type":["string","null"],"description":"Conversation ID."},"possibly_sensitive":{"type":["boolean","null"],"description":"Explicit sensitive-content flag."},"likes":{"type":["number","null"],"description":"Public like count."},"comments":{"type":["number","null"],"description":"Public reply count, not reply rows."},"reposts":{"type":["number","null"],"description":"Public repost count."},"quotes":{"type":["number","null"],"description":"Public quote count."},"bookmarks":{"type":["number","null"],"description":"Public bookmark count when exposed."},"views":{"type":["number","null"],"description":"Public impression count when exposed; not unique viewers."},"hashtags":{"type":["array","null"],"description":"Source hashtags; null if not provided.","items":{"type":["object","null"],"description":"Source item.","properties":{"name":{"type":["string","null"],"description":"Hashtag or account handle."},"id":{"type":["string","null"],"description":"Source ID when supplied."},"source":{"type":["string","null"],"description":"platform; never inferred account ownership."}}}},"mentions":{"type":["array","null"],"description":"Source mentions; not verified account connections.","items":{"type":["object","null"],"description":"Source item.","properties":{"name":{"type":["string","null"],"description":"Hashtag or account handle."},"id":{"type":["string","null"],"description":"Source ID when supplied."},"source":{"type":["string","null"],"description":"platform; never inferred account ownership."}}}},"media":{"type":["array","null"],"description":"Attached media in source order. Missing expansions remain null; URLs may expire.","items":{"type":["object","null"],"description":"Source item.","properties":{"media_key":{"type":["string","null"],"description":"Source media key."},"type":{"type":["string","null"],"description":"Source media type."},"url":{"type":["string","null"],"description":"Image URL when exposed."},"preview_url":{"type":["string","null"],"description":"Preview image URL."},"width":{"type":["number","null"],"description":"Width in pixels."},"height":{"type":["number","null"],"description":"Height in pixels."},"duration_seconds":{"type":["number","null"],"description":"Duration in seconds."},"alt_text":{"type":["string","null"],"description":"Source alt text."},"variants":{"type":["array","null"],"description":"Public playback variants when exposed.","items":{"type":["object","null"],"description":"Source item.","properties":{"url":{"type":["string","null"],"description":"Playback URL."},"content_type":{"type":["string","null"],"description":"MIME type."},"bit_rate":{"type":["number","null"],"description":"Bit rate when supplied."}}}}}}}}}}}}}}]}}}},"400":{"$ref":"#/components/responses/InvalidInput"},"401":{"$ref":"#/components/responses/InvalidApiKey"},"402":{"$ref":"#/components/responses/InsufficientCredits"},"403":{"$ref":"#/components/responses/SourceRestricted"},"404":{"$ref":"#/components/responses/ResourceNotFound"},"408":{"$ref":"#/components/responses/SourceTimeout"},"422":{"$ref":"#/components/responses/SourceResponseChanged"},"429":{"$ref":"#/components/responses/TemporaryCapacity"},"501":{"$ref":"#/components/responses/SourceNotImplemented"},"503":{"$ref":"#/components/responses/SourceUnavailable"}},"x-availability":"planned","x-identifier-one-of":["handle"],"x-credits":2,"x-source-access":"x_api","x-preview":true,"x-codeSamples":[{"lang":"curl","source":"curl 'https://api.socialdatakit.com/v1/twitter/user/tweets?handle=nasa' \\\n  -H 'x-api-key: YOUR_API_KEY'"},{"lang":"javascript","source":"const response = await fetch(\"https://api.socialdatakit.com/v1/twitter/user/tweets?handle=nasa\", {\n  headers: { \"x-api-key\": process.env.SOCIALDATAKIT_API_KEY }\n});\nif (!response.ok) throw new Error(await response.text());\nconst result = await response.json();"},{"lang":"python","source":"import os\nimport requests\n\nresponse = requests.get(\n    \"https://api.socialdatakit.com/v1/twitter/user/tweets?handle=nasa\",\n    headers={\"x-api-key\": os.environ[\"SOCIALDATAKIT_API_KEY\"]},\n    timeout=30,\n)\nresponse.raise_for_status()\nresult = response.json()"}],"x-response-fields":{"id":{"type":"string","description":"Stable post ID, preserved as a string."},"text":{"type":"string","description":"Post text; long-form text when supplied."},"author":{"type":"string","description":"Public author handle when expanded."},"author_id":{"type":"string","description":"Stable author ID."},"author_display_name":{"type":"string","description":"Expanded display name."},"author_verified":{"type":"boolean","description":"Explicit author verification flag."},"author_avatar_url":{"type":"string","description":"Expanded profile image URL."},"published_at":{"type":"string","description":"Publication timestamp."},"permalink":{"type":"string","description":"Public post URL."},"language":{"type":"string","description":"Source language code."},"conversation_id":{"type":"string","description":"Conversation ID."},"possibly_sensitive":{"type":"boolean","description":"Explicit sensitive-content flag."},"likes":{"type":"number","description":"Public like count."},"comments":{"type":"number","description":"Public reply count, not reply rows."},"reposts":{"type":"number","description":"Public repost count."},"quotes":{"type":"number","description":"Public quote count."},"bookmarks":{"type":"number","description":"Public bookmark count when exposed."},"views":{"type":"number","description":"Public impression count when exposed; not unique viewers."},"hashtags":{"type":"array","description":"Source hashtags; null if not provided.","items":{"type":"object","description":"Source item.","properties":{"name":{"type":"string","description":"Hashtag or account handle."},"id":{"type":"string","description":"Source ID when supplied."},"source":{"type":"string","description":"platform; never inferred account ownership."}}}},"mentions":{"type":"array","description":"Source mentions; not verified account connections.","items":{"type":"object","description":"Source item.","properties":{"name":{"type":"string","description":"Hashtag or account handle."},"id":{"type":"string","description":"Source ID when supplied."},"source":{"type":"string","description":"platform; never inferred account ownership."}}}},"media":{"type":"array","description":"Attached media in source order. Missing expansions remain null; URLs may expire.","items":{"type":"object","description":"Source item.","properties":{"media_key":{"type":"string","description":"Source media key."},"type":{"type":"string","description":"Source media type."},"url":{"type":"string","description":"Image URL when exposed."},"preview_url":{"type":"string","description":"Preview image URL."},"width":{"type":"number","description":"Width in pixels."},"height":{"type":"number","description":"Height in pixels."},"duration_seconds":{"type":"number","description":"Duration in seconds."},"alt_text":{"type":"string","description":"Source alt text."},"variants":{"type":"array","description":"Public playback variants when exposed.","items":{"type":"object","description":"Source item.","properties":{"url":{"type":"string","description":"Playback URL."},"content_type":{"type":"string","description":"MIME type."},"bit_rate":{"type":"number","description":"Bit rate when supplied."}}}}}}}}}},"/v1/twitter/tweet":{"get":{"operationId":"twitter_v1_tweet","summary":"Twitter/X tweet","description":"Get a single public tweet. Planned: returns 501 SOURCE_NOT_IMPLEMENTED with no credits charged. Collector code is restricted to operator validation; no public collector or sample is enabled.","tags":["twitter"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"url","in":"query","required":true,"schema":{"type":"string","pattern":"^https?://[^\\s]{5,400}$","example":"https://x.com/nasa/status/1234567890"},"description":"Required twitter url."},{"name":"cache_max_age","in":"query","required":false,"schema":{"type":"string","enum":["1d","3d","7d","14d","30d"]},"description":"Maximum acceptable cache age. Valid cache hits cost zero credits."},{"name":"fields","in":"query","required":false,"schema":{"type":"string","example":"item"},"description":"Comma-separated fields or dot paths, including inside arrays such as items.id. Response identity and pagination are retained."},{"name":"trim","in":"query","required":false,"schema":{"type":"boolean","default":false},"description":"Remove null and empty values. Meaningful empty YouTube region-restriction lists are retained."}],"responses":{"200":{"description":"Normalized resource","headers":{"x-request-id":{"schema":{"type":"string"}},"x-data-mode":{"schema":{"type":"string","enum":["live","sandbox"]}},"x-cache":{"schema":{"type":"string","enum":["HIT","MISS"]}},"x-credits-charged":{"schema":{"type":"integer"}},"x-credits-remaining":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"data":{"type":"object","properties":{"item":{"type":"object","additionalProperties":true,"properties":{"id":{"type":["string","null"],"description":"Stable post ID, preserved as a string."},"text":{"type":["string","null"],"description":"Post text; long-form text when supplied."},"author":{"type":["string","null"],"description":"Public author handle when expanded."},"author_id":{"type":["string","null"],"description":"Stable author ID."},"author_display_name":{"type":["string","null"],"description":"Expanded display name."},"author_verified":{"type":["boolean","null"],"description":"Explicit author verification flag."},"author_avatar_url":{"type":["string","null"],"description":"Expanded profile image URL."},"published_at":{"type":["string","null"],"description":"Publication timestamp."},"permalink":{"type":["string","null"],"description":"Public post URL."},"language":{"type":["string","null"],"description":"Source language code."},"conversation_id":{"type":["string","null"],"description":"Conversation ID."},"possibly_sensitive":{"type":["boolean","null"],"description":"Explicit sensitive-content flag."},"likes":{"type":["number","null"],"description":"Public like count."},"comments":{"type":["number","null"],"description":"Public reply count, not reply rows."},"reposts":{"type":["number","null"],"description":"Public repost count."},"quotes":{"type":["number","null"],"description":"Public quote count."},"bookmarks":{"type":["number","null"],"description":"Public bookmark count when exposed."},"views":{"type":["number","null"],"description":"Public impression count when exposed; not unique viewers."},"hashtags":{"type":["array","null"],"description":"Source hashtags; null if not provided.","items":{"type":["object","null"],"description":"Source item.","properties":{"name":{"type":["string","null"],"description":"Hashtag or account handle."},"id":{"type":["string","null"],"description":"Source ID when supplied."},"source":{"type":["string","null"],"description":"platform; never inferred account ownership."}}}},"mentions":{"type":["array","null"],"description":"Source mentions; not verified account connections.","items":{"type":["object","null"],"description":"Source item.","properties":{"name":{"type":["string","null"],"description":"Hashtag or account handle."},"id":{"type":["string","null"],"description":"Source ID when supplied."},"source":{"type":["string","null"],"description":"platform; never inferred account ownership."}}}},"media":{"type":["array","null"],"description":"Attached media in source order. Missing expansions remain null; URLs may expire.","items":{"type":["object","null"],"description":"Source item.","properties":{"media_key":{"type":["string","null"],"description":"Source media key."},"type":{"type":["string","null"],"description":"Source media type."},"url":{"type":["string","null"],"description":"Image URL when exposed."},"preview_url":{"type":["string","null"],"description":"Preview image URL."},"width":{"type":["number","null"],"description":"Width in pixels."},"height":{"type":["number","null"],"description":"Height in pixels."},"duration_seconds":{"type":["number","null"],"description":"Duration in seconds."},"alt_text":{"type":["string","null"],"description":"Source alt text."},"variants":{"type":["array","null"],"description":"Public playback variants when exposed.","items":{"type":["object","null"],"description":"Source item.","properties":{"url":{"type":["string","null"],"description":"Playback URL."},"content_type":{"type":["string","null"],"description":"MIME type."},"bit_rate":{"type":["number","null"],"description":"Bit rate when supplied."}}}}}}}}}}}}}]}}}},"400":{"$ref":"#/components/responses/InvalidInput"},"401":{"$ref":"#/components/responses/InvalidApiKey"},"402":{"$ref":"#/components/responses/InsufficientCredits"},"403":{"$ref":"#/components/responses/SourceRestricted"},"404":{"$ref":"#/components/responses/ResourceNotFound"},"408":{"$ref":"#/components/responses/SourceTimeout"},"422":{"$ref":"#/components/responses/SourceResponseChanged"},"429":{"$ref":"#/components/responses/TemporaryCapacity"},"501":{"$ref":"#/components/responses/SourceNotImplemented"},"503":{"$ref":"#/components/responses/SourceUnavailable"}},"x-availability":"planned","x-identifier-one-of":["url"],"x-credits":1,"x-source-access":"x_api","x-preview":true,"x-codeSamples":[{"lang":"curl","source":"curl 'https://api.socialdatakit.com/v1/twitter/tweet?url=https%3A%2F%2Fx.com%2Fnasa%2Fstatus%2F1234567890' \\\n  -H 'x-api-key: YOUR_API_KEY'"},{"lang":"javascript","source":"const response = await fetch(\"https://api.socialdatakit.com/v1/twitter/tweet?url=https%3A%2F%2Fx.com%2Fnasa%2Fstatus%2F1234567890\", {\n  headers: { \"x-api-key\": process.env.SOCIALDATAKIT_API_KEY }\n});\nif (!response.ok) throw new Error(await response.text());\nconst result = await response.json();"},{"lang":"python","source":"import os\nimport requests\n\nresponse = requests.get(\n    \"https://api.socialdatakit.com/v1/twitter/tweet?url=https%3A%2F%2Fx.com%2Fnasa%2Fstatus%2F1234567890\",\n    headers={\"x-api-key\": os.environ[\"SOCIALDATAKIT_API_KEY\"]},\n    timeout=30,\n)\nresponse.raise_for_status()\nresult = response.json()"}],"x-response-fields":{"id":{"type":"string","description":"Stable post ID, preserved as a string."},"text":{"type":"string","description":"Post text; long-form text when supplied."},"author":{"type":"string","description":"Public author handle when expanded."},"author_id":{"type":"string","description":"Stable author ID."},"author_display_name":{"type":"string","description":"Expanded display name."},"author_verified":{"type":"boolean","description":"Explicit author verification flag."},"author_avatar_url":{"type":"string","description":"Expanded profile image URL."},"published_at":{"type":"string","description":"Publication timestamp."},"permalink":{"type":"string","description":"Public post URL."},"language":{"type":"string","description":"Source language code."},"conversation_id":{"type":"string","description":"Conversation ID."},"possibly_sensitive":{"type":"boolean","description":"Explicit sensitive-content flag."},"likes":{"type":"number","description":"Public like count."},"comments":{"type":"number","description":"Public reply count, not reply rows."},"reposts":{"type":"number","description":"Public repost count."},"quotes":{"type":"number","description":"Public quote count."},"bookmarks":{"type":"number","description":"Public bookmark count when exposed."},"views":{"type":"number","description":"Public impression count when exposed; not unique viewers."},"hashtags":{"type":"array","description":"Source hashtags; null if not provided.","items":{"type":"object","description":"Source item.","properties":{"name":{"type":"string","description":"Hashtag or account handle."},"id":{"type":"string","description":"Source ID when supplied."},"source":{"type":"string","description":"platform; never inferred account ownership."}}}},"mentions":{"type":"array","description":"Source mentions; not verified account connections.","items":{"type":"object","description":"Source item.","properties":{"name":{"type":"string","description":"Hashtag or account handle."},"id":{"type":"string","description":"Source ID when supplied."},"source":{"type":"string","description":"platform; never inferred account ownership."}}}},"media":{"type":"array","description":"Attached media in source order. Missing expansions remain null; URLs may expire.","items":{"type":"object","description":"Source item.","properties":{"media_key":{"type":"string","description":"Source media key."},"type":{"type":"string","description":"Source media type."},"url":{"type":"string","description":"Image URL when exposed."},"preview_url":{"type":"string","description":"Preview image URL."},"width":{"type":"number","description":"Width in pixels."},"height":{"type":"number","description":"Height in pixels."},"duration_seconds":{"type":"number","description":"Duration in seconds."},"alt_text":{"type":"string","description":"Source alt text."},"variants":{"type":"array","description":"Public playback variants when exposed.","items":{"type":"object","description":"Source item.","properties":{"url":{"type":"string","description":"Playback URL."},"content_type":{"type":"string","description":"MIME type."},"bit_rate":{"type":"number","description":"Bit rate when supplied."}}}}}}}}}},"/v1/twitter/tweet/transcript":{"get":{"operationId":"twitter_v1_tweet_transcript","summary":"Twitter/X tweet transcript","description":"Get a transcript for a public video tweet. Planned: returns 501 SOURCE_NOT_IMPLEMENTED; no collector or sample response is available and no credits are charged.","tags":["twitter"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"url","in":"query","required":true,"schema":{"type":"string","pattern":"^https?://[^\\s]{5,400}$","example":"https://x.com/nasa/status/1234567890"},"description":"Required twitter url."},{"name":"cache_max_age","in":"query","required":false,"schema":{"type":"string","enum":["1d","3d","7d","14d","30d"]},"description":"Maximum acceptable cache age. Valid cache hits cost zero credits."},{"name":"fields","in":"query","required":false,"schema":{"type":"string","example":"item"},"description":"Comma-separated fields or dot paths, including inside arrays such as items.id. Response identity and pagination are retained."},{"name":"trim","in":"query","required":false,"schema":{"type":"boolean","default":false},"description":"Remove null and empty values. Meaningful empty YouTube region-restriction lists are retained."}],"responses":{"200":{"description":"Normalized resource","headers":{"x-request-id":{"schema":{"type":"string"}},"x-data-mode":{"schema":{"type":"string","enum":["live","sandbox"]}},"x-cache":{"schema":{"type":"string","enum":["HIT","MISS"]}},"x-credits-charged":{"schema":{"type":"integer"}},"x-credits-remaining":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"data":{"type":"object","properties":{"item":{"type":"object","additionalProperties":true,"properties":{"id":{"type":["string","null"],"description":"Resource identifier used by this endpoint."},"author":{"type":["string","null"],"description":"Public creator name or handle."},"published_at":{"type":["string","null"],"description":"Source publication date or timestamp; null when absent."},"views":{"type":["number","null"],"description":"Observed views, where exposed by this source."},"likes":{"type":["number","null"],"description":"Observed likes."},"comments":{"type":["number","null"],"description":"Observed comment count, not comment rows."},"media_url":{"type":["string","null"],"description":"Preview image URL; not a guaranteed downloadable video."},"permalink":{"type":["string","null"],"description":"Public content URL."},"duration_seconds":{"type":["number","null"],"description":"Duration in seconds when returned."},"hashtags":{"type":["array","null"],"description":"Hashtags with platform or derived_text provenance.","items":{"type":["object","null"],"description":"Entity observed at source or derived from text.","properties":{"name":{"type":["string","null"],"description":"Hashtag or account name."},"id":{"type":["string","null"],"description":"Platform ID when supplied."},"source":{"type":["string","null"],"description":"platform or derived_text."}}}},"mentions":{"type":["array","null"],"description":"Mentions with platform or derived_text provenance; text is not proof of an account relationship.","items":{"type":["object","null"],"description":"Entity observed at source or derived from text.","properties":{"name":{"type":["string","null"],"description":"Hashtag or account name."},"id":{"type":["string","null"],"description":"Platform ID when supplied."},"source":{"type":["string","null"],"description":"platform or derived_text."}}}},"category_id":{"type":["string","null"],"description":"YouTube category ID."},"language":{"type":["string","null"],"description":"Default metadata language."},"audio_language":{"type":["string","null"],"description":"Default audio language."},"localized":{"type":["object","null"],"description":"Selected localized text.","properties":{"title":{"type":["string","null"],"description":"Title."},"description":{"type":["string","null"],"description":"Description."}}},"localizations":{"type":["object","null"],"description":"Returned language-to-title/description map."},"duration_iso8601":{"type":["string","null"],"description":"Source ISO 8601 duration."},"dimension":{"type":["string","null"],"description":"2d or 3d."},"definition":{"type":["string","null"],"description":"hd or sd."},"licensed_content":{"type":["boolean","null"],"description":"Source licensed-content flag."},"region_restriction":{"type":["object","null"],"description":"An omitted list differs from an empty list. An empty allowed list blocks everywhere; an empty blocked list blocks nowhere.","properties":{"allowed":{"type":["array","null"],"description":"Countries where viewing is permitted.","items":{"type":["string","null"],"description":"Source value."}},"blocked":{"type":["array","null"],"description":"Countries where viewing is blocked.","items":{"type":["string","null"],"description":"Source value."}}}},"content_rating":{"type":["object","null"],"description":"Country/authority rating map retained without enumerating columns."},"projection":{"type":["string","null"],"description":"Projection format."},"privacy_status":{"type":["string","null"],"description":"Source public/unlisted status when returned without account authorization."},"license":{"type":["string","null"],"description":"Source license."},"public_stats_viewable":{"type":["boolean","null"],"description":"Source public-statistics setting."},"made_for_kids":{"type":["boolean","null"],"description":"Current source designation when publicly returned; not the owner-only self-declared setting."},"contains_synthetic_media":{"type":["boolean","null"],"description":"Source altered/synthetic-media disclosure when publicly returned; not an AI prediction."},"paid_partnership":{"type":["boolean","null"],"description":"Explicit source paid-product-placement flag when publicly returned."},"topic_ids":{"type":["array","null"],"description":"Legacy source topic IDs, when returned.","items":{"type":["string","null"],"description":"Source value."}},"topic_categories":{"type":["array","null"],"description":"Topic-category URLs.","items":{"type":["string","null"],"description":"Source value."}},"recording_date":{"type":["string","null"],"description":"Public recording date, when returned."},"embed_html":{"type":["string","null"],"description":"Source embed markup as a string. Never execute returned HTML without sanitizing."},"embed_height":{"type":["number","null"],"description":"Source embed height."},"embed_width":{"type":["number","null"],"description":"Source embed width."},"live_status":{"type":["string","null"],"description":"live, upcoming or none when supplied."},"title":{"type":["string","null"],"description":"Video title."},"description":{"type":["string","null"],"description":"Video description."},"channel_id":{"type":["string","null"],"description":"Owning channel ID."},"tags":{"type":["array","null"],"description":"Keyword tags; distinct from hashtags.","items":{"type":["string","null"],"description":"Keyword tag."}},"thumbnails":{"type":["array","null"],"description":"Returned thumbnail variants and dimensions.","items":{"type":["object","null"],"description":"One source media variant; URLs may expire.","properties":{"url":{"type":["string","null"],"description":"Source URL."},"width":{"type":["number","null"],"description":"Width in pixels."},"height":{"type":["number","null"],"description":"Height in pixels."},"asset_type":{"type":["string","null"],"description":"image, video, thumbnail or avatar."},"variant":{"type":["string","null"],"description":"Source variant when known."},"expires_at":{"type":["string","null"],"description":"Expiry timestamp when known."}}}},"author_avatar_url":{"type":["string","null"],"description":"Channel avatar from the watch page."},"channel_url":{"type":["string","null"],"description":"Channel URL built from the observed channel ID."},"upload_date":{"type":["string","null"],"description":"Source upload date, separate from publication date."},"available_countries":{"type":["array","null"],"description":"Allowed country list when the player exposes it; no inferred blocked countries.","items":{"type":["string","null"],"description":"Country code."}},"unlisted":{"type":["boolean","null"],"description":"Source unlisted flag."},"family_safe":{"type":["boolean","null"],"description":"Source family-safe flag; not the made-for-kids designation."},"counts_rounded":{"type":["object","null"],"description":"Precision of observed counters. Unknown precision is null.","properties":{"views":{"type":["boolean","null"],"description":"Views rounded."},"likes":{"type":["boolean","null"],"description":"Likes rounded."},"comments":{"type":["boolean","null"],"description":"Comments rounded."}}},"caption_tracks":{"type":["array","null"],"description":"Caption-track metadata without caption text.","items":{"type":["object","null"],"description":"One available caption language; URLs are not returned.","properties":{"language":{"type":["string","null"],"description":"Source language code."},"language_name":{"type":["string","null"],"description":"Source language label."},"generated":{"type":["boolean","null"],"description":"True for an automatic caption track."},"translatable":{"type":["boolean","null"],"description":"Source translation capability."}}}},"category":{"type":["string","null"],"description":"Source category name."},"is_live":{"type":["boolean","null"],"description":"Explicit current live state."},"is_live_content":{"type":["boolean","null"],"description":"Explicit live-content classification."},"captions_available":{"type":["boolean","null"],"description":"Caption-track availability when observable."},"embeddable":{"type":["boolean","null"],"description":"Player embed permission when returned."},"live":{"type":["object","null"],"description":"Returned broadcast start/end times and live-now state.","properties":{"actual_start_time":{"type":["string","null"],"description":"Source broadcast start time."},"actual_end_time":{"type":["string","null"],"description":"Source broadcast end time."},"is_live_now":{"type":["boolean","null"],"description":"Explicit live-now state."},"scheduled_start_time":{"type":["string","null"],"description":"Scheduled start time."},"scheduled_end_time":{"type":["string","null"],"description":"Scheduled end time."},"concurrent_viewers":{"type":["number","null"],"description":"Current live viewers, when public."},"active_live_chat_id":{"type":["string","null"],"description":"Active public live-chat ID when supplied."}}}}}}}}}]}}}},"400":{"$ref":"#/components/responses/InvalidInput"},"401":{"$ref":"#/components/responses/InvalidApiKey"},"402":{"$ref":"#/components/responses/InsufficientCredits"},"403":{"$ref":"#/components/responses/SourceRestricted"},"404":{"$ref":"#/components/responses/ResourceNotFound"},"408":{"$ref":"#/components/responses/SourceTimeout"},"422":{"$ref":"#/components/responses/SourceResponseChanged"},"429":{"$ref":"#/components/responses/TemporaryCapacity"},"501":{"$ref":"#/components/responses/SourceNotImplemented"},"503":{"$ref":"#/components/responses/SourceUnavailable"}},"x-availability":"planned","x-identifier-one-of":["url"],"x-credits":4,"x-source-access":"public_page","x-preview":true,"x-codeSamples":[{"lang":"curl","source":"curl 'https://api.socialdatakit.com/v1/twitter/tweet/transcript?url=https%3A%2F%2Fx.com%2Fnasa%2Fstatus%2F1234567890' \\\n  -H 'x-api-key: YOUR_API_KEY'"},{"lang":"javascript","source":"const response = await fetch(\"https://api.socialdatakit.com/v1/twitter/tweet/transcript?url=https%3A%2F%2Fx.com%2Fnasa%2Fstatus%2F1234567890\", {\n  headers: { \"x-api-key\": process.env.SOCIALDATAKIT_API_KEY }\n});\nif (!response.ok) throw new Error(await response.text());\nconst result = await response.json();"},{"lang":"python","source":"import os\nimport requests\n\nresponse = requests.get(\n    \"https://api.socialdatakit.com/v1/twitter/tweet/transcript?url=https%3A%2F%2Fx.com%2Fnasa%2Fstatus%2F1234567890\",\n    headers={\"x-api-key\": os.environ[\"SOCIALDATAKIT_API_KEY\"]},\n    timeout=30,\n)\nresponse.raise_for_status()\nresult = response.json()"}],"x-response-fields":{"id":{"type":"string","description":"Resource identifier used by this endpoint."},"author":{"type":"string","description":"Public creator name or handle."},"published_at":{"type":"string","description":"Source publication date or timestamp; null when absent."},"views":{"type":"number","description":"Observed views, where exposed by this source."},"likes":{"type":"number","description":"Observed likes."},"comments":{"type":"number","description":"Observed comment count, not comment rows."},"media_url":{"type":"string","description":"Preview image URL; not a guaranteed downloadable video."},"permalink":{"type":"string","description":"Public content URL."},"duration_seconds":{"type":"number","description":"Duration in seconds when returned."},"hashtags":{"type":"array","description":"Hashtags with platform or derived_text provenance.","items":{"type":"object","description":"Entity observed at source or derived from text.","properties":{"name":{"type":"string","description":"Hashtag or account name."},"id":{"type":"string","description":"Platform ID when supplied."},"source":{"type":"string","description":"platform or derived_text."}}}},"mentions":{"type":"array","description":"Mentions with platform or derived_text provenance; text is not proof of an account relationship.","items":{"type":"object","description":"Entity observed at source or derived from text.","properties":{"name":{"type":"string","description":"Hashtag or account name."},"id":{"type":"string","description":"Platform ID when supplied."},"source":{"type":"string","description":"platform or derived_text."}}}},"category_id":{"type":"string","description":"YouTube category ID."},"language":{"type":"string","description":"Default metadata language."},"audio_language":{"type":"string","description":"Default audio language."},"localized":{"type":"object","description":"Selected localized text.","properties":{"title":{"type":"string","description":"Title."},"description":{"type":"string","description":"Description."}}},"localizations":{"type":"object","description":"Returned language-to-title/description map."},"duration_iso8601":{"type":"string","description":"Source ISO 8601 duration."},"dimension":{"type":"string","description":"2d or 3d."},"definition":{"type":"string","description":"hd or sd."},"licensed_content":{"type":"boolean","description":"Source licensed-content flag."},"region_restriction":{"type":"object","description":"An omitted list differs from an empty list. An empty allowed list blocks everywhere; an empty blocked list blocks nowhere.","properties":{"allowed":{"type":"array","description":"Countries where viewing is permitted.","items":{"type":"string","description":"Source value."}},"blocked":{"type":"array","description":"Countries where viewing is blocked.","items":{"type":"string","description":"Source value."}}}},"content_rating":{"type":"object","description":"Country/authority rating map retained without enumerating columns."},"projection":{"type":"string","description":"Projection format."},"privacy_status":{"type":"string","description":"Source public/unlisted status when returned without account authorization."},"license":{"type":"string","description":"Source license."},"public_stats_viewable":{"type":"boolean","description":"Source public-statistics setting."},"made_for_kids":{"type":"boolean","description":"Current source designation when publicly returned; not the owner-only self-declared setting."},"contains_synthetic_media":{"type":"boolean","description":"Source altered/synthetic-media disclosure when publicly returned; not an AI prediction."},"paid_partnership":{"type":"boolean","description":"Explicit source paid-product-placement flag when publicly returned."},"topic_ids":{"type":"array","description":"Legacy source topic IDs, when returned.","items":{"type":"string","description":"Source value."}},"topic_categories":{"type":"array","description":"Topic-category URLs.","items":{"type":"string","description":"Source value."}},"recording_date":{"type":"string","description":"Public recording date, when returned."},"embed_html":{"type":"string","description":"Source embed markup as a string. Never execute returned HTML without sanitizing."},"embed_height":{"type":"number","description":"Source embed height."},"embed_width":{"type":"number","description":"Source embed width."},"live_status":{"type":"string","description":"live, upcoming or none when supplied."},"title":{"type":"string","description":"Video title."},"description":{"type":"string","description":"Video description."},"channel_id":{"type":"string","description":"Owning channel ID."},"tags":{"type":"array","description":"Keyword tags; distinct from hashtags.","items":{"type":"string","description":"Keyword tag."}},"thumbnails":{"type":"array","description":"Returned thumbnail variants and dimensions.","items":{"type":"object","description":"One source media variant; URLs may expire.","properties":{"url":{"type":"string","description":"Source URL."},"width":{"type":"number","description":"Width in pixels."},"height":{"type":"number","description":"Height in pixels."},"asset_type":{"type":"string","description":"image, video, thumbnail or avatar."},"variant":{"type":"string","description":"Source variant when known."},"expires_at":{"type":"string","description":"Expiry timestamp when known."}}}},"author_avatar_url":{"type":"string","description":"Channel avatar from the watch page."},"channel_url":{"type":"string","description":"Channel URL built from the observed channel ID."},"upload_date":{"type":"string","description":"Source upload date, separate from publication date."},"available_countries":{"type":"array","description":"Allowed country list when the player exposes it; no inferred blocked countries.","items":{"type":"string","description":"Country code."}},"unlisted":{"type":"boolean","description":"Source unlisted flag."},"family_safe":{"type":"boolean","description":"Source family-safe flag; not the made-for-kids designation."},"counts_rounded":{"type":"object","description":"Precision of observed counters. Unknown precision is null.","properties":{"views":{"type":"boolean","description":"Views rounded."},"likes":{"type":"boolean","description":"Likes rounded."},"comments":{"type":"boolean","description":"Comments rounded."}}},"caption_tracks":{"type":"array","description":"Caption-track metadata without caption text.","items":{"type":"object","description":"One available caption language; URLs are not returned.","properties":{"language":{"type":"string","description":"Source language code."},"language_name":{"type":"string","description":"Source language label."},"generated":{"type":"boolean","description":"True for an automatic caption track."},"translatable":{"type":"boolean","description":"Source translation capability."}}}},"category":{"type":"string","description":"Source category name."},"is_live":{"type":"boolean","description":"Explicit current live state."},"is_live_content":{"type":"boolean","description":"Explicit live-content classification."},"captions_available":{"type":"boolean","description":"Caption-track availability when observable."},"embeddable":{"type":"boolean","description":"Player embed permission when returned."},"live":{"type":"object","description":"Returned broadcast start/end times and live-now state.","properties":{"actual_start_time":{"type":"string","description":"Source broadcast start time."},"actual_end_time":{"type":"string","description":"Source broadcast end time."},"is_live_now":{"type":"boolean","description":"Explicit live-now state."},"scheduled_start_time":{"type":"string","description":"Scheduled start time."},"scheduled_end_time":{"type":"string","description":"Scheduled end time."},"concurrent_viewers":{"type":"number","description":"Current live viewers, when public."},"active_live_chat_id":{"type":"string","description":"Active public live-chat ID when supplied."}}}}}},"/v1/twitter/community":{"get":{"operationId":"twitter_v1_community","summary":"Twitter/X community","description":"Get a public community. Planned: returns 501 SOURCE_NOT_IMPLEMENTED with no credits charged. Collector code is restricted to operator validation; no public collector or sample is enabled.","tags":["twitter"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"url","in":"query","required":true,"schema":{"type":"string","pattern":"^https?://[^\\s]{5,400}$","example":"https://x.com/i/communities/1234567890"},"description":"Required twitter url."},{"name":"cache_max_age","in":"query","required":false,"schema":{"type":"string","enum":["1d","3d","7d","14d","30d"]},"description":"Maximum acceptable cache age. Valid cache hits cost zero credits."},{"name":"fields","in":"query","required":false,"schema":{"type":"string","example":"item"},"description":"Comma-separated fields or dot paths, including inside arrays such as items.id. Response identity and pagination are retained."},{"name":"trim","in":"query","required":false,"schema":{"type":"boolean","default":false},"description":"Remove null and empty values. Meaningful empty YouTube region-restriction lists are retained."}],"responses":{"200":{"description":"Normalized resource","headers":{"x-request-id":{"schema":{"type":"string"}},"x-data-mode":{"schema":{"type":"string","enum":["live","sandbox"]}},"x-cache":{"schema":{"type":"string","enum":["HIT","MISS"]}},"x-credits-charged":{"schema":{"type":"integer"}},"x-credits-remaining":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"data":{"type":"object","properties":{"item":{"type":"object","additionalProperties":true,"properties":{"id":{"type":["string","null"],"description":"Stable community ID, preserved as a string."},"name":{"type":["string","null"],"description":"Community name."},"description":{"type":["string","null"],"description":"Public description."},"community_url":{"type":["string","null"],"description":"Public community URL."},"created_at":{"type":["string","null"],"description":"Creation timestamp."},"member_count":{"type":["number","null"],"description":"Observed member count."},"access":{"type":["string","null"],"description":"Source visibility; only public communities are collected."},"join_policy":{"type":["string","null"],"description":"Membership rule; separate from visibility."}}}}}}}]}}}},"400":{"$ref":"#/components/responses/InvalidInput"},"401":{"$ref":"#/components/responses/InvalidApiKey"},"402":{"$ref":"#/components/responses/InsufficientCredits"},"403":{"$ref":"#/components/responses/SourceRestricted"},"404":{"$ref":"#/components/responses/ResourceNotFound"},"408":{"$ref":"#/components/responses/SourceTimeout"},"422":{"$ref":"#/components/responses/SourceResponseChanged"},"429":{"$ref":"#/components/responses/TemporaryCapacity"},"501":{"$ref":"#/components/responses/SourceNotImplemented"},"503":{"$ref":"#/components/responses/SourceUnavailable"}},"x-availability":"planned","x-identifier-one-of":["url"],"x-credits":1,"x-source-access":"x_api","x-preview":true,"x-codeSamples":[{"lang":"curl","source":"curl 'https://api.socialdatakit.com/v1/twitter/community?url=https%3A%2F%2Fx.com%2Fi%2Fcommunities%2F1234567890' \\\n  -H 'x-api-key: YOUR_API_KEY'"},{"lang":"javascript","source":"const response = await fetch(\"https://api.socialdatakit.com/v1/twitter/community?url=https%3A%2F%2Fx.com%2Fi%2Fcommunities%2F1234567890\", {\n  headers: { \"x-api-key\": process.env.SOCIALDATAKIT_API_KEY }\n});\nif (!response.ok) throw new Error(await response.text());\nconst result = await response.json();"},{"lang":"python","source":"import os\nimport requests\n\nresponse = requests.get(\n    \"https://api.socialdatakit.com/v1/twitter/community?url=https%3A%2F%2Fx.com%2Fi%2Fcommunities%2F1234567890\",\n    headers={\"x-api-key\": os.environ[\"SOCIALDATAKIT_API_KEY\"]},\n    timeout=30,\n)\nresponse.raise_for_status()\nresult = response.json()"}],"x-response-fields":{"id":{"type":"string","description":"Stable community ID, preserved as a string."},"name":{"type":"string","description":"Community name."},"description":{"type":"string","description":"Public description."},"community_url":{"type":"string","description":"Public community URL."},"created_at":{"type":"string","description":"Creation timestamp."},"member_count":{"type":"number","description":"Observed member count."},"access":{"type":"string","description":"Source visibility; only public communities are collected."},"join_policy":{"type":"string","description":"Membership rule; separate from visibility."}}}},"/v1/twitter/community/tweets":{"get":{"operationId":"twitter_v1_community_tweets","summary":"Twitter/X community tweets","description":"Get public tweets in a community. Planned: returns 501 SOURCE_NOT_IMPLEMENTED; no collector or sample response is available and no credits are charged.","tags":["twitter"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"url","in":"query","required":true,"schema":{"type":"string","pattern":"^https?://[^\\s]{5,400}$","example":"https://x.com/i/communities/1234567890"},"description":"Required twitter url."},{"name":"cache_max_age","in":"query","required":false,"schema":{"type":"string","enum":["1d","3d","7d","14d","30d"]},"description":"Maximum acceptable cache age. Valid cache hits cost zero credits."},{"name":"fields","in":"query","required":false,"schema":{"type":"string","example":"items"},"description":"Comma-separated fields or dot paths, including inside arrays such as items.id. Response identity and pagination are retained."},{"name":"trim","in":"query","required":false,"schema":{"type":"boolean","default":false},"description":"Remove null and empty values. Meaningful empty YouTube region-restriction lists are retained."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":20,"default":3},"description":"Number of items to return."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"},"description":"Opaque pagination value returned as data.pagination.next_cursor. Keep the identifier, filters and limit unchanged."}],"responses":{"200":{"description":"Normalized resource","headers":{"x-request-id":{"schema":{"type":"string"}},"x-data-mode":{"schema":{"type":"string","enum":["live","sandbox"]}},"x-cache":{"schema":{"type":"string","enum":["HIT","MISS"]}},"x-credits-charged":{"schema":{"type":"integer"}},"x-credits-remaining":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"data":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","additionalProperties":true,"properties":{"id":{"type":["string","null"],"description":"Resource identifier used by this endpoint."},"author":{"type":["string","null"],"description":"Public creator name or handle."},"published_at":{"type":["string","null"],"description":"Source publication date or timestamp; null when absent."},"views":{"type":["number","null"],"description":"Observed views, where exposed by this source."},"likes":{"type":["number","null"],"description":"Observed likes."},"comments":{"type":["number","null"],"description":"Observed comment count, not comment rows."},"media_url":{"type":["string","null"],"description":"Preview image URL; not a guaranteed downloadable video."},"permalink":{"type":["string","null"],"description":"Public content URL."},"duration_seconds":{"type":["number","null"],"description":"Duration in seconds when returned."},"hashtags":{"type":["array","null"],"description":"Hashtags with platform or derived_text provenance.","items":{"type":["object","null"],"description":"Entity observed at source or derived from text.","properties":{"name":{"type":["string","null"],"description":"Hashtag or account name."},"id":{"type":["string","null"],"description":"Platform ID when supplied."},"source":{"type":["string","null"],"description":"platform or derived_text."}}}},"mentions":{"type":["array","null"],"description":"Mentions with platform or derived_text provenance; text is not proof of an account relationship.","items":{"type":["object","null"],"description":"Entity observed at source or derived from text.","properties":{"name":{"type":["string","null"],"description":"Hashtag or account name."},"id":{"type":["string","null"],"description":"Platform ID when supplied."},"source":{"type":["string","null"],"description":"platform or derived_text."}}}},"category_id":{"type":["string","null"],"description":"YouTube category ID."},"language":{"type":["string","null"],"description":"Default metadata language."},"audio_language":{"type":["string","null"],"description":"Default audio language."},"localized":{"type":["object","null"],"description":"Selected localized text.","properties":{"title":{"type":["string","null"],"description":"Title."},"description":{"type":["string","null"],"description":"Description."}}},"localizations":{"type":["object","null"],"description":"Returned language-to-title/description map."},"duration_iso8601":{"type":["string","null"],"description":"Source ISO 8601 duration."},"dimension":{"type":["string","null"],"description":"2d or 3d."},"definition":{"type":["string","null"],"description":"hd or sd."},"licensed_content":{"type":["boolean","null"],"description":"Source licensed-content flag."},"region_restriction":{"type":["object","null"],"description":"An omitted list differs from an empty list. An empty allowed list blocks everywhere; an empty blocked list blocks nowhere.","properties":{"allowed":{"type":["array","null"],"description":"Countries where viewing is permitted.","items":{"type":["string","null"],"description":"Source value."}},"blocked":{"type":["array","null"],"description":"Countries where viewing is blocked.","items":{"type":["string","null"],"description":"Source value."}}}},"content_rating":{"type":["object","null"],"description":"Country/authority rating map retained without enumerating columns."},"projection":{"type":["string","null"],"description":"Projection format."},"privacy_status":{"type":["string","null"],"description":"Source public/unlisted status when returned without account authorization."},"license":{"type":["string","null"],"description":"Source license."},"public_stats_viewable":{"type":["boolean","null"],"description":"Source public-statistics setting."},"made_for_kids":{"type":["boolean","null"],"description":"Current source designation when publicly returned; not the owner-only self-declared setting."},"contains_synthetic_media":{"type":["boolean","null"],"description":"Source altered/synthetic-media disclosure when publicly returned; not an AI prediction."},"paid_partnership":{"type":["boolean","null"],"description":"Explicit source paid-product-placement flag when publicly returned."},"topic_ids":{"type":["array","null"],"description":"Legacy source topic IDs, when returned.","items":{"type":["string","null"],"description":"Source value."}},"topic_categories":{"type":["array","null"],"description":"Topic-category URLs.","items":{"type":["string","null"],"description":"Source value."}},"recording_date":{"type":["string","null"],"description":"Public recording date, when returned."},"embed_html":{"type":["string","null"],"description":"Source embed markup as a string. Never execute returned HTML without sanitizing."},"embed_height":{"type":["number","null"],"description":"Source embed height."},"embed_width":{"type":["number","null"],"description":"Source embed width."},"live_status":{"type":["string","null"],"description":"live, upcoming or none when supplied."},"title":{"type":["string","null"],"description":"Video title."},"description":{"type":["string","null"],"description":"Video description."},"channel_id":{"type":["string","null"],"description":"Owning channel ID."},"tags":{"type":["array","null"],"description":"Keyword tags; distinct from hashtags.","items":{"type":["string","null"],"description":"Keyword tag."}},"thumbnails":{"type":["array","null"],"description":"Returned thumbnail variants and dimensions.","items":{"type":["object","null"],"description":"One source media variant; URLs may expire.","properties":{"url":{"type":["string","null"],"description":"Source URL."},"width":{"type":["number","null"],"description":"Width in pixels."},"height":{"type":["number","null"],"description":"Height in pixels."},"asset_type":{"type":["string","null"],"description":"image, video, thumbnail or avatar."},"variant":{"type":["string","null"],"description":"Source variant when known."},"expires_at":{"type":["string","null"],"description":"Expiry timestamp when known."}}}},"author_avatar_url":{"type":["string","null"],"description":"Channel avatar from the watch page."},"channel_url":{"type":["string","null"],"description":"Channel URL built from the observed channel ID."},"upload_date":{"type":["string","null"],"description":"Source upload date, separate from publication date."},"available_countries":{"type":["array","null"],"description":"Allowed country list when the player exposes it; no inferred blocked countries.","items":{"type":["string","null"],"description":"Country code."}},"unlisted":{"type":["boolean","null"],"description":"Source unlisted flag."},"family_safe":{"type":["boolean","null"],"description":"Source family-safe flag; not the made-for-kids designation."},"counts_rounded":{"type":["object","null"],"description":"Precision of observed counters. Unknown precision is null.","properties":{"views":{"type":["boolean","null"],"description":"Views rounded."},"likes":{"type":["boolean","null"],"description":"Likes rounded."},"comments":{"type":["boolean","null"],"description":"Comments rounded."}}},"caption_tracks":{"type":["array","null"],"description":"Caption-track metadata without caption text.","items":{"type":["object","null"],"description":"One available caption language; URLs are not returned.","properties":{"language":{"type":["string","null"],"description":"Source language code."},"language_name":{"type":["string","null"],"description":"Source language label."},"generated":{"type":["boolean","null"],"description":"True for an automatic caption track."},"translatable":{"type":["boolean","null"],"description":"Source translation capability."}}}},"category":{"type":["string","null"],"description":"Source category name."},"is_live":{"type":["boolean","null"],"description":"Explicit current live state."},"is_live_content":{"type":["boolean","null"],"description":"Explicit live-content classification."},"captions_available":{"type":["boolean","null"],"description":"Caption-track availability when observable."},"embeddable":{"type":["boolean","null"],"description":"Player embed permission when returned."},"live":{"type":["object","null"],"description":"Returned broadcast start/end times and live-now state.","properties":{"actual_start_time":{"type":["string","null"],"description":"Source broadcast start time."},"actual_end_time":{"type":["string","null"],"description":"Source broadcast end time."},"is_live_now":{"type":["boolean","null"],"description":"Explicit live-now state."},"scheduled_start_time":{"type":["string","null"],"description":"Scheduled start time."},"scheduled_end_time":{"type":["string","null"],"description":"Scheduled end time."},"concurrent_viewers":{"type":["number","null"],"description":"Current live viewers, when public."},"active_live_chat_id":{"type":["string","null"],"description":"Active public live-chat ID when supplied."}}}}}}}}}}]}}}},"400":{"$ref":"#/components/responses/InvalidInput"},"401":{"$ref":"#/components/responses/InvalidApiKey"},"402":{"$ref":"#/components/responses/InsufficientCredits"},"403":{"$ref":"#/components/responses/SourceRestricted"},"404":{"$ref":"#/components/responses/ResourceNotFound"},"408":{"$ref":"#/components/responses/SourceTimeout"},"422":{"$ref":"#/components/responses/SourceResponseChanged"},"429":{"$ref":"#/components/responses/TemporaryCapacity"},"501":{"$ref":"#/components/responses/SourceNotImplemented"},"503":{"$ref":"#/components/responses/SourceUnavailable"}},"x-availability":"planned","x-identifier-one-of":["url"],"x-credits":2,"x-source-access":"public_page","x-preview":true,"x-codeSamples":[{"lang":"curl","source":"curl 'https://api.socialdatakit.com/v1/twitter/community/tweets?url=https%3A%2F%2Fx.com%2Fi%2Fcommunities%2F1234567890' \\\n  -H 'x-api-key: YOUR_API_KEY'"},{"lang":"javascript","source":"const response = await fetch(\"https://api.socialdatakit.com/v1/twitter/community/tweets?url=https%3A%2F%2Fx.com%2Fi%2Fcommunities%2F1234567890\", {\n  headers: { \"x-api-key\": process.env.SOCIALDATAKIT_API_KEY }\n});\nif (!response.ok) throw new Error(await response.text());\nconst result = await response.json();"},{"lang":"python","source":"import os\nimport requests\n\nresponse = requests.get(\n    \"https://api.socialdatakit.com/v1/twitter/community/tweets?url=https%3A%2F%2Fx.com%2Fi%2Fcommunities%2F1234567890\",\n    headers={\"x-api-key\": os.environ[\"SOCIALDATAKIT_API_KEY\"]},\n    timeout=30,\n)\nresponse.raise_for_status()\nresult = response.json()"}],"x-response-fields":{"id":{"type":"string","description":"Resource identifier used by this endpoint."},"author":{"type":"string","description":"Public creator name or handle."},"published_at":{"type":"string","description":"Source publication date or timestamp; null when absent."},"views":{"type":"number","description":"Observed views, where exposed by this source."},"likes":{"type":"number","description":"Observed likes."},"comments":{"type":"number","description":"Observed comment count, not comment rows."},"media_url":{"type":"string","description":"Preview image URL; not a guaranteed downloadable video."},"permalink":{"type":"string","description":"Public content URL."},"duration_seconds":{"type":"number","description":"Duration in seconds when returned."},"hashtags":{"type":"array","description":"Hashtags with platform or derived_text provenance.","items":{"type":"object","description":"Entity observed at source or derived from text.","properties":{"name":{"type":"string","description":"Hashtag or account name."},"id":{"type":"string","description":"Platform ID when supplied."},"source":{"type":"string","description":"platform or derived_text."}}}},"mentions":{"type":"array","description":"Mentions with platform or derived_text provenance; text is not proof of an account relationship.","items":{"type":"object","description":"Entity observed at source or derived from text.","properties":{"name":{"type":"string","description":"Hashtag or account name."},"id":{"type":"string","description":"Platform ID when supplied."},"source":{"type":"string","description":"platform or derived_text."}}}},"category_id":{"type":"string","description":"YouTube category ID."},"language":{"type":"string","description":"Default metadata language."},"audio_language":{"type":"string","description":"Default audio language."},"localized":{"type":"object","description":"Selected localized text.","properties":{"title":{"type":"string","description":"Title."},"description":{"type":"string","description":"Description."}}},"localizations":{"type":"object","description":"Returned language-to-title/description map."},"duration_iso8601":{"type":"string","description":"Source ISO 8601 duration."},"dimension":{"type":"string","description":"2d or 3d."},"definition":{"type":"string","description":"hd or sd."},"licensed_content":{"type":"boolean","description":"Source licensed-content flag."},"region_restriction":{"type":"object","description":"An omitted list differs from an empty list. An empty allowed list blocks everywhere; an empty blocked list blocks nowhere.","properties":{"allowed":{"type":"array","description":"Countries where viewing is permitted.","items":{"type":"string","description":"Source value."}},"blocked":{"type":"array","description":"Countries where viewing is blocked.","items":{"type":"string","description":"Source value."}}}},"content_rating":{"type":"object","description":"Country/authority rating map retained without enumerating columns."},"projection":{"type":"string","description":"Projection format."},"privacy_status":{"type":"string","description":"Source public/unlisted status when returned without account authorization."},"license":{"type":"string","description":"Source license."},"public_stats_viewable":{"type":"boolean","description":"Source public-statistics setting."},"made_for_kids":{"type":"boolean","description":"Current source designation when publicly returned; not the owner-only self-declared setting."},"contains_synthetic_media":{"type":"boolean","description":"Source altered/synthetic-media disclosure when publicly returned; not an AI prediction."},"paid_partnership":{"type":"boolean","description":"Explicit source paid-product-placement flag when publicly returned."},"topic_ids":{"type":"array","description":"Legacy source topic IDs, when returned.","items":{"type":"string","description":"Source value."}},"topic_categories":{"type":"array","description":"Topic-category URLs.","items":{"type":"string","description":"Source value."}},"recording_date":{"type":"string","description":"Public recording date, when returned."},"embed_html":{"type":"string","description":"Source embed markup as a string. Never execute returned HTML without sanitizing."},"embed_height":{"type":"number","description":"Source embed height."},"embed_width":{"type":"number","description":"Source embed width."},"live_status":{"type":"string","description":"live, upcoming or none when supplied."},"title":{"type":"string","description":"Video title."},"description":{"type":"string","description":"Video description."},"channel_id":{"type":"string","description":"Owning channel ID."},"tags":{"type":"array","description":"Keyword tags; distinct from hashtags.","items":{"type":"string","description":"Keyword tag."}},"thumbnails":{"type":"array","description":"Returned thumbnail variants and dimensions.","items":{"type":"object","description":"One source media variant; URLs may expire.","properties":{"url":{"type":"string","description":"Source URL."},"width":{"type":"number","description":"Width in pixels."},"height":{"type":"number","description":"Height in pixels."},"asset_type":{"type":"string","description":"image, video, thumbnail or avatar."},"variant":{"type":"string","description":"Source variant when known."},"expires_at":{"type":"string","description":"Expiry timestamp when known."}}}},"author_avatar_url":{"type":"string","description":"Channel avatar from the watch page."},"channel_url":{"type":"string","description":"Channel URL built from the observed channel ID."},"upload_date":{"type":"string","description":"Source upload date, separate from publication date."},"available_countries":{"type":"array","description":"Allowed country list when the player exposes it; no inferred blocked countries.","items":{"type":"string","description":"Country code."}},"unlisted":{"type":"boolean","description":"Source unlisted flag."},"family_safe":{"type":"boolean","description":"Source family-safe flag; not the made-for-kids designation."},"counts_rounded":{"type":"object","description":"Precision of observed counters. Unknown precision is null.","properties":{"views":{"type":"boolean","description":"Views rounded."},"likes":{"type":"boolean","description":"Likes rounded."},"comments":{"type":"boolean","description":"Comments rounded."}}},"caption_tracks":{"type":"array","description":"Caption-track metadata without caption text.","items":{"type":"object","description":"One available caption language; URLs are not returned.","properties":{"language":{"type":"string","description":"Source language code."},"language_name":{"type":"string","description":"Source language label."},"generated":{"type":"boolean","description":"True for an automatic caption track."},"translatable":{"type":"boolean","description":"Source translation capability."}}}},"category":{"type":"string","description":"Source category name."},"is_live":{"type":"boolean","description":"Explicit current live state."},"is_live_content":{"type":"boolean","description":"Explicit live-content classification."},"captions_available":{"type":"boolean","description":"Caption-track availability when observable."},"embeddable":{"type":"boolean","description":"Player embed permission when returned."},"live":{"type":"object","description":"Returned broadcast start/end times and live-now state.","properties":{"actual_start_time":{"type":"string","description":"Source broadcast start time."},"actual_end_time":{"type":"string","description":"Source broadcast end time."},"is_live_now":{"type":"boolean","description":"Explicit live-now state."},"scheduled_start_time":{"type":"string","description":"Scheduled start time."},"scheduled_end_time":{"type":"string","description":"Scheduled end time."},"concurrent_viewers":{"type":"number","description":"Current live viewers, when public."},"active_live_chat_id":{"type":"string","description":"Active public live-chat ID when supplied."}}}}}},"/v1/facebook/adLibrary/company/ads":{"get":{"operationId":"facebook_adLibrary_company_ads","summary":"Meta company ads","description":"Preview contract for a company's public Meta Ad Library ads, creative assets, delivery dates and publisher platforms. Live access is pending source validation. Filter by country, status, media, language and start date. Preview: evaluate live availability and source coverage before customer use.","tags":["facebook"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"pageId","in":"query","required":false,"schema":{"type":"string","pattern":"^[0-9]{1,24}$","example":"367152833370567"},"description":"Facebook Page ID. companyName accepts only a name mapped to a verified Page ID; general company-name search is not available. Supply exactly one of: pageId, companyName."},{"name":"cache_max_age","in":"query","required":false,"schema":{"type":"string","enum":["1d","3d","7d","14d","30d"]},"description":"Maximum acceptable cache age. Valid cache hits cost zero credits."},{"name":"fields","in":"query","required":false,"schema":{"type":"string","example":"items"},"description":"Comma-separated fields or dot paths, including inside arrays such as items.id. Response identity and pagination are retained."},{"name":"trim","in":"query","required":false,"schema":{"type":"boolean","default":false},"description":"Remove null and empty values. Meaningful empty YouTube region-restriction lists are retained."},{"name":"companyName","in":"query","required":false,"schema":{"type":"string","pattern":"^[^\\x00-\\x1f]{2,120}$"},"description":"Alternative to pageId. Supply exactly one identifier."},{"name":"country","in":"query","required":false,"description":"Country code, or ALL (default)","schema":{"type":"string","pattern":"^(ALL|[A-Z]{2})$","example":"GB"}},{"name":"status","in":"query","required":false,"description":"Ad status (default ACTIVE)","schema":{"type":"string","enum":["ALL","ACTIVE","INACTIVE"],"example":"ACTIVE"}},{"name":"media_type","in":"query","required":false,"description":"Media format (default ALL)","schema":{"type":"string","enum":["ALL","IMAGE","VIDEO","MEME","IMAGE_AND_MEME","NONE"],"example":"VIDEO"}},{"name":"language","in":"query","required":false,"description":"Two-letter language code","schema":{"type":"string","pattern":"^[A-Za-z]{2}$","example":"EN"}},{"name":"sort_by","in":"query","required":false,"description":"Sort order (default total_impressions)","schema":{"type":"string","enum":["total_impressions","relevancy_monthly_grouped"],"example":"total_impressions"}},{"name":"start_date","in":"query","required":false,"description":"Earliest ad start date, YYYY-MM-DD","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2026-01-01"}},{"name":"end_date","in":"query","required":false,"description":"Latest ad start date, YYYY-MM-DD","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2026-09-19"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":20,"default":3},"description":"Number of items to return."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string","maxLength":32768},"description":"Opaque pagination value returned as data.pagination.next_cursor. Keep the identifier, filters and limit unchanged."}],"responses":{"200":{"description":"Normalized resource","headers":{"x-request-id":{"schema":{"type":"string"}},"x-data-mode":{"schema":{"type":"string","enum":["live","sandbox"]}},"x-cache":{"schema":{"type":"string","enum":["HIT","MISS"]}},"x-credits-charged":{"schema":{"type":"integer"}},"x-credits-remaining":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"data":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","additionalProperties":true,"properties":{"id":{"type":["string","null"],"description":"Meta Ad Library archive ID, kept as a string."},"ad_archive_id":{"type":["string","null"],"description":"Meta Ad Library archive ID."},"ad_library_url":{"type":["string","null"],"description":"Public Ad Library link for this ad."},"page_id":{"type":["string","null"],"description":"Advertiser Facebook Page ID."},"page_name":{"type":["string","null"],"description":"Advertiser name shown by Meta."},"is_active":{"type":["boolean","null"],"description":"Whether Meta reports this ad as active."},"start_date":{"type":["string","null"],"description":"First delivery date in UTC, when supplied."},"end_date":{"type":["string","null"],"description":"Delivery end date in UTC, when supplied."},"collation_id":{"type":["string","null"],"description":"Meta's identifier grouping related ad variations; not an Ads Manager campaign ID."},"collation_count":{"type":["number","null"],"description":"Number of variations reported for the group."},"publisher_platforms":{"type":["array","null"],"description":"Platforms where the ad is published.","items":{"type":["string","null"],"description":"Meta publisher platform."}},"creative":{"type":["object","null"],"description":"Public ad creative. Media links may expire; unavailable values remain null.","properties":{"body":{"type":["string","null"],"description":"Ad copy as plain text."},"title":{"type":["string","null"],"description":"Creative headline."},"caption":{"type":["string","null"],"description":"Display caption."},"description":{"type":["string","null"],"description":"Link description."},"display_format":{"type":["string","null"],"description":"Meta creative format."},"cta_text":{"type":["string","null"],"description":"Call-to-action label."},"cta_type":{"type":["string","null"],"description":"Call-to-action type."},"destination_url":{"type":["string","null"],"description":"Advertised destination URL."},"images":{"type":["array","null"],"description":"Public image assets.","items":{"type":["object","null"],"description":"Public image assets.","properties":{"url":{"type":["string","null"],"description":"Public image URL; may expire."},"resized_url":{"type":["string","null"],"description":"Resized image URL when supplied."}}}},"videos":{"type":["array","null"],"description":"Public video assets.","items":{"type":["object","null"],"description":"Public video assets.","properties":{"hd_url":{"type":["string","null"],"description":"HD video URL when supplied."},"sd_url":{"type":["string","null"],"description":"SD video URL when supplied."},"preview_url":{"type":["string","null"],"description":"Video preview image URL."}}}},"cards":{"type":["array","null"],"description":"Ordered carousel cards.","items":{"type":["object","null"],"description":"Ordered carousel cards.","properties":{"title":{"type":["string","null"],"description":"Card headline."},"body":{"type":["string","null"],"description":"Card text."},"destination_url":{"type":["string","null"],"description":"Card destination."},"image_url":{"type":["string","null"],"description":"Card image."},"video_hd_url":{"type":["string","null"],"description":"Card HD video."},"video_sd_url":{"type":["string","null"],"description":"Card SD video."},"cta_text":{"type":["string","null"],"description":"Card call to action."}}}}}}}}}}}}}]}}}},"400":{"$ref":"#/components/responses/InvalidInput"},"401":{"$ref":"#/components/responses/InvalidApiKey"},"402":{"$ref":"#/components/responses/InsufficientCredits"},"403":{"$ref":"#/components/responses/SourceRestricted"},"404":{"$ref":"#/components/responses/ResourceNotFound"},"408":{"$ref":"#/components/responses/SourceTimeout"},"422":{"$ref":"#/components/responses/SourceResponseChanged"},"429":{"$ref":"#/components/responses/TemporaryCapacity"},"501":{"$ref":"#/components/responses/SourceNotImplemented"},"503":{"$ref":"#/components/responses/SourceUnavailable"}},"x-availability":"preview","x-identifier-one-of":["pageId","companyName"],"x-credits":1,"x-source-access":"public_json","x-preview":true,"x-codeSamples":[{"lang":"curl","source":"curl 'https://api.socialdatakit.com/v1/facebook/adLibrary/company/ads?pageId=367152833370567' \\\n  -H 'x-api-key: YOUR_API_KEY'"},{"lang":"javascript","source":"const response = await fetch(\"https://api.socialdatakit.com/v1/facebook/adLibrary/company/ads?pageId=367152833370567\", {\n  headers: { \"x-api-key\": process.env.SOCIALDATAKIT_API_KEY }\n});\nif (!response.ok) throw new Error(await response.text());\nconst result = await response.json();"},{"lang":"python","source":"import os\nimport requests\n\nresponse = requests.get(\n    \"https://api.socialdatakit.com/v1/facebook/adLibrary/company/ads?pageId=367152833370567\",\n    headers={\"x-api-key\": os.environ[\"SOCIALDATAKIT_API_KEY\"]},\n    timeout=30,\n)\nresponse.raise_for_status()\nresult = response.json()"}],"x-response-fields":{"id":{"type":"string","description":"Meta Ad Library archive ID, kept as a string."},"ad_archive_id":{"type":"string","description":"Meta Ad Library archive ID."},"ad_library_url":{"type":"string","description":"Public Ad Library link for this ad."},"page_id":{"type":"string","description":"Advertiser Facebook Page ID."},"page_name":{"type":"string","description":"Advertiser name shown by Meta."},"is_active":{"type":"boolean","description":"Whether Meta reports this ad as active."},"start_date":{"type":"string","description":"First delivery date in UTC, when supplied."},"end_date":{"type":"string","description":"Delivery end date in UTC, when supplied."},"collation_id":{"type":"string","description":"Meta's identifier grouping related ad variations; not an Ads Manager campaign ID."},"collation_count":{"type":"number","description":"Number of variations reported for the group."},"publisher_platforms":{"type":"array","description":"Platforms where the ad is published.","items":{"type":"string","description":"Meta publisher platform."}},"creative":{"type":"object","description":"Public ad creative. Media links may expire; unavailable values remain null.","properties":{"body":{"type":"string","description":"Ad copy as plain text."},"title":{"type":"string","description":"Creative headline."},"caption":{"type":"string","description":"Display caption."},"description":{"type":"string","description":"Link description."},"display_format":{"type":"string","description":"Meta creative format."},"cta_text":{"type":"string","description":"Call-to-action label."},"cta_type":{"type":"string","description":"Call-to-action type."},"destination_url":{"type":"string","description":"Advertised destination URL."},"images":{"type":"array","description":"Public image assets.","items":{"type":"object","description":"Public image assets.","properties":{"url":{"type":"string","description":"Public image URL; may expire."},"resized_url":{"type":"string","description":"Resized image URL when supplied."}}}},"videos":{"type":"array","description":"Public video assets.","items":{"type":"object","description":"Public video assets.","properties":{"hd_url":{"type":"string","description":"HD video URL when supplied."},"sd_url":{"type":"string","description":"SD video URL when supplied."},"preview_url":{"type":"string","description":"Video preview image URL."}}}},"cards":{"type":"array","description":"Ordered carousel cards.","items":{"type":"object","description":"Ordered carousel cards.","properties":{"title":{"type":"string","description":"Card headline."},"body":{"type":"string","description":"Card text."},"destination_url":{"type":"string","description":"Card destination."},"image_url":{"type":"string","description":"Card image."},"video_hd_url":{"type":"string","description":"Card HD video."},"video_sd_url":{"type":"string","description":"Card SD video."},"cta_text":{"type":"string","description":"Card call to action."}}}}}}}},"post":{"operationId":"facebook_adLibrary_company_ads_post","summary":"Meta company ads","description":"Preview contract for a company's public Meta Ad Library ads, creative assets, delivery dates and publisher platforms. Live access is pending source validation. Filter by country, status, media, language and start date. Preview: evaluate live availability and source coverage before customer use. Send the same parameters as JSON, especially for long cursors. Maximum body size: 64 KiB. Do not mix query parameters with a JSON body.","tags":["facebook"],"security":[{"ApiKeyAuth":[]}],"responses":{"200":{"description":"Normalized resource","headers":{"x-request-id":{"schema":{"type":"string"}},"x-data-mode":{"schema":{"type":"string","enum":["live","sandbox"]}},"x-cache":{"schema":{"type":"string","enum":["HIT","MISS"]}},"x-credits-charged":{"schema":{"type":"integer"}},"x-credits-remaining":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"data":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","additionalProperties":true,"properties":{"id":{"type":["string","null"],"description":"Meta Ad Library archive ID, kept as a string."},"ad_archive_id":{"type":["string","null"],"description":"Meta Ad Library archive ID."},"ad_library_url":{"type":["string","null"],"description":"Public Ad Library link for this ad."},"page_id":{"type":["string","null"],"description":"Advertiser Facebook Page ID."},"page_name":{"type":["string","null"],"description":"Advertiser name shown by Meta."},"is_active":{"type":["boolean","null"],"description":"Whether Meta reports this ad as active."},"start_date":{"type":["string","null"],"description":"First delivery date in UTC, when supplied."},"end_date":{"type":["string","null"],"description":"Delivery end date in UTC, when supplied."},"collation_id":{"type":["string","null"],"description":"Meta's identifier grouping related ad variations; not an Ads Manager campaign ID."},"collation_count":{"type":["number","null"],"description":"Number of variations reported for the group."},"publisher_platforms":{"type":["array","null"],"description":"Platforms where the ad is published.","items":{"type":["string","null"],"description":"Meta publisher platform."}},"creative":{"type":["object","null"],"description":"Public ad creative. Media links may expire; unavailable values remain null.","properties":{"body":{"type":["string","null"],"description":"Ad copy as plain text."},"title":{"type":["string","null"],"description":"Creative headline."},"caption":{"type":["string","null"],"description":"Display caption."},"description":{"type":["string","null"],"description":"Link description."},"display_format":{"type":["string","null"],"description":"Meta creative format."},"cta_text":{"type":["string","null"],"description":"Call-to-action label."},"cta_type":{"type":["string","null"],"description":"Call-to-action type."},"destination_url":{"type":["string","null"],"description":"Advertised destination URL."},"images":{"type":["array","null"],"description":"Public image assets.","items":{"type":["object","null"],"description":"Public image assets.","properties":{"url":{"type":["string","null"],"description":"Public image URL; may expire."},"resized_url":{"type":["string","null"],"description":"Resized image URL when supplied."}}}},"videos":{"type":["array","null"],"description":"Public video assets.","items":{"type":["object","null"],"description":"Public video assets.","properties":{"hd_url":{"type":["string","null"],"description":"HD video URL when supplied."},"sd_url":{"type":["string","null"],"description":"SD video URL when supplied."},"preview_url":{"type":["string","null"],"description":"Video preview image URL."}}}},"cards":{"type":["array","null"],"description":"Ordered carousel cards.","items":{"type":["object","null"],"description":"Ordered carousel cards.","properties":{"title":{"type":["string","null"],"description":"Card headline."},"body":{"type":["string","null"],"description":"Card text."},"destination_url":{"type":["string","null"],"description":"Card destination."},"image_url":{"type":["string","null"],"description":"Card image."},"video_hd_url":{"type":["string","null"],"description":"Card HD video."},"video_sd_url":{"type":["string","null"],"description":"Card SD video."},"cta_text":{"type":["string","null"],"description":"Card call to action."}}}}}}}}}}}}}]}}}},"400":{"$ref":"#/components/responses/InvalidInput"},"401":{"$ref":"#/components/responses/InvalidApiKey"},"402":{"$ref":"#/components/responses/InsufficientCredits"},"403":{"$ref":"#/components/responses/SourceRestricted"},"404":{"$ref":"#/components/responses/ResourceNotFound"},"408":{"$ref":"#/components/responses/SourceTimeout"},"413":{"description":"The JSON body exceeds 64 KiB.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"code":"INVALID_INPUT","message":"The JSON body exceeds 64 KiB.","request_id":"req_example"}}}}},"415":{"description":"Content-Type must be application/json.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"code":"INVALID_INPUT","message":"Content-Type must be application/json.","request_id":"req_example"}}}}},"422":{"$ref":"#/components/responses/SourceResponseChanged"},"429":{"$ref":"#/components/responses/TemporaryCapacity"},"501":{"$ref":"#/components/responses/SourceNotImplemented"},"503":{"$ref":"#/components/responses/SourceUnavailable"}},"x-availability":"preview","x-identifier-one-of":["pageId","companyName"],"x-credits":1,"x-source-access":"public_json","x-preview":true,"x-codeSamples":[{"lang":"curl","source":"curl 'https://api.socialdatakit.com/v1/facebook/adLibrary/company/ads' \\\n  -H 'x-api-key: YOUR_API_KEY' \\\n  -H 'Content-Type: application/json' \\\n  --data '{\"pageId\":\"367152833370567\"}'"},{"lang":"javascript","source":"const response = await fetch(\"https://api.socialdatakit.com/v1/facebook/adLibrary/company/ads\", {\n  method: \"POST\",\n  headers: { \"x-api-key\": process.env.SOCIALDATAKIT_API_KEY, \"Content-Type\": \"application/json\" },\n  body: JSON.stringify({\"pageId\":\"367152833370567\"})\n});\nif (!response.ok) throw new Error(await response.text());\nconst result = await response.json();"},{"lang":"python","source":"import os\nimport requests\n\nresponse = requests.post(\n    \"https://api.socialdatakit.com/v1/facebook/adLibrary/company/ads\",\n    headers={\"x-api-key\": os.environ[\"SOCIALDATAKIT_API_KEY\"]},\n    json={\"pageId\":\"367152833370567\"},\n    timeout=40,\n)\nresponse.raise_for_status()\nresult = response.json()"}],"x-response-fields":{"id":{"type":"string","description":"Meta Ad Library archive ID, kept as a string."},"ad_archive_id":{"type":"string","description":"Meta Ad Library archive ID."},"ad_library_url":{"type":"string","description":"Public Ad Library link for this ad."},"page_id":{"type":"string","description":"Advertiser Facebook Page ID."},"page_name":{"type":"string","description":"Advertiser name shown by Meta."},"is_active":{"type":"boolean","description":"Whether Meta reports this ad as active."},"start_date":{"type":"string","description":"First delivery date in UTC, when supplied."},"end_date":{"type":"string","description":"Delivery end date in UTC, when supplied."},"collation_id":{"type":"string","description":"Meta's identifier grouping related ad variations; not an Ads Manager campaign ID."},"collation_count":{"type":"number","description":"Number of variations reported for the group."},"publisher_platforms":{"type":"array","description":"Platforms where the ad is published.","items":{"type":"string","description":"Meta publisher platform."}},"creative":{"type":"object","description":"Public ad creative. Media links may expire; unavailable values remain null.","properties":{"body":{"type":"string","description":"Ad copy as plain text."},"title":{"type":"string","description":"Creative headline."},"caption":{"type":"string","description":"Display caption."},"description":{"type":"string","description":"Link description."},"display_format":{"type":"string","description":"Meta creative format."},"cta_text":{"type":"string","description":"Call-to-action label."},"cta_type":{"type":"string","description":"Call-to-action type."},"destination_url":{"type":"string","description":"Advertised destination URL."},"images":{"type":"array","description":"Public image assets.","items":{"type":"object","description":"Public image assets.","properties":{"url":{"type":"string","description":"Public image URL; may expire."},"resized_url":{"type":"string","description":"Resized image URL when supplied."}}}},"videos":{"type":"array","description":"Public video assets.","items":{"type":"object","description":"Public video assets.","properties":{"hd_url":{"type":"string","description":"HD video URL when supplied."},"sd_url":{"type":"string","description":"SD video URL when supplied."},"preview_url":{"type":"string","description":"Video preview image URL."}}}},"cards":{"type":"array","description":"Ordered carousel cards.","items":{"type":"object","description":"Ordered carousel cards.","properties":{"title":{"type":"string","description":"Card headline."},"body":{"type":"string","description":"Card text."},"destination_url":{"type":"string","description":"Card destination."},"image_url":{"type":"string","description":"Card image."},"video_hd_url":{"type":"string","description":"Card HD video."},"video_sd_url":{"type":"string","description":"Card SD video."},"cta_text":{"type":"string","description":"Card call to action."}}}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"pageId":{"type":"string","pattern":"^[0-9]{1,24}$","example":"367152833370567"},"cache_max_age":{"type":"string","enum":["1d","3d","7d","14d","30d"]},"fields":{"type":"string","example":"items"},"trim":{"oneOf":[{"type":"boolean","default":false},{"type":"string","enum":["true","false"]}]},"companyName":{"type":"string","pattern":"^[^\\x00-\\x1f]{2,120}$"},"country":{"type":"string","pattern":"^(ALL|[A-Z]{2})$","example":"GB"},"status":{"type":"string","enum":["ALL","ACTIVE","INACTIVE"],"example":"ACTIVE"},"media_type":{"type":"string","enum":["ALL","IMAGE","VIDEO","MEME","IMAGE_AND_MEME","NONE"],"example":"VIDEO"},"language":{"type":"string","pattern":"^[A-Za-z]{2}$","example":"EN"},"sort_by":{"type":"string","enum":["total_impressions","relevancy_monthly_grouped"],"example":"total_impressions"},"start_date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2026-01-01"},"end_date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2026-09-19"},"limit":{"oneOf":[{"type":"integer","minimum":1,"maximum":20,"default":3},{"type":"string","pattern":"^(?:[1-9]|1[0-9]|20)$"}]},"cursor":{"type":"string","maxLength":32768}},"oneOf":[{"required":["pageId"]},{"required":["companyName"]}]}}}}}},"/v1/workflows/profile":{"get":{"operationId":"workflow_profile","summary":"Get spreadsheet-ready public profile metrics","tags":["workflows"],"description":"Accepts Instagram profile, TikTok profile and YouTube channel URLs. Channels use the preview collector. Uses one credit for a successful fresh live result; valid cache hits and development samples are free. data_mode identifies samples. Missing counters are null; rounded_fields names approximate counters.","security":[{"ApiKeyAuth":[]}],"x-credits":1,"parameters":[{"name":"url","in":"query","required":true,"schema":{"type":"string","format":"uri"}},{"name":"cache_max_age","in":"query","schema":{"type":"string","enum":["1d","3d","7d","14d","30d"]}}],"responses":{"200":{"description":"Flat data fields plus credit metadata","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"object","properties":{"url":{"type":"string"},"platform":{"type":"string"},"identifier":{"type":"string"},"display_name":{"type":["string","null"]},"entity_id":{"type":["string","null"]},"followers":{"type":["number","null"]},"following":{"type":["number","null"]},"posts":{"type":["number","null"]},"likes":{"type":["number","null"]},"total_views":{"type":["number","null"]},"observed_at":{"type":"string","format":"date-time"},"rounded_fields":{"type":"string"},"status":{"type":"string"},"error_code":{"type":"string"},"data_mode":{"type":"string","enum":["live","sample"]}}},"meta":{"$ref":"#/components/schemas/SuccessEnvelope/properties/meta"}}}}}},"400":{"$ref":"#/components/responses/InvalidInput"},"401":{"$ref":"#/components/responses/InvalidApiKey"},"402":{"$ref":"#/components/responses/InsufficientCredits"},"429":{"$ref":"#/components/responses/TemporaryCapacity"},"503":{"$ref":"#/components/responses/SourceUnavailable"}}}},"/v1/workflows/campaign-report":{"get":{"operationId":"workflow_campaign_report","summary":"Read a campaign report","tags":["workflows"],"security":[{"ApiKeyAuth":[]}],"x-credits":0,"description":"Production API key and active paid campaign access required. Returns current report or an immutable saved weekly report. Totals group by platform and profiles/posts; available and missing counts identify incomplete coverage. Totals are not unique reach or sales attribution.","parameters":[{"name":"id","in":"query","required":true,"schema":{"type":"string"}},{"name":"report_id","in":"query","schema":{"type":"string"}},{"name":"format","in":"query","schema":{"type":"string","enum":["json","csv"]}}],"responses":{"200":{"description":"Campaign rows, totals, dates and coverage","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","additionalProperties":true},"meta":{"type":"object","properties":{"credits_charged":{"type":"integer","const":0}}}}}},"text/csv":{"schema":{"type":"string"}}}},"401":{"$ref":"#/components/responses/InvalidApiKey"},"403":{"description":"Paid access or production key required"},"404":{"description":"Report missing, in another workspace or outside retained history"},"429":{"$ref":"#/components/responses/TemporaryCapacity"}}}},"/v1/credit/balance":{"get":{"operationId":"credit_balance","summary":"Get credit balance","tags":["account"],"description":"Check the calling key’s workspace balance without spending credits. The bundled demo key returns null and plan=playground instead of environment.","security":[{"ApiKeyAuth":[]}],"x-credits":0,"responses":{"200":{"description":"Workspace balance","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"object","required":["credits_remaining","sandbox"],"properties":{"credits_remaining":{"type":["integer","null"]},"sandbox":{"type":"boolean"},"environment":{"type":"string"},"plan":{"type":"string","enum":["playground"]}}},"meta":{"type":"object","required":["request_id"],"properties":{"request_id":{"type":"string"}}}}}}}},"401":{"$ref":"#/components/responses/InvalidApiKey"}}}}},"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"x-api-key"}},"schemas":{"SuccessEnvelope":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"object","additionalProperties":true,"properties":{"coverage":{"type":"object","required":["contract_version","partial","unavailable_fields"],"properties":{"contract_version":{"type":"string"},"partial":{"type":"boolean","description":"Some resource fields are unavailable, inapplicable or have changed type; does not indicate pagination completeness."},"unavailable_fields":{"type":"array","items":{"type":"string"},"description":"Paths relative to data before fields/trim shaping. Unknown values are null, never invented zero or false."}}}}},"meta":{"type":"object","required":["cached","credits_charged","credits_remaining","endpoint","request_id","sandbox"],"properties":{"cached":{"type":"boolean"},"credits_charged":{"type":"integer"},"credits_remaining":{"type":["integer","null"],"description":"Current workspace balance. Null when the bundled demo key bypasses credit charging."},"endpoint":{"type":"string"},"request_id":{"type":"string","format":"uuid"},"sandbox":{"type":"boolean","description":"True when the deterministic test adapter served the request; false for a live public-source collector."}}}}},"ErrorEnvelope":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","request_id"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"request_id":{"type":"string"}}}}}},"responses":{"InvalidInput":{"description":"A required resource parameter or option is malformed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"code":"INVALID_INPUT","message":"A required resource parameter or option is malformed.","request_id":"req_example"}}}}},"InvalidApiKey":{"description":"The API key is missing, invalid, or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"code":"INVALID_API_KEY","message":"The API key is missing, invalid, or revoked.","request_id":"req_example"}}}}},"InsufficientCredits":{"description":"The workspace needs more credits.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"code":"INSUFFICIENT_CREDITS","message":"The workspace needs more credits.","request_id":"req_example"}}}}},"ResourceNotFound":{"description":"The requested endpoint or public resource was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"code":"RESOURCE_NOT_FOUND","message":"The requested endpoint or public resource was not found.","request_id":"req_example"}}}}},"SourceRestricted":{"description":"The public source restricts this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"code":"SOURCE_RESTRICTED","message":"The public source restricts this resource.","request_id":"req_example"}}}}},"SourceTimeout":{"description":"The public source exceeded the collector timeout.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"code":"SOURCE_TIMEOUT","message":"The public source exceeded the collector timeout.","request_id":"req_example"}}}}},"SourceResponseChanged":{"description":"The source response could not be normalized safely.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"code":"SOURCE_RESPONSE_CHANGED","message":"The source response could not be normalized safely.","request_id":"req_example"}}}}},"TemporaryCapacity":{"description":"The collector or source is temporarily rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"code":"TEMPORARY_CAPACITY","message":"The collector or source is temporarily rate limited.","request_id":"req_example"}}}}},"SourceNotConfigured":{"description":"The operator must configure the required platform API access.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"code":"SOURCE_NOT_CONFIGURED","message":"The operator must configure the required platform API access.","request_id":"req_example"}}}}},"SourceNotImplemented":{"description":"This planned endpoint has no collector. No credits are charged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"code":"SOURCE_NOT_IMPLEMENTED","message":"This planned endpoint has no collector. No credits are charged.","request_id":"req_example"}}}}},"SourceUnavailable":{"description":"The upstream source is temporarily unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"code":"SOURCE_UNAVAILABLE","message":"The upstream source is temporarily unavailable.","request_id":"req_example"}}}}}}}}