{ "openapi": "3.1.0", "info": { "title": "LurkAPI", "version": "1.0.0", "description": "Public social media data as clean JSON: one GET request per call, authenticated with the `x-api-key` header. Docs: https://lurkapi.com/docs" }, "servers": [ { "url": "https://api.lurkapi.com" } ], "security": [ { "apiKey": [] } ], "tags": [ { "name": "Facebook", "description": "Ads running on Facebook and Instagram, from Meta's Ad Library: copy, creative, landing page, dates and platforms." }, { "name": "Reddit", "description": "Posts, comments, search and community stats from any public subreddit." }, { "name": "YouTube", "description": "Videos, Shorts, transcripts, comments and channel stats from any public YouTube channel." }, { "name": "TikTok", "description": "Profiles, videos, transcripts and comments from any public TikTok account." }, { "name": "Google", "description": "Ads running on Google Search, YouTube, Maps, Play and Shopping, from Google's Ads Transparency Center." }, { "name": "Bluesky", "description": "Profiles, posts and full threads from any public Bluesky account." }, { "name": "Snapchat", "description": "Public profiles, live stories, highlights and Spotlight videos from Snapchat." }, { "name": "Truth Social", "description": "Profiles and posts from public Truth Social accounts." }, { "name": "Telegram", "description": "Public channel profiles, their posts and single posts, with views, media and reactions." }, { "name": "X (Twitter)", "description": "Tweets, profiles and recent posts from any public X account." }, { "name": "Threads", "description": "Public profiles, paginated account posts and individual Threads posts." }, { "name": "Instagram", "description": "Public profiles, posts, reels and comments with media and engagement counts." }, { "name": "LinkedIn", "description": "Public company pages, their latest updates and ads from LinkedIn's Ad Library." }, { "name": "Link-in-bio", "description": "Linktree profiles, their public links and social destinations." }, { "name": "Account", "description": "Your LurkAPI credit balance." } ], "paths": { "/v1/facebook/adLibrary/search/ads": { "get": { "operationId": "facebook_search_ads", "tags": [ "Facebook" ], "summary": "Search Ad Library ads", "description": "Find ads in Meta's Ad Library by keyword, with their copy, media, landing page and run dates.\n\nUse it to see how a whole market advertises: the angles, offers and formats that keep running. For one advertiser's ads, use company ads (facebook_company_ads) instead. `status` defaults to all; pass `active` for ads running now.\n\nKeyword search across every ad in the Meta Ad Library, the same as typing into facebook.com/ads/library. Filter by country, status, media type, language and date range. The default sort puts the most-seen ads first.\n\n**Pagination.** The first page returns up to 30 ads plus `searchResultsCount`. Pass `cursor` back (with the same filters) for the next page: cursor pages return up to 10 ads, which is Facebook's own page size, and `searchResultsCount` is null. `cursor` is null on the last page.\n\nCost: 1 credit.", "externalDocs": { "url": "https://lurkapi.com/docs/facebook/search-ads" }, "x-credits": 1, "parameters": [ { "name": "query", "in": "query", "required": true, "description": "Keywords to search ad text for, e.g. `running shoes`.", "schema": { "type": "string", "minLength": 1, "description": "Keywords to search ad text for, e.g. `running shoes`." }, "example": "running shoes" }, { "name": "search_type", "in": "query", "required": false, "description": "`keyword_unordered` matches all words in any order; `keyword_exact_phrase` matches the phrase as typed.", "schema": { "description": "`keyword_unordered` matches all words in any order; `keyword_exact_phrase` matches the phrase as typed.", "default": "keyword_unordered", "type": "string", "enum": [ "keyword_unordered", "keyword_exact_phrase" ] } }, { "name": "country", "in": "query", "required": false, "description": "Where the ad ran: a 2-letter ISO country code (US, GB, DE…) or ALL. One country per request.", "schema": { "description": "Where the ad ran: a 2-letter ISO country code (US, GB, DE…) or ALL. One country per request.", "default": "ALL", "type": "string", "pattern": "^(ALL|[A-Z]{2})$" }, "example": "US" }, { "name": "status", "in": "query", "required": false, "description": "Only ads that are running now (active), only stopped ads (inactive), or both (all).", "schema": { "description": "Only ads that are running now (active), only stopped ads (inactive), or both (all).", "default": "all", "type": "string", "enum": [ "all", "active", "inactive" ] }, "example": "active" }, { "name": "media_type", "in": "query", "required": false, "description": "Creative format. `meme` is Facebook's name for image + text; `none` means text-only.", "schema": { "description": "Creative format. `meme` is Facebook's name for image + text; `none` means text-only.", "default": "all", "type": "string", "enum": [ "all", "image", "video", "meme", "image_and_meme", "none" ] } }, { "name": "ad_type", "in": "query", "required": false, "description": "Ad category. Political ads also carry spend and impressions ranges.", "schema": { "description": "Ad category. Political ads also carry spend and impressions ranges.", "default": "ALL", "type": "string", "enum": [ "ALL", "POLITICAL_AND_ISSUE_ADS", "EMPLOYMENT_ADS", "HOUSING_ADS", "CREDIT_ADS" ] } }, { "name": "language", "in": "query", "required": false, "description": "Language of the ad text as an ISO 639-1 code, e.g. `en` or `es`.", "schema": { "description": "Language of the ad text as an ISO 639-1 code, e.g. `en` or `es`.", "type": "string", "pattern": "^([a-z]{2}|cmn|yue)$" } }, { "name": "sort_by", "in": "query", "required": false, "description": "`total_impressions`: most-seen ads first. `relevancy_monthly_grouped`: most recent first.", "schema": { "description": "`total_impressions`: most-seen ads first. `relevancy_monthly_grouped`: most recent first.", "default": "total_impressions", "type": "string", "enum": [ "total_impressions", "relevancy_monthly_grouped" ] } }, { "name": "start_date", "in": "query", "required": false, "description": "Only ads shown on or after this date (YYYY-MM-DD). The ad itself may have launched earlier.", "schema": { "description": "Only ads shown on or after this date (YYYY-MM-DD). The ad itself may have launched earlier.", "type": "string" } }, { "name": "end_date", "in": "query", "required": false, "description": "Only ads shown on or before this date (YYYY-MM-DD).", "schema": { "description": "Only ads shown on or before this date (YYYY-MM-DD).", "type": "string" } }, { "name": "cursor", "in": "query", "required": false, "description": "The `cursor` from the previous response, to get the next page. Keep every other param the same.", "schema": { "description": "The `cursor` from the previous response, to get the next page. Keep every other param the same.", "type": "string" } }, { "name": "trim", "in": "query", "required": false, "description": "`true` drops image and video URLs (inside `snapshot.cards` too) for a much smaller response. All text is kept.", "schema": { "description": "`true` drops image and video URLs (inside `snapshot.cards` too) for a much smaller response. All text is kept.", "default": "false", "type": "string", "enum": [ "true", "false" ] } } ], "responses": { "200": { "description": "Find ads in Meta's Ad Library by keyword, with their copy, media, landing page and run dates.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "const": true, "description": "Always true here; errors have `success: false`." }, "credits_remaining": { "type": "number", "description": "Your balance after this call. On anonymous playground calls: free tries left today." }, "credits_charged": { "type": "number", "description": "Credits this call cost; 0 on free endpoints. On anonymous playground calls: tries used (1)." }, "searchResults": { "type": "array", "items": { "type": "object", "properties": { "ad_archive_id": { "description": "The Ad Library id. Pass it as `id` to the ad details endpoint.", "type": [ "string", "null" ] }, "ad_id": { "description": "Meta's internal ad id. null in every response we've seen; use the Ad Library id.", "type": [ "string", "null" ] }, "page_id": { "description": "The advertiser's Facebook page id. Pass it as `pageId` to the company ads endpoint.", "type": [ "string", "null" ] }, "page_name": { "description": "The advertiser's page name.", "type": [ "string", "null" ] }, "is_active": { "type": "boolean", "description": "Whether the ad is running now." }, "start_date": { "description": "When the ad started running, Unix seconds (UTC).", "type": [ "number", "null" ] }, "end_date": { "description": "When the ad stopped, or its latest delivery date if still running, Unix seconds (UTC).", "type": [ "number", "null" ] }, "start_date_string": { "description": "The same date as ISO 8601 text when Facebook includes it; often null, so prefer the Unix seconds field.", "type": [ "string", "null" ] }, "end_date_string": { "description": "The same date as ISO 8601 text when Facebook includes it; often null, so prefer the Unix seconds field.", "type": [ "string", "null" ] }, "total_active_time": { "description": "Seconds the ad has run, when Facebook reports it; usually null.", "type": [ "number", "null" ] }, "publisher_platform": { "type": "array", "items": { "type": "string" }, "description": "Where it ran, uppercase: FACEBOOK, INSTAGRAM, AUDIENCE_NETWORK, MESSENGER, THREADS." }, "collation_count": { "description": "How many near-identical versions are grouped under this ad. A high count means the advertiser is scaling it; null for a single version.", "type": [ "number", "null" ] }, "collation_id": { "description": "Id shared by the grouped versions of this ad; null for a single version.", "type": [ "string", "null" ] }, "snapshot": { "type": "object", "properties": { "page_id": { "description": "The advertiser's page id (same as the ad's).", "type": [ "string", "null" ] }, "page_name": { "description": "The advertiser's page name as shown on the ad.", "type": [ "string", "null" ] }, "page_profile_uri": { "description": "The advertiser's Facebook page URL.", "type": [ "string", "null" ] }, "page_profile_picture_url": { "description": "The advertiser's profile picture, 60×60 px.", "type": [ "string", "null" ] }, "page_like_count": { "description": "Followers of the advertiser's page.", "type": [ "number", "null" ] }, "page_categories": { "type": "array", "items": { "type": "string" }, "description": "Page categories, e.g. [\"Outdoor & Sporting Goods Company\"]." }, "page_is_deleted": { "type": "boolean", "description": "Whether the advertiser's page has been deleted." }, "title": { "description": "Headline under the creative; null when there is none.", "type": [ "string", "null" ] }, "caption": { "description": "Display link under the creative, usually the domain (e.g. HOKA.com).", "type": [ "string", "null" ] }, "link_url": { "description": "Landing page the ad sends people to, UTM tags included.", "type": [ "string", "null" ] }, "link_description": { "description": "Text under the headline; null when there is none.", "type": [ "string", "null" ] }, "cta_text": { "description": "Button label, e.g. \"Shop now\".", "type": [ "string", "null" ] }, "cta_type": { "description": "Button type, e.g. SHOP_NOW, LEARN_MORE, NO_BUTTON.", "type": [ "string", "null" ] }, "display_format": { "description": "Creative format, e.g. IMAGE, VIDEO, DCO (dynamic creative), DPA (dynamic product ad) or MULTI_IMAGES. For DCO and DPA ads the creative is in `cards`.", "type": [ "string", "null" ] }, "images": { "type": "array", "items": { "type": "object", "properties": { "original_image_url": { "description": "Full-size image URL. Facebook CDN links expire after a few days; download what you need.", "type": [ "string", "null" ] }, "resized_image_url": { "description": "600 px image URL, good for thumbnails.", "type": [ "string", "null" ] }, "watermarked_resized_image_url": { "type": "string", "description": "Watermarked copy; empty or null in every response we've seen." }, "image_crops": { "type": "array", "items": {}, "description": "Facebook internal field; an empty array in every response we've seen. Crop hints for the image." } }, "required": [ "original_image_url", "resized_image_url", "watermarked_resized_image_url", "image_crops" ], "additionalProperties": false }, "description": "Image creatives. Empty for video and card-based ads, and with trim=true." }, "videos": { "type": "array", "items": { "type": "object", "properties": { "video_hd_url": { "description": "HD video file URL; null if Facebook has no HD version.", "type": [ "string", "null" ] }, "video_sd_url": { "description": "SD video file URL.", "type": [ "string", "null" ] }, "video_preview_image_url": { "description": "Poster frame (still image) URL.", "type": [ "string", "null" ] }, "watermarked_video_hd_url": { "description": "Watermarked copy; empty or null in every response we've seen.", "type": [ "string", "null" ] }, "watermarked_video_sd_url": { "description": "Watermarked copy; empty or null in every response we've seen.", "type": [ "string", "null" ] } }, "required": [ "video_hd_url", "video_sd_url", "video_preview_image_url", "watermarked_video_hd_url", "watermarked_video_sd_url" ], "additionalProperties": false }, "description": "Video creatives. Empty for image and card-based ads, and with trim=true." }, "cards": { "type": "array", "items": { "type": "object", "properties": { "title": { "description": "This version's headline.", "type": [ "string", "null" ] }, "body": { "description": "This version's primary text.", "type": [ "string", "null" ] }, "caption": { "description": "This version's display link, usually the domain.", "type": [ "string", "null" ] }, "cta_text": { "description": "Button label, e.g. \"Shop now\".", "type": [ "string", "null" ] }, "cta_type": { "description": "Button type, e.g. SHOP_NOW, LEARN_MORE.", "type": [ "string", "null" ] }, "link_url": { "description": "This version's landing page URL.", "type": [ "string", "null" ] }, "link_description": { "description": "Text under the headline; null when there is none.", "type": [ "string", "null" ] }, "original_image_url": { "description": "Full-size image URL; null for video versions.", "type": [ "string", "null" ] }, "resized_image_url": { "description": "600 px image URL; null for video versions.", "type": [ "string", "null" ] }, "watermarked_resized_image_url": { "type": "string", "description": "Watermarked copy; empty or null in every response we've seen." }, "image_crops": { "type": "array", "items": {}, "description": "Facebook internal field; an empty array in every response we've seen. Crop hints for the image." }, "video_hd_url": { "description": "HD video file URL; null for image versions.", "type": [ "string", "null" ] }, "video_sd_url": { "description": "SD video file URL; null for image versions.", "type": [ "string", "null" ] }, "video_preview_image_url": { "description": "Poster frame URL; null for image versions.", "type": [ "string", "null" ] }, "watermarked_video_hd_url": { "description": "Watermarked copy; empty or null in every response we've seen.", "type": [ "string", "null" ] }, "watermarked_video_sd_url": { "description": "Watermarked copy; empty or null in every response we've seen.", "type": [ "string", "null" ] } }, "required": [ "title", "body", "caption", "cta_text", "cta_type", "link_url", "link_description", "original_image_url", "resized_image_url", "watermarked_resized_image_url", "image_crops", "video_hd_url", "video_sd_url", "video_preview_image_url", "watermarked_video_hd_url", "watermarked_video_sd_url" ], "additionalProperties": false }, "description": "Carousel, dynamic-creative and product versions, each with its own copy and media. With trim=true the text stays and media URLs are null." }, "byline": { "description": "Line under the page name, when shown; null or empty in most ads.", "type": [ "string", "null" ] }, "disclaimer_label": { "description": "\"Paid for by\" line on political and issue ads; null otherwise.", "type": [ "string", "null" ] }, "country_iso_code": { "description": "Facebook internal field; null in every response we've seen. A country code on some ads.", "type": [ "string", "null" ] }, "is_reshared": { "type": "boolean", "description": "Whether the ad reshares an existing post (see `root_reshared_post`)." }, "root_reshared_post": { "description": "The original post when `is_reshared` is true; null otherwise." }, "branded_content": { "description": "Paid partnership details when the ad is branded content; null otherwise." }, "additional_info": { "description": "Facebook internal field; null in every response we've seen." }, "brazil_tax_id": { "description": "Advertiser tax id shown on ads under Brazil's rules; null otherwise." }, "ec_certificates": { "type": "array", "items": {}, "description": "Facebook internal field; an empty array in every response we've seen." }, "event": { "description": "Event details on event ads; null otherwise." }, "extra_images": { "type": "array", "items": {}, "description": "More images from dynamic creative; usually empty." }, "extra_links": { "type": "array", "items": {}, "description": "More landing page URLs from dynamic creative; usually empty." }, "extra_texts": { "type": "array", "items": {}, "description": "More text variations from dynamic creative; usually empty." }, "extra_videos": { "type": "array", "items": {}, "description": "More videos from dynamic creative; usually empty." }, "body": { "anyOf": [ { "type": "object", "properties": { "text": { "description": "The ad's primary text.", "type": [ "string", "null" ] } }, "required": [ "text" ], "additionalProperties": false }, { "type": "null" } ], "description": "Primary text as `{ text }`; null when the copy is only in `cards`." } }, "required": [ "page_id", "page_name", "page_profile_uri", "page_profile_picture_url", "page_like_count", "page_categories", "page_is_deleted", "title", "caption", "link_url", "link_description", "cta_text", "cta_type", "display_format", "images", "videos", "cards", "byline", "disclaimer_label", "country_iso_code", "is_reshared", "root_reshared_post", "branded_content", "additional_info", "brazil_tax_id", "ec_certificates", "event", "extra_images", "extra_links", "extra_texts", "extra_videos", "body" ], "additionalProperties": false, "description": "The creative: copy, media, landing page and advertiser details." }, "categories": { "type": "array", "items": { "type": "string" }, "description": "Special ad categories Facebook assigned. [\"UNKNOWN\"] for ordinary ads." }, "targeted_or_reached_countries": { "type": "array", "items": { "type": "string" }, "description": "Countries the ad targeted or reached, when Facebook discloses them; empty in most results." }, "currency": { "type": "string", "description": "Currency code of `spend` (e.g. USD) when spend is reported; an empty string otherwise." }, "spend": { "description": "Spend range, reported for political and issue ads only; null otherwise." }, "impressions_with_index": { "type": "object", "properties": { "impressions_text": { "description": "The range as Facebook shows it; null when not reported.", "type": [ "string", "null" ] }, "impressions_index": { "type": "number", "description": "Facebook's bucket number for the range; -1 when not reported." } }, "required": [ "impressions_text", "impressions_index" ], "additionalProperties": false, "description": "Impressions range, reported for political and issue ads only." }, "reach_estimate": { "description": "Estimated reach, which Facebook reports for some EU-delivered ads; null otherwise." }, "url": { "description": "Ad Library link for this ad. Often null; build it as https://www.facebook.com/ads/library/?id=.", "type": [ "string", "null" ] }, "contains_digital_created_media": { "type": "boolean", "description": "Whether Facebook labels the creative as AI-generated or digitally altered." }, "contains_sensitive_content": { "type": "boolean", "description": "Facebook internal field; false in every response we've seen. Facebook's sensitive-content flag." }, "gated_type": { "type": "string", "description": "Facebook internal field; ELIGIBLE (lowercase in ad details) in every response we've seen." }, "has_user_reported": { "type": "boolean", "description": "Whether the viewing user reported the ad. Always false: we read the Ad Library logged out." }, "hide_data_status": { "type": "string", "description": "Facebook internal field; NONE in every response we've seen." }, "is_aaa_eligible": { "type": "boolean", "description": "Facebook flag, true on a few ads; meaning undocumented. Ad details' `aaa_info` holds the related data when present." }, "menu_items": { "type": "array", "items": {}, "description": "Facebook internal field; an empty array in every response we've seen." }, "page_is_deleted": { "type": "boolean", "description": "Whether the advertiser's page has been deleted." }, "regional_regulation_data": { "type": "object", "properties": { "finserv": { "type": "object", "properties": { "is_deemed_finserv": { "type": "boolean", "description": "Facebook treats the ad as a financial-services ad." }, "is_limited_delivery": { "type": "boolean", "description": "Delivery is limited under financial-services rules." } }, "required": [ "is_deemed_finserv", "is_limited_delivery" ], "additionalProperties": false, "description": "Financial-services ad rules." }, "tw_anti_scam": { "type": "object", "properties": { "is_limited_delivery": { "type": "boolean", "description": "Delivery is limited under Taiwan's anti-scam rules." } }, "required": [ "is_limited_delivery" ], "additionalProperties": false, "description": "Taiwan's anti-scam ad rules." } }, "required": [ "finserv", "tw_anti_scam" ], "additionalProperties": false, "description": "Delivery limits under regional ad rules." }, "report_count": { "description": "Times the ad was reported, when disclosed; null in every response we've seen.", "type": [ "number", "null" ] }, "fev_info": { "description": "Facebook internal field; null in every response we've seen." }, "state_media_run_label": { "description": "Label for ads run by state-controlled media; null otherwise." } }, "required": [ "ad_archive_id", "ad_id", "page_id", "page_name", "is_active", "start_date", "end_date", "start_date_string", "end_date_string", "total_active_time", "publisher_platform", "collation_count", "collation_id", "snapshot", "categories", "targeted_or_reached_countries", "currency", "spend", "impressions_with_index", "reach_estimate", "url", "contains_digital_created_media", "contains_sensitive_content", "gated_type", "has_user_reported", "hide_data_status", "is_aaa_eligible", "menu_items", "page_is_deleted", "regional_regulation_data", "report_count", "fev_info", "state_media_run_label" ], "additionalProperties": false }, "description": "Matching ads." }, "searchResultsCount": { "description": "Total matching ads, as Facebook estimates it. Only on the first page; null on cursor pages.", "type": [ "number", "null" ] }, "cursor": { "description": "Pass as `cursor` for the next page. null on the last page.", "type": [ "string", "null" ] } }, "required": [ "success", "credits_remaining", "credits_charged", "searchResults", "searchResultsCount", "cursor" ], "additionalProperties": false } } } }, "default": { "description": "Error. Not charged, except the endpoint's own 4xx answers such as not_found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/facebook/adLibrary/company/ads": { "get": { "operationId": "facebook_company_ads", "tags": [ "Facebook" ], "summary": "Ad Library ads by company", "description": "Every ad one advertiser is running (or ran) on Facebook and Instagram, from Meta's Ad Library.\n\nUse it to study one competitor's creative, offers and landing pages. Pass `pageId` (exact) or `companyName` (we use the top match and return it as `page_id` and `page_name`). `status` defaults to all; pass `active` for ads running now.\n\n`pageId` comes from search companies (facebook_search_companies) or the `view_all_page_id` in an Ad Library URL. Returns 404 `not_found` if no page matches `companyName`. The list is under `results` (keyword search uses `searchResults`).\n\n**Pagination.** The first page returns up to 30 ads plus `searchResultsCount`. Pass `cursor` back (with the same filters) for the next page: cursor pages return up to 10 ads, which is Facebook's own page size, and `searchResultsCount` is null. `cursor` is null on the last page.\n\nCost: 1 credit.", "externalDocs": { "url": "https://lurkapi.com/docs/facebook/company-ads" }, "x-credits": 1, "parameters": [ { "name": "pageId", "in": "query", "required": false, "description": "The advertiser's Facebook page id, e.g. `15087023444` (Nike). Required unless you pass `companyName`.", "schema": { "description": "The advertiser's Facebook page id, e.g. `15087023444` (Nike). Required unless you pass `companyName`.", "type": "string", "pattern": "^\\d+$" }, "example": "15087023444" }, { "name": "companyName", "in": "query", "required": false, "description": "Advertiser name, e.g. `Nike`. We use the top match from search companies. Ignored when `pageId` is set.", "schema": { "description": "Advertiser name, e.g. `Nike`. We use the top match from search companies. Ignored when `pageId` is set.", "type": "string", "minLength": 1 } }, { "name": "country", "in": "query", "required": false, "description": "Where the ad ran: a 2-letter ISO country code (US, GB, DE…) or ALL. One country per request.", "schema": { "description": "Where the ad ran: a 2-letter ISO country code (US, GB, DE…) or ALL. One country per request.", "default": "ALL", "type": "string", "pattern": "^(ALL|[A-Z]{2})$" } }, { "name": "status", "in": "query", "required": false, "description": "Only ads that are running now (active), only stopped ads (inactive), or both (all).", "schema": { "description": "Only ads that are running now (active), only stopped ads (inactive), or both (all).", "default": "all", "type": "string", "enum": [ "all", "active", "inactive" ] }, "example": "active" }, { "name": "media_type", "in": "query", "required": false, "description": "Creative format. `meme` is Facebook's name for image + text; `none` means text-only.", "schema": { "description": "Creative format. `meme` is Facebook's name for image + text; `none` means text-only.", "default": "all", "type": "string", "enum": [ "all", "image", "video", "meme", "image_and_meme", "none" ] } }, { "name": "ad_type", "in": "query", "required": false, "description": "Ad category. Political ads also carry spend and impressions ranges.", "schema": { "description": "Ad category. Political ads also carry spend and impressions ranges.", "default": "ALL", "type": "string", "enum": [ "ALL", "POLITICAL_AND_ISSUE_ADS", "EMPLOYMENT_ADS", "HOUSING_ADS", "CREDIT_ADS" ] } }, { "name": "language", "in": "query", "required": false, "description": "Language of the ad text as an ISO 639-1 code, e.g. `en` or `es`.", "schema": { "description": "Language of the ad text as an ISO 639-1 code, e.g. `en` or `es`.", "type": "string", "pattern": "^([a-z]{2}|cmn|yue)$" } }, { "name": "sort_by", "in": "query", "required": false, "description": "`total_impressions`: most-seen ads first. `relevancy_monthly_grouped`: most recent first.", "schema": { "description": "`total_impressions`: most-seen ads first. `relevancy_monthly_grouped`: most recent first.", "default": "total_impressions", "type": "string", "enum": [ "total_impressions", "relevancy_monthly_grouped" ] } }, { "name": "start_date", "in": "query", "required": false, "description": "Only ads shown on or after this date (YYYY-MM-DD). The ad itself may have launched earlier.", "schema": { "description": "Only ads shown on or after this date (YYYY-MM-DD). The ad itself may have launched earlier.", "type": "string" } }, { "name": "end_date", "in": "query", "required": false, "description": "Only ads shown on or before this date (YYYY-MM-DD).", "schema": { "description": "Only ads shown on or before this date (YYYY-MM-DD).", "type": "string" } }, { "name": "cursor", "in": "query", "required": false, "description": "The `cursor` from the previous response, to get the next page. Keep every other param the same.", "schema": { "description": "The `cursor` from the previous response, to get the next page. Keep every other param the same.", "type": "string" } }, { "name": "trim", "in": "query", "required": false, "description": "`true` drops image and video URLs (inside `snapshot.cards` too) for a much smaller response. All text is kept.", "schema": { "description": "`true` drops image and video URLs (inside `snapshot.cards` too) for a much smaller response. All text is kept.", "default": "false", "type": "string", "enum": [ "true", "false" ] } } ], "responses": { "200": { "description": "Every ad one advertiser is running (or ran) on Facebook and Instagram, from Meta's Ad Library.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "const": true, "description": "Always true here; errors have `success: false`." }, "credits_remaining": { "type": "number", "description": "Your balance after this call. On anonymous playground calls: free tries left today." }, "credits_charged": { "type": "number", "description": "Credits this call cost; 0 on free endpoints. On anonymous playground calls: tries used (1)." }, "page_id": { "type": "string", "description": "The page these ads are from: `pageId` as given, or the page we matched for `companyName`." }, "page_name": { "description": "That page's name (the matched page for `companyName`, else from the ads); null when there are no ads.", "type": [ "string", "null" ] }, "results": { "type": "array", "items": { "type": "object", "properties": { "ad_archive_id": { "description": "The Ad Library id. Pass it as `id` to the ad details endpoint.", "type": [ "string", "null" ] }, "ad_id": { "description": "Meta's internal ad id. null in every response we've seen; use the Ad Library id.", "type": [ "string", "null" ] }, "page_id": { "description": "The advertiser's Facebook page id. Pass it as `pageId` to the company ads endpoint.", "type": [ "string", "null" ] }, "page_name": { "description": "The advertiser's page name.", "type": [ "string", "null" ] }, "is_active": { "type": "boolean", "description": "Whether the ad is running now." }, "start_date": { "description": "When the ad started running, Unix seconds (UTC).", "type": [ "number", "null" ] }, "end_date": { "description": "When the ad stopped, or its latest delivery date if still running, Unix seconds (UTC).", "type": [ "number", "null" ] }, "start_date_string": { "description": "The same date as ISO 8601 text when Facebook includes it; often null, so prefer the Unix seconds field.", "type": [ "string", "null" ] }, "end_date_string": { "description": "The same date as ISO 8601 text when Facebook includes it; often null, so prefer the Unix seconds field.", "type": [ "string", "null" ] }, "total_active_time": { "description": "Seconds the ad has run, when Facebook reports it; usually null.", "type": [ "number", "null" ] }, "publisher_platform": { "type": "array", "items": { "type": "string" }, "description": "Where it ran, uppercase: FACEBOOK, INSTAGRAM, AUDIENCE_NETWORK, MESSENGER, THREADS." }, "collation_count": { "description": "How many near-identical versions are grouped under this ad. A high count means the advertiser is scaling it; null for a single version.", "type": [ "number", "null" ] }, "collation_id": { "description": "Id shared by the grouped versions of this ad; null for a single version.", "type": [ "string", "null" ] }, "snapshot": { "type": "object", "properties": { "page_id": { "description": "The advertiser's page id (same as the ad's).", "type": [ "string", "null" ] }, "page_name": { "description": "The advertiser's page name as shown on the ad.", "type": [ "string", "null" ] }, "page_profile_uri": { "description": "The advertiser's Facebook page URL.", "type": [ "string", "null" ] }, "page_profile_picture_url": { "description": "The advertiser's profile picture, 60×60 px.", "type": [ "string", "null" ] }, "page_like_count": { "description": "Followers of the advertiser's page.", "type": [ "number", "null" ] }, "page_categories": { "type": "array", "items": { "type": "string" }, "description": "Page categories, e.g. [\"Outdoor & Sporting Goods Company\"]." }, "page_is_deleted": { "type": "boolean", "description": "Whether the advertiser's page has been deleted." }, "title": { "description": "Headline under the creative; null when there is none.", "type": [ "string", "null" ] }, "caption": { "description": "Display link under the creative, usually the domain (e.g. HOKA.com).", "type": [ "string", "null" ] }, "link_url": { "description": "Landing page the ad sends people to, UTM tags included.", "type": [ "string", "null" ] }, "link_description": { "description": "Text under the headline; null when there is none.", "type": [ "string", "null" ] }, "cta_text": { "description": "Button label, e.g. \"Shop now\".", "type": [ "string", "null" ] }, "cta_type": { "description": "Button type, e.g. SHOP_NOW, LEARN_MORE, NO_BUTTON.", "type": [ "string", "null" ] }, "display_format": { "description": "Creative format, e.g. IMAGE, VIDEO, DCO (dynamic creative), DPA (dynamic product ad) or MULTI_IMAGES. For DCO and DPA ads the creative is in `cards`.", "type": [ "string", "null" ] }, "images": { "type": "array", "items": { "type": "object", "properties": { "original_image_url": { "description": "Full-size image URL. Facebook CDN links expire after a few days; download what you need.", "type": [ "string", "null" ] }, "resized_image_url": { "description": "600 px image URL, good for thumbnails.", "type": [ "string", "null" ] }, "watermarked_resized_image_url": { "type": "string", "description": "Watermarked copy; empty or null in every response we've seen." }, "image_crops": { "type": "array", "items": {}, "description": "Facebook internal field; an empty array in every response we've seen. Crop hints for the image." } }, "required": [ "original_image_url", "resized_image_url", "watermarked_resized_image_url", "image_crops" ], "additionalProperties": false }, "description": "Image creatives. Empty for video and card-based ads, and with trim=true." }, "videos": { "type": "array", "items": { "type": "object", "properties": { "video_hd_url": { "description": "HD video file URL; null if Facebook has no HD version.", "type": [ "string", "null" ] }, "video_sd_url": { "description": "SD video file URL.", "type": [ "string", "null" ] }, "video_preview_image_url": { "description": "Poster frame (still image) URL.", "type": [ "string", "null" ] }, "watermarked_video_hd_url": { "description": "Watermarked copy; empty or null in every response we've seen.", "type": [ "string", "null" ] }, "watermarked_video_sd_url": { "description": "Watermarked copy; empty or null in every response we've seen.", "type": [ "string", "null" ] } }, "required": [ "video_hd_url", "video_sd_url", "video_preview_image_url", "watermarked_video_hd_url", "watermarked_video_sd_url" ], "additionalProperties": false }, "description": "Video creatives. Empty for image and card-based ads, and with trim=true." }, "cards": { "type": "array", "items": { "type": "object", "properties": { "title": { "description": "This version's headline.", "type": [ "string", "null" ] }, "body": { "description": "This version's primary text.", "type": [ "string", "null" ] }, "caption": { "description": "This version's display link, usually the domain.", "type": [ "string", "null" ] }, "cta_text": { "description": "Button label, e.g. \"Shop now\".", "type": [ "string", "null" ] }, "cta_type": { "description": "Button type, e.g. SHOP_NOW, LEARN_MORE.", "type": [ "string", "null" ] }, "link_url": { "description": "This version's landing page URL.", "type": [ "string", "null" ] }, "link_description": { "description": "Text under the headline; null when there is none.", "type": [ "string", "null" ] }, "original_image_url": { "description": "Full-size image URL; null for video versions.", "type": [ "string", "null" ] }, "resized_image_url": { "description": "600 px image URL; null for video versions.", "type": [ "string", "null" ] }, "watermarked_resized_image_url": { "type": "string", "description": "Watermarked copy; empty or null in every response we've seen." }, "image_crops": { "type": "array", "items": {}, "description": "Facebook internal field; an empty array in every response we've seen. Crop hints for the image." }, "video_hd_url": { "description": "HD video file URL; null for image versions.", "type": [ "string", "null" ] }, "video_sd_url": { "description": "SD video file URL; null for image versions.", "type": [ "string", "null" ] }, "video_preview_image_url": { "description": "Poster frame URL; null for image versions.", "type": [ "string", "null" ] }, "watermarked_video_hd_url": { "description": "Watermarked copy; empty or null in every response we've seen.", "type": [ "string", "null" ] }, "watermarked_video_sd_url": { "description": "Watermarked copy; empty or null in every response we've seen.", "type": [ "string", "null" ] } }, "required": [ "title", "body", "caption", "cta_text", "cta_type", "link_url", "link_description", "original_image_url", "resized_image_url", "watermarked_resized_image_url", "image_crops", "video_hd_url", "video_sd_url", "video_preview_image_url", "watermarked_video_hd_url", "watermarked_video_sd_url" ], "additionalProperties": false }, "description": "Carousel, dynamic-creative and product versions, each with its own copy and media. With trim=true the text stays and media URLs are null." }, "byline": { "description": "Line under the page name, when shown; null or empty in most ads.", "type": [ "string", "null" ] }, "disclaimer_label": { "description": "\"Paid for by\" line on political and issue ads; null otherwise.", "type": [ "string", "null" ] }, "country_iso_code": { "description": "Facebook internal field; null in every response we've seen. A country code on some ads.", "type": [ "string", "null" ] }, "is_reshared": { "type": "boolean", "description": "Whether the ad reshares an existing post (see `root_reshared_post`)." }, "root_reshared_post": { "description": "The original post when `is_reshared` is true; null otherwise." }, "branded_content": { "description": "Paid partnership details when the ad is branded content; null otherwise." }, "additional_info": { "description": "Facebook internal field; null in every response we've seen." }, "brazil_tax_id": { "description": "Advertiser tax id shown on ads under Brazil's rules; null otherwise." }, "ec_certificates": { "type": "array", "items": {}, "description": "Facebook internal field; an empty array in every response we've seen." }, "event": { "description": "Event details on event ads; null otherwise." }, "extra_images": { "type": "array", "items": {}, "description": "More images from dynamic creative; usually empty." }, "extra_links": { "type": "array", "items": {}, "description": "More landing page URLs from dynamic creative; usually empty." }, "extra_texts": { "type": "array", "items": {}, "description": "More text variations from dynamic creative; usually empty." }, "extra_videos": { "type": "array", "items": {}, "description": "More videos from dynamic creative; usually empty." }, "body": { "anyOf": [ { "type": "object", "properties": { "text": { "description": "The ad's primary text.", "type": [ "string", "null" ] } }, "required": [ "text" ], "additionalProperties": false }, { "type": "null" } ], "description": "Primary text as `{ text }`; null when the copy is only in `cards`." } }, "required": [ "page_id", "page_name", "page_profile_uri", "page_profile_picture_url", "page_like_count", "page_categories", "page_is_deleted", "title", "caption", "link_url", "link_description", "cta_text", "cta_type", "display_format", "images", "videos", "cards", "byline", "disclaimer_label", "country_iso_code", "is_reshared", "root_reshared_post", "branded_content", "additional_info", "brazil_tax_id", "ec_certificates", "event", "extra_images", "extra_links", "extra_texts", "extra_videos", "body" ], "additionalProperties": false, "description": "The creative: copy, media, landing page and advertiser details." }, "categories": { "type": "array", "items": { "type": "string" }, "description": "Special ad categories Facebook assigned. [\"UNKNOWN\"] for ordinary ads." }, "targeted_or_reached_countries": { "type": "array", "items": { "type": "string" }, "description": "Countries the ad targeted or reached, when Facebook discloses them; empty in most results." }, "currency": { "type": "string", "description": "Currency code of `spend` (e.g. USD) when spend is reported; an empty string otherwise." }, "spend": { "description": "Spend range, reported for political and issue ads only; null otherwise." }, "impressions_with_index": { "type": "object", "properties": { "impressions_text": { "description": "The range as Facebook shows it; null when not reported.", "type": [ "string", "null" ] }, "impressions_index": { "type": "number", "description": "Facebook's bucket number for the range; -1 when not reported." } }, "required": [ "impressions_text", "impressions_index" ], "additionalProperties": false, "description": "Impressions range, reported for political and issue ads only." }, "reach_estimate": { "description": "Estimated reach, which Facebook reports for some EU-delivered ads; null otherwise." }, "url": { "description": "Ad Library link for this ad. Often null; build it as https://www.facebook.com/ads/library/?id=.", "type": [ "string", "null" ] }, "contains_digital_created_media": { "type": "boolean", "description": "Whether Facebook labels the creative as AI-generated or digitally altered." }, "contains_sensitive_content": { "type": "boolean", "description": "Facebook internal field; false in every response we've seen. Facebook's sensitive-content flag." }, "gated_type": { "type": "string", "description": "Facebook internal field; ELIGIBLE (lowercase in ad details) in every response we've seen." }, "has_user_reported": { "type": "boolean", "description": "Whether the viewing user reported the ad. Always false: we read the Ad Library logged out." }, "hide_data_status": { "type": "string", "description": "Facebook internal field; NONE in every response we've seen." }, "is_aaa_eligible": { "type": "boolean", "description": "Facebook flag, true on a few ads; meaning undocumented. Ad details' `aaa_info` holds the related data when present." }, "menu_items": { "type": "array", "items": {}, "description": "Facebook internal field; an empty array in every response we've seen." }, "page_is_deleted": { "type": "boolean", "description": "Whether the advertiser's page has been deleted." }, "regional_regulation_data": { "type": "object", "properties": { "finserv": { "type": "object", "properties": { "is_deemed_finserv": { "type": "boolean", "description": "Facebook treats the ad as a financial-services ad." }, "is_limited_delivery": { "type": "boolean", "description": "Delivery is limited under financial-services rules." } }, "required": [ "is_deemed_finserv", "is_limited_delivery" ], "additionalProperties": false, "description": "Financial-services ad rules." }, "tw_anti_scam": { "type": "object", "properties": { "is_limited_delivery": { "type": "boolean", "description": "Delivery is limited under Taiwan's anti-scam rules." } }, "required": [ "is_limited_delivery" ], "additionalProperties": false, "description": "Taiwan's anti-scam ad rules." } }, "required": [ "finserv", "tw_anti_scam" ], "additionalProperties": false, "description": "Delivery limits under regional ad rules." }, "report_count": { "description": "Times the ad was reported, when disclosed; null in every response we've seen.", "type": [ "number", "null" ] }, "fev_info": { "description": "Facebook internal field; null in every response we've seen." }, "state_media_run_label": { "description": "Label for ads run by state-controlled media; null otherwise." } }, "required": [ "ad_archive_id", "ad_id", "page_id", "page_name", "is_active", "start_date", "end_date", "start_date_string", "end_date_string", "total_active_time", "publisher_platform", "collation_count", "collation_id", "snapshot", "categories", "targeted_or_reached_countries", "currency", "spend", "impressions_with_index", "reach_estimate", "url", "contains_digital_created_media", "contains_sensitive_content", "gated_type", "has_user_reported", "hide_data_status", "is_aaa_eligible", "menu_items", "page_is_deleted", "regional_regulation_data", "report_count", "fev_info", "state_media_run_label" ], "additionalProperties": false }, "description": "The advertiser's ads." }, "searchResultsCount": { "description": "Total matching ads, as Facebook estimates it. Only on the first page; null on cursor pages.", "type": [ "number", "null" ] }, "cursor": { "description": "Pass as `cursor` for the next page. null on the last page.", "type": [ "string", "null" ] } }, "required": [ "success", "credits_remaining", "credits_charged", "page_id", "page_name", "results", "searchResultsCount", "cursor" ], "additionalProperties": false } } } }, "404": { "description": "not_found: The endpoint, or the thing you asked for (ad, post, subreddit), doesn't exist. Charged when the platform was checked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error. Not charged, except the endpoint's own 4xx answers such as not_found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/facebook/adLibrary/ad": { "get": { "operationId": "facebook_ad", "tags": [ "Facebook" ], "summary": "Ad Library ad details", "description": "Full detail for one ad from Meta's Ad Library, by its id or URL.\n\nUse it for one ad's full creative after a search: pass its `ad_archive_id` as `id`, or an Ad Library link as `url`. Top-level keys here are camelCase (`adArchiveID`, `isActive`).\n\nEverything about a single ad: copy, every image and video, landing page, platforms and run dates. Unlike the list endpoints, top-level keys are camelCase (`adArchiveID`, `pageName`, `isActive`), `publisherPlatform` values are lowercase and `snapshot.body` is a plain string. Ads with several versions keep their creative in `snapshot.cards`.\n\nReturns 404 `not_found` if the ad doesn't exist.\n\nCost: 1 credit.", "externalDocs": { "url": "https://lurkapi.com/docs/facebook/ad" }, "x-credits": 1, "parameters": [ { "name": "id", "in": "query", "required": false, "description": "The ad's Ad Library id (`ad_archive_id`), e.g. `1016451784037642`. Required unless you pass `url`.", "schema": { "description": "The ad's Ad Library id (`ad_archive_id`), e.g. `1016451784037642`. Required unless you pass `url`.", "type": "string", "pattern": "^\\d+$" }, "example": "1016451784037642" }, { "name": "url", "in": "query", "required": false, "description": "An Ad Library link containing `?id=…`, e.g. `https://www.facebook.com/ads/library/?id=1016451784037642`.", "schema": { "description": "An Ad Library link containing `?id=…`, e.g. `https://www.facebook.com/ads/library/?id=1016451784037642`.", "type": "string" } }, { "name": "trim", "in": "query", "required": false, "description": "`true` drops image and video URLs (inside `snapshot.cards` too). All text is kept.", "schema": { "description": "`true` drops image and video URLs (inside `snapshot.cards` too). All text is kept.", "default": "false", "type": "string", "enum": [ "true", "false" ] } } ], "responses": { "200": { "description": "Full detail for one ad from Meta's Ad Library, by its id or URL.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "const": true, "description": "Always true here; errors have `success: false`." }, "credits_remaining": { "type": "number", "description": "Your balance after this call. On anonymous playground calls: free tries left today." }, "credits_charged": { "type": "number", "description": "Credits this call cost; 0 on free endpoints. On anonymous playground calls: tries used (1)." }, "adArchiveID": { "description": "The Ad Library id. Pass it as `id` to the ad details endpoint.", "type": [ "string", "null" ] }, "adid": { "description": "Meta's internal ad id. null in every response we've seen; use the Ad Library id.", "type": [ "string", "null" ] }, "pageID": { "description": "The advertiser's Facebook page id. Pass it as `pageId` to the company ads endpoint.", "type": [ "string", "null" ] }, "pageName": { "description": "The advertiser's page name.", "type": [ "string", "null" ] }, "isActive": { "type": "boolean", "description": "Whether the ad is running now." }, "startDate": { "description": "When the ad started running, Unix seconds (UTC).", "type": [ "number", "null" ] }, "endDate": { "description": "When the ad stopped, or its latest delivery date if still running, Unix seconds (UTC).", "type": [ "number", "null" ] }, "startDateString": { "description": "The same date as ISO 8601 text when Facebook includes it; often null, so prefer the Unix seconds field.", "type": [ "string", "null" ] }, "endDateString": { "description": "The same date as ISO 8601 text when Facebook includes it; often null, so prefer the Unix seconds field.", "type": [ "string", "null" ] }, "totalActiveTime": { "description": "Seconds the ad has run, when Facebook reports it; usually null.", "type": [ "number", "null" ] }, "publisherPlatform": { "type": "array", "items": { "type": "string" }, "description": "Where it ran, lowercase: facebook, instagram, audience_network, messenger, threads." }, "collationCount": { "description": "How many near-identical versions are grouped under this ad. A high count means the advertiser is scaling it; null for a single version.", "type": [ "number", "null" ] }, "collationID": { "description": "Id shared by the grouped versions of this ad; null for a single version.", "type": [ "string", "null" ] }, "snapshot": { "type": "object", "properties": { "page_id": { "description": "The advertiser's page id (same as the ad's).", "type": [ "string", "null" ] }, "page_name": { "description": "The advertiser's page name as shown on the ad.", "type": [ "string", "null" ] }, "page_profile_uri": { "description": "The advertiser's Facebook page URL.", "type": [ "string", "null" ] }, "page_profile_picture_url": { "description": "The advertiser's profile picture, 60×60 px.", "type": [ "string", "null" ] }, "page_like_count": { "description": "Followers of the advertiser's page.", "type": [ "number", "null" ] }, "page_categories": { "type": "array", "items": { "type": "string" }, "description": "Page categories, e.g. [\"Outdoor & Sporting Goods Company\"]." }, "page_is_deleted": { "type": "boolean", "description": "Whether the advertiser's page has been deleted." }, "title": { "description": "Headline under the creative; null when there is none.", "type": [ "string", "null" ] }, "caption": { "description": "Display link under the creative, usually the domain (e.g. HOKA.com).", "type": [ "string", "null" ] }, "link_url": { "description": "Landing page the ad sends people to, UTM tags included.", "type": [ "string", "null" ] }, "link_description": { "description": "Text under the headline; null when there is none.", "type": [ "string", "null" ] }, "cta_text": { "description": "Button label, e.g. \"Shop now\".", "type": [ "string", "null" ] }, "cta_type": { "description": "Button type, e.g. SHOP_NOW, LEARN_MORE, NO_BUTTON.", "type": [ "string", "null" ] }, "display_format": { "description": "Creative format, e.g. IMAGE, VIDEO, DCO (dynamic creative), DPA (dynamic product ad) or MULTI_IMAGES. For DCO and DPA ads the creative is in `cards`.", "type": [ "string", "null" ] }, "images": { "type": "array", "items": { "type": "object", "properties": { "original_image_url": { "description": "Full-size image URL. Facebook CDN links expire after a few days; download what you need.", "type": [ "string", "null" ] }, "resized_image_url": { "description": "600 px image URL, good for thumbnails.", "type": [ "string", "null" ] }, "watermarked_resized_image_url": { "type": "string", "description": "Watermarked copy; empty or null in every response we've seen." }, "image_crops": { "type": "array", "items": {}, "description": "Facebook internal field; an empty array in every response we've seen. Crop hints for the image." } }, "required": [ "original_image_url", "resized_image_url", "watermarked_resized_image_url", "image_crops" ], "additionalProperties": false }, "description": "Image creatives. Empty for video and card-based ads, and with trim=true." }, "videos": { "type": "array", "items": { "type": "object", "properties": { "video_hd_url": { "description": "HD video file URL; null if Facebook has no HD version.", "type": [ "string", "null" ] }, "video_sd_url": { "description": "SD video file URL.", "type": [ "string", "null" ] }, "video_preview_image_url": { "description": "Poster frame (still image) URL.", "type": [ "string", "null" ] }, "watermarked_video_hd_url": { "description": "Watermarked copy; empty or null in every response we've seen.", "type": [ "string", "null" ] }, "watermarked_video_sd_url": { "description": "Watermarked copy; empty or null in every response we've seen.", "type": [ "string", "null" ] } }, "required": [ "video_hd_url", "video_sd_url", "video_preview_image_url", "watermarked_video_hd_url", "watermarked_video_sd_url" ], "additionalProperties": false }, "description": "Video creatives. Empty for image and card-based ads, and with trim=true." }, "cards": { "type": "array", "items": { "type": "object", "properties": { "title": { "description": "This version's headline.", "type": [ "string", "null" ] }, "body": { "description": "This version's primary text.", "type": [ "string", "null" ] }, "caption": { "description": "This version's display link, usually the domain.", "type": [ "string", "null" ] }, "cta_text": { "description": "Button label, e.g. \"Shop now\".", "type": [ "string", "null" ] }, "cta_type": { "description": "Button type, e.g. SHOP_NOW, LEARN_MORE.", "type": [ "string", "null" ] }, "link_url": { "description": "This version's landing page URL.", "type": [ "string", "null" ] }, "link_description": { "description": "Text under the headline; null when there is none.", "type": [ "string", "null" ] }, "original_image_url": { "description": "Full-size image URL; null for video versions.", "type": [ "string", "null" ] }, "resized_image_url": { "description": "600 px image URL; null for video versions.", "type": [ "string", "null" ] }, "watermarked_resized_image_url": { "type": "string", "description": "Watermarked copy; empty or null in every response we've seen." }, "image_crops": { "type": "array", "items": {}, "description": "Facebook internal field; an empty array in every response we've seen. Crop hints for the image." }, "video_hd_url": { "description": "HD video file URL; null for image versions.", "type": [ "string", "null" ] }, "video_sd_url": { "description": "SD video file URL; null for image versions.", "type": [ "string", "null" ] }, "video_preview_image_url": { "description": "Poster frame URL; null for image versions.", "type": [ "string", "null" ] }, "watermarked_video_hd_url": { "description": "Watermarked copy; empty or null in every response we've seen.", "type": [ "string", "null" ] }, "watermarked_video_sd_url": { "description": "Watermarked copy; empty or null in every response we've seen.", "type": [ "string", "null" ] } }, "required": [ "title", "body", "caption", "cta_text", "cta_type", "link_url", "link_description", "original_image_url", "resized_image_url", "watermarked_resized_image_url", "image_crops", "video_hd_url", "video_sd_url", "video_preview_image_url", "watermarked_video_hd_url", "watermarked_video_sd_url" ], "additionalProperties": false }, "description": "Carousel, dynamic-creative and product versions, each with its own copy and media. With trim=true the text stays and media URLs are null." }, "byline": { "description": "Line under the page name, when shown; null or empty in most ads.", "type": [ "string", "null" ] }, "disclaimer_label": { "description": "\"Paid for by\" line on political and issue ads; null otherwise.", "type": [ "string", "null" ] }, "country_iso_code": { "description": "Facebook internal field; null in every response we've seen. A country code on some ads.", "type": [ "string", "null" ] }, "is_reshared": { "type": "boolean", "description": "Whether the ad reshares an existing post (see `root_reshared_post`)." }, "root_reshared_post": { "description": "The original post when `is_reshared` is true; null otherwise." }, "branded_content": { "description": "Paid partnership details when the ad is branded content; null otherwise." }, "additional_info": { "description": "Facebook internal field; null in every response we've seen." }, "brazil_tax_id": { "description": "Advertiser tax id shown on ads under Brazil's rules; null otherwise." }, "ec_certificates": { "type": "array", "items": {}, "description": "Facebook internal field; an empty array in every response we've seen." }, "event": { "description": "Event details on event ads; null otherwise." }, "extra_images": { "type": "array", "items": {}, "description": "More images from dynamic creative; usually empty." }, "extra_links": { "type": "array", "items": {}, "description": "More landing page URLs from dynamic creative; usually empty." }, "extra_texts": { "type": "array", "items": {}, "description": "More text variations from dynamic creative; usually empty." }, "extra_videos": { "type": "array", "items": {}, "description": "More videos from dynamic creative; usually empty." }, "body": { "description": "The ad's primary text as a plain string; null when the copy is only in `cards`.", "type": [ "string", "null" ] }, "final_url": { "description": "Final landing URL after redirects, when Facebook reports it; usually null.", "type": [ "string", "null" ] } }, "required": [ "page_id", "page_name", "page_profile_uri", "page_profile_picture_url", "page_like_count", "page_categories", "page_is_deleted", "title", "caption", "link_url", "link_description", "cta_text", "cta_type", "display_format", "images", "videos", "cards", "byline", "disclaimer_label", "country_iso_code", "is_reshared", "root_reshared_post", "branded_content", "additional_info", "brazil_tax_id", "ec_certificates", "event", "extra_images", "extra_links", "extra_texts", "extra_videos", "body", "final_url" ], "additionalProperties": false, "description": "The creative: copy, media, landing page and advertiser details (snake_case inside)." }, "categories": { "type": "array", "items": { "type": "string" }, "description": "Special ad categories Facebook assigned. [\"UNKNOWN\"] for ordinary ads." }, "currency": { "type": "string", "description": "Currency code of `spend` (e.g. USD) when spend is reported; an empty string otherwise." }, "spend": { "description": "Spend range, reported for political and issue ads only; null otherwise." }, "impressionsWithIndex": { "type": "object", "properties": { "impressionsText": { "description": "The range as Facebook shows it; null when not reported.", "type": [ "string", "null" ] }, "impressionsIndex": { "type": "number", "description": "Facebook's bucket number for the range; -1 when not reported." } }, "required": [ "impressionsText", "impressionsIndex" ], "additionalProperties": false, "description": "Impressions range, reported for political and issue ads only." }, "reachEstimate": { "description": "Estimated reach, which Facebook reports for some EU-delivered ads; null otherwise." }, "url": { "description": "Ad Library link for this ad. Often null; build it as https://www.facebook.com/ads/library/?id=.", "type": [ "string", "null" ] }, "containsDigitallyCreatedMedia": { "type": "boolean", "description": "Whether Facebook labels the creative as AI-generated or digitally altered." }, "containsSensitiveContent": { "type": "boolean", "description": "Facebook internal field; false in every response we've seen. Facebook's sensitive-content flag." }, "gatedType": { "type": "string", "description": "Facebook internal field; ELIGIBLE (lowercase in ad details) in every response we've seen." }, "hasUserReported": { "type": "boolean", "description": "Whether the viewing user reported the ad. Always false: we read the Ad Library logged out." }, "hideDataStatus": { "type": "string", "description": "Facebook internal field; NONE in every response we've seen." }, "isAAAEligible": { "type": "boolean", "description": "Facebook flag, true on a few ads; meaning undocumented. Ad details' `aaa_info` holds the related data when present." }, "menuItems": { "type": "array", "items": {}, "description": "Facebook internal field; an empty array in every response we've seen." }, "pageIsDeleted": { "type": "boolean", "description": "Whether the advertiser's page has been deleted." }, "regionalRegulationData": { "type": "object", "properties": { "finserv": { "type": "object", "properties": { "is_deemed_finserv": { "type": "boolean", "description": "Facebook treats the ad as a financial-services ad." }, "is_limited_delivery": { "type": "boolean", "description": "Delivery is limited under financial-services rules." } }, "required": [ "is_deemed_finserv", "is_limited_delivery" ], "additionalProperties": false, "description": "Financial-services ad rules." }, "tw_anti_scam": { "type": "object", "properties": { "is_limited_delivery": { "type": "boolean", "description": "Delivery is limited under Taiwan's anti-scam rules." } }, "required": [ "is_limited_delivery" ], "additionalProperties": false, "description": "Taiwan's anti-scam ad rules." } }, "required": [ "finserv", "tw_anti_scam" ], "additionalProperties": false, "description": "Delivery limits under regional ad rules." }, "reportCount": { "description": "Times the ad was reported, when disclosed; null in every response we've seen.", "type": [ "number", "null" ] }, "fevInfo": { "description": "Facebook internal field; null in every response we've seen." }, "stateMediaRunLabel": { "description": "Label for ads run by state-controlled media; null otherwise." }, "aaa_info": { "description": "Extra transparency data on some ads (see `isAAAEligible`); null in every response we've seen." } }, "required": [ "success", "credits_remaining", "credits_charged", "adArchiveID", "adid", "pageID", "pageName", "isActive", "startDate", "endDate", "startDateString", "endDateString", "totalActiveTime", "publisherPlatform", "collationCount", "collationID", "snapshot", "categories", "currency", "spend", "impressionsWithIndex", "reachEstimate", "url", "containsDigitallyCreatedMedia", "containsSensitiveContent", "gatedType", "hasUserReported", "hideDataStatus", "isAAAEligible", "menuItems", "pageIsDeleted", "regionalRegulationData", "reportCount", "fevInfo", "stateMediaRunLabel", "aaa_info" ], "additionalProperties": false } } } }, "404": { "description": "not_found: The endpoint, or the thing you asked for (ad, post, subreddit), doesn't exist. Charged when the platform was checked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error. Not charged, except the endpoint's own 4xx answers such as not_found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/facebook/adLibrary/search/companies": { "get": { "operationId": "facebook_search_companies", "tags": [ "Facebook" ], "summary": "Search Ad Library companies", "description": "Find an advertiser's Facebook page id by name in Meta's Ad Library, with followers and linked Instagram.\n\nUse it to turn a brand name into the `page_id` that company ads (facebook_company_ads) needs. Big brands have several pages (regional, product lines); pick by `name`, `likes` and `verification`.\n\nTypeahead search over advertisers in the Ad Library, like the search box on facebook.com/ads/library. Returns up to about 15 matches, no pagination.\n\nCost: 1 credit.", "externalDocs": { "url": "https://lurkapi.com/docs/facebook/search-companies" }, "x-credits": 1, "parameters": [ { "name": "query", "in": "query", "required": true, "description": "Brand or page name, e.g. `nike`.", "schema": { "type": "string", "minLength": 1, "description": "Brand or page name, e.g. `nike`." }, "example": "nike" }, { "name": "country", "in": "query", "required": false, "description": "2-letter country code that biases which pages rank first, or ALL.", "schema": { "description": "2-letter country code that biases which pages rank first, or ALL.", "default": "US", "type": "string", "pattern": "^(ALL|[A-Z]{2})$" } } ], "responses": { "200": { "description": "Find an advertiser's Facebook page id by name in Meta's Ad Library, with followers and linked Instagram.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "const": true, "description": "Always true here; errors have `success: false`." }, "credits_remaining": { "type": "number", "description": "Your balance after this call. On anonymous playground calls: free tries left today." }, "credits_charged": { "type": "number", "description": "Credits this call cost; 0 on free endpoints. On anonymous playground calls: tries used (1)." }, "searchResults": { "type": "array", "items": { "type": "object", "properties": { "page_id": { "description": "The page id. Pass it as `pageId` to the company ads endpoint.", "type": [ "string", "null" ] }, "name": { "description": "The page's name.", "type": [ "string", "null" ] }, "page_alias": { "description": "Vanity name: facebook.com/.", "type": [ "string", "null" ] }, "category": { "description": "Page category, e.g. \"Sportswear Store\".", "type": [ "string", "null" ] }, "likes": { "description": "Page followers.", "type": [ "number", "null" ] }, "verification": { "description": "BLUE_VERIFIED or NOT_VERIFIED.", "type": [ "string", "null" ] }, "image_uri": { "description": "Profile picture URL.", "type": [ "string", "null" ] }, "ig_username": { "description": "Linked Instagram username, without @; null when none is linked.", "type": [ "string", "null" ] }, "ig_followers": { "description": "Followers of the linked Instagram account; null when none is linked.", "type": [ "number", "null" ] }, "ig_verification": { "type": "boolean", "description": "Whether the linked Instagram account is verified; false when none is linked." }, "country": { "description": "The page's country; null in every response we've seen.", "type": [ "string", "null" ] }, "entity_type": { "description": "Facebook's page type; PERSON_PROFILE for most pages, brands included.", "type": [ "string", "null" ] }, "page_is_deleted": { "type": "boolean", "description": "Whether the page has been deleted." } }, "required": [ "page_id", "name", "page_alias", "category", "likes", "verification", "image_uri", "ig_username", "ig_followers", "ig_verification", "country", "entity_type", "page_is_deleted" ], "additionalProperties": false }, "description": "Matching advertiser pages, best match first." } }, "required": [ "success", "credits_remaining", "credits_charged", "searchResults" ], "additionalProperties": false } } } }, "default": { "description": "Error. Not charged, except the endpoint's own 4xx answers such as not_found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/facebook/profile": { "get": { "operationId": "facebook_profile", "tags": [ "Facebook" ], "summary": "Public Page profile", "description": "Public business Page metadata, pictures, verification and follower counts.\n\nPass a public Facebook business Page URL. New-style Pages expose a profile id and a separate page_id. Counts and descriptions come from the logged-out page; omitted counts stay null. This endpoint returns metadata, not a page feed or personal-profile details.\n\nCost: 1 credit.", "externalDocs": { "url": "https://lurkapi.com/docs/facebook/profile" }, "x-credits": 1, "parameters": [ { "name": "url", "in": "query", "required": true, "description": "A public business Page URL, such as https://www.facebook.com/NASA. Personal profiles are unavailable.", "schema": { "description": "A public business Page URL, such as https://www.facebook.com/NASA. Personal profiles are unavailable.", "type": "string" }, "example": "https://www.facebook.com/NASA" } ], "responses": { "200": { "description": "Public business Page metadata, pictures, verification and follower counts.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "const": true, "description": "Always true here; errors have `success: false`." }, "credits_remaining": { "type": "number", "description": "Your balance after this call. On anonymous playground calls: free tries left today." }, "credits_charged": { "type": "number", "description": "Credits this call cost; 0 on free endpoints. On anonymous playground calls: tries used (1)." }, "id": { "type": "string", "description": "Facebook's profile id for the Page. New-style Pages can use a different underlying page_id." }, "page_id": { "type": "string", "description": "The Page's delegate id, useful for Ad Library company ads." }, "url": { "type": "string", "description": "The canonical public Facebook Page URL." }, "name": { "type": "string", "description": "The Page's display name." }, "description": { "description": "The exact public description, which can include the Page name, follower counts and biography.", "type": [ "string", "null" ] }, "is_verified": { "description": "Whether the public header shows Facebook's verification badge; null if omitted.", "type": [ "boolean", "null" ] }, "followers_count": { "description": "Exact follower count from public page metadata; rounded display counts are not converted into exact counts; null when Facebook does not disclose it to public visitors.", "type": [ "number", "null" ] }, "followers_text": { "description": "The follower count label shown in the header, which is often rounded (for example 28M followers).", "type": [ "string", "null" ] }, "following_count": { "description": "Exact following count, when the public header shows an unrounded number; null when Facebook does not disclose it to public visitors.", "type": [ "number", "null" ] }, "talking_about_count": { "description": "The talking-about count reported in Facebook's public page metadata; null when Facebook does not disclose it to public visitors.", "type": [ "number", "null" ] }, "profile_picture_url": { "description": "The public Page profile-picture CDN URL. CDN links expire.", "type": [ "string", "null" ] }, "cover_photo_url": { "description": "The public Page cover-photo CDN URL. CDN links expire.", "type": [ "string", "null" ] } }, "required": [ "success", "credits_remaining", "credits_charged", "id", "page_id", "url", "name", "description", "is_verified", "followers_count", "followers_text", "following_count", "talking_about_count", "profile_picture_url", "cover_photo_url" ], "additionalProperties": false } } } }, "403": { "description": "not_public: The platform confirmed this account or content isn't available to logged-out visitors. Use a publicly visible target.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "not_found: The endpoint, or the thing you asked for (ad, post, subreddit), doesn't exist. Charged when the platform was checked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error. Not charged, except the endpoint's own 4xx answers such as not_found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/facebook/post": { "get": { "operationId": "facebook_post", "tags": [ "Facebook" ], "summary": "Public post", "description": "A public post's text, author, engagement counts and attached media.\n\nPass a public Facebook post permalink or video URL. Public counts can be hidden or delayed; missing fields stay null. The response includes media exposed to logged-out visitors, but does not fetch comments or follow share links. CDN media URLs expire.\n\nCost: 1 credit.", "externalDocs": { "url": "https://lurkapi.com/docs/facebook/post" }, "x-credits": 1, "parameters": [ { "name": "url", "in": "query", "required": true, "description": "A public Facebook post or video URL. Supports posts, permalink.php, story.php, videos and watch URLs; share links and groups are unavailable.", "schema": { "description": "A public Facebook post or video URL. Supports posts, permalink.php, story.php, videos and watch URLs; share links and groups are unavailable.", "type": "string" }, "example": "https://www.facebook.com/attn/posts/pfbid0j1Czf2gGDVqeQ8KiMLFm3pWN8GxsQmeRrVhimWDzMuKQoR8r4b1knNsejELmUgyhl" } ], "responses": { "200": { "description": "A public post's text, author, engagement counts and attached media.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "const": true, "description": "Always true here; errors have `success: false`." }, "credits_remaining": { "type": "number", "description": "Your balance after this call. On anonymous playground calls: free tries left today." }, "credits_charged": { "type": "number", "description": "Credits this call cost; 0 on free endpoints. On anonymous playground calls: tries used (1)." }, "post_id": { "type": "string", "description": "Numeric post id, separate from Facebook's opaque GraphQL story id." }, "url": { "type": "string", "description": "The post's canonical Facebook permalink." }, "text": { "description": "Public post text, preserving line breaks; null for a media-only post.", "type": [ "string", "null" ] }, "created_at": { "description": "Post publication time as Unix seconds; null when Facebook does not disclose it to public visitors.", "type": [ "number", "null" ] }, "author": { "type": "object", "properties": { "id": { "type": "string", "description": "Author profile id." }, "name": { "type": "string", "description": "Author display name." }, "url": { "description": "Author's public Facebook URL.", "type": [ "string", "null" ] } }, "required": [ "id", "name", "url" ], "additionalProperties": false, "description": "The author of this post, rather than an author mentioned in its text or comments." }, "reaction_count": { "description": "Total reactions to the post; null when Facebook does not disclose it to public visitors.", "type": [ "number", "null" ] }, "comment_count": { "description": "Total comments Facebook reports for the public comment list; null when Facebook does not disclose it to public visitors.", "type": [ "number", "null" ] }, "share_count": { "description": "Share count; null when Facebook does not disclose it to public visitors.", "type": [ "number", "null" ] }, "view_count": { "description": "Video view count; null when Facebook does not disclose it to public visitors.", "type": [ "number", "null" ] }, "reactions": { "type": "array", "items": { "type": "object", "properties": { "name": { "description": "Facebook's localized reaction name, such as Like or Love.", "type": [ "string", "null" ] }, "count": { "description": "Number of reactions of this type; null when Facebook does not disclose it to public visitors.", "type": [ "number", "null" ] } }, "required": [ "name", "count" ], "additionalProperties": false }, "description": "The reaction breakdown Facebook includes; an empty list means no breakdown was exposed." }, "media": { "type": "array", "items": { "type": "object", "properties": { "id": { "description": "Media id.", "type": [ "string", "null" ] }, "type": { "type": "string", "enum": [ "image", "video" ], "description": "Media format." }, "url": { "description": "Facebook media permalink.", "type": [ "string", "null" ] }, "image_url": { "description": "Image or video thumbnail CDN URL; CDN links expire.", "type": [ "string", "null" ] }, "width": { "description": "Media width in pixels; null when Facebook does not disclose it to public visitors.", "type": [ "number", "null" ] }, "height": { "description": "Media height in pixels; null when Facebook does not disclose it to public visitors.", "type": [ "number", "null" ] }, "sd_url": { "description": "Standard-definition progressive video CDN URL; null for images. CDN links expire.", "type": [ "string", "null" ] }, "hd_url": { "description": "High-definition progressive video CDN URL; null for images. CDN links expire.", "type": [ "string", "null" ] }, "duration_s": { "description": "Video duration in seconds; null for images; null when Facebook does not disclose it to public visitors.", "type": [ "number", "null" ] } }, "required": [ "id", "type", "url", "image_url", "width", "height", "sd_url", "hd_url", "duration_s" ], "additionalProperties": false }, "description": "Publicly exposed attached images and videos; delivery URLs can expire." } }, "required": [ "success", "credits_remaining", "credits_charged", "post_id", "url", "text", "created_at", "author", "reaction_count", "comment_count", "share_count", "view_count", "reactions", "media" ], "additionalProperties": false } } } }, "403": { "description": "not_public: The platform confirmed this account or content isn't available to logged-out visitors. Use a publicly visible target.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "not_found: The endpoint, or the thing you asked for (ad, post, subreddit), doesn't exist. Charged when the platform was checked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error. Not charged, except the endpoint's own 4xx answers such as not_found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/reddit/subreddit": { "get": { "operationId": "reddit_subreddit_posts", "tags": [ "Reddit" ], "summary": "Subreddit posts", "description": "A subreddit's feed (hot, new, top, rising or best), with titles, text, scores and comment counts.\n\nUse it to track what a community talks about. About 25 posts per page; pass `after` for more. `timeframe` only applies with `sort=top`. Missing, private and banned subreddits return an empty `posts` list.\n\nOne page of a subreddit's feed as sorted on reddit.com, with titles, text, scores and comment counts.\n\n**Pagination.** Pass the response's `after` back as `after` for the next page; `after` is null at the end.\n\nCost: 1 credit.", "externalDocs": { "url": "https://lurkapi.com/docs/reddit/subreddit-posts" }, "x-credits": 1, "parameters": [ { "name": "subreddit", "in": "query", "required": true, "description": "Subreddit name without r/, e.g. `marketing`.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9_]{1,21}$", "description": "Subreddit name without r/, e.g. `marketing`." }, "example": "marketing" }, { "name": "sort", "in": "query", "required": false, "description": "Feed order, as on reddit.com.", "schema": { "description": "Feed order, as on reddit.com.", "default": "hot", "type": "string", "enum": [ "best", "hot", "new", "top", "rising" ] } }, { "name": "timeframe", "in": "query", "required": false, "description": "Time window for `sort=top`: hour, day, week, month, year or all.", "schema": { "description": "Time window for `sort=top`: hour, day, week, month, year or all.", "default": "all", "type": "string", "enum": [ "all", "hour", "day", "week", "month", "year" ] } }, { "name": "after", "in": "query", "required": false, "description": "The `after` from the previous response, to get the next page.", "schema": { "description": "The `after` from the previous response, to get the next page.", "type": "string" } }, { "name": "trim", "in": "query", "required": false, "description": "`true` omits `selftext_html` for a smaller response.", "schema": { "description": "`true` omits `selftext_html` for a smaller response.", "default": "false", "type": "string", "enum": [ "true", "false" ] } } ], "responses": { "200": { "description": "A subreddit's feed (hot, new, top, rising or best), with titles, text, scores and comment counts.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "const": true, "description": "Always true here; errors have `success: false`." }, "credits_remaining": { "type": "number", "description": "Your balance after this call. On anonymous playground calls: free tries left today." }, "credits_charged": { "type": "number", "description": "Credits this call cost; 0 on free endpoints. On anonymous playground calls: tries used (1)." }, "posts": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Post id, e.g. `1wtfnyr`." }, "name": { "type": "string", "description": "Fullname, `t3_` + id. Subreddit listings paginate with it." }, "title": { "type": "string", "description": "Post title." }, "author": { "description": "Username, without u/; null if unknown.", "type": [ "string", "null" ] }, "author_fullname": { "description": "Author's account fullname, `t2_` + id; null if unknown.", "type": [ "string", "null" ] }, "subreddit": { "type": "string", "description": "Subreddit name without r/, e.g. `marketing`." }, "subreddit_id": { "description": "Subreddit fullname, `t5_` + id.", "type": [ "string", "null" ] }, "subreddit_name_prefixed": { "description": "e.g. `r/marketing`.", "type": [ "string", "null" ] }, "permalink": { "type": "string", "description": "Path on reddit.com; prepend https://www.reddit.com." }, "url": { "type": "string", "description": "The link a link post points to, or the post itself for text posts." }, "url_overridden_by_dest": { "description": "Outbound link, on link posts only.", "type": "string" }, "domain": { "description": "`self.` for text posts, else the linked site.", "type": [ "string", "null" ] }, "selftext": { "type": "string", "description": "Post body as plain text. Empty for link posts." }, "selftext_html": { "description": "Post body as HTML. Omitted with trim=true.", "type": [ "string", "null" ] }, "score": { "type": "number", "description": "Upvotes minus downvotes." }, "ups": { "type": "number", "description": "Same as score." }, "upvote_ratio": { "description": "Share of votes that are upvotes, 0–1.", "type": [ "number", "null" ] }, "num_comments": { "type": "number", "description": "Comment count when fetched." }, "created": { "type": "number", "description": "Posted at, Unix seconds." }, "created_utc": { "type": "number", "description": "Posted at, Unix seconds." }, "is_self": { "type": "boolean", "description": "A text post rather than a link." }, "is_video": { "type": "boolean", "description": "A video post." }, "is_gallery": { "description": "Present (true) on image galleries; absent otherwise.", "type": "boolean" }, "over_18": { "type": "boolean", "description": "Marked NSFW." }, "spoiler": { "type": "boolean", "description": "Marked as a spoiler." }, "stickied": { "type": "boolean", "description": "Pinned by moderators." }, "locked": { "type": "boolean", "description": "Locked: no new comments allowed." }, "link_flair_text": { "description": "Post flair, e.g. \"Question\"; null without flair.", "type": [ "string", "null" ] }, "link_flair_background_color": { "description": "Flair color as a hex code, e.g. #94E044; null without flair.", "type": [ "string", "null" ] }, "thumbnail": { "description": "Preview image URL; null for posts without media.", "type": [ "string", "null" ] }, "total_awards_received": { "type": "number", "description": "Awards the post received." } }, "required": [ "id", "name", "title", "author", "author_fullname", "subreddit", "subreddit_id", "subreddit_name_prefixed", "permalink", "url", "domain", "selftext", "score", "ups", "upvote_ratio", "num_comments", "created", "created_utc", "is_self", "is_video", "over_18", "spoiler", "stickied", "locked", "link_flair_text", "link_flair_background_color", "thumbnail", "total_awards_received" ], "additionalProperties": false }, "description": "One page of posts, in feed order." }, "after": { "description": "Pass as `after` for the next page. null on the last page.", "type": [ "string", "null" ] } }, "required": [ "success", "credits_remaining", "credits_charged", "posts", "after" ], "additionalProperties": false } } } }, "default": { "description": "Error. Not charged, except the endpoint's own 4xx answers such as not_found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/reddit/subreddit/details": { "get": { "operationId": "reddit_subreddit_details", "tags": [ "Reddit" ], "summary": "Subreddit details", "description": "A community's size, activity, description, rules and images.\n\nUse it to size up a community before posting: weekly visitors and contributions, rules and description. There's no subscriber count (reddit.com no longer shows it); `weekly_active_users` is the closest measure.\n\nStats and settings for one subreddit: the numbers reddit.com shows on the community page, numbered rules, icon, banner and creation date. Pass `subreddit` or a Reddit `url`.\n\nUnknown or private subreddits return 404 `not_found`.\n\nCost: 1 credit.", "externalDocs": { "url": "https://lurkapi.com/docs/reddit/subreddit-details" }, "x-credits": 1, "parameters": [ { "name": "subreddit", "in": "query", "required": false, "description": "Subreddit name (e.g. `marketing`) or URL. Required unless you pass `url`.", "schema": { "description": "Subreddit name (e.g. `marketing`) or URL. Required unless you pass `url`.", "type": "string" }, "example": "marketing" }, { "name": "url", "in": "query", "required": false, "description": "Any Reddit URL containing /r/, e.g. `https://www.reddit.com/r/marketing/`.", "schema": { "description": "Any Reddit URL containing /r/, e.g. `https://www.reddit.com/r/marketing/`.", "type": "string" } } ], "responses": { "200": { "description": "A community's size, activity, description, rules and images.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "const": true, "description": "Always true here; errors have `success: false`." }, "credits_remaining": { "type": "number", "description": "Your balance after this call. On anonymous playground calls: free tries left today." }, "credits_charged": { "type": "number", "description": "Credits this call cost; 0 on free endpoints. On anonymous playground calls: tries used (1)." }, "subreddit_id": { "type": "string", "description": "Fullname, `t5_…`." }, "display_name": { "type": "string", "description": "Name with Reddit's capitalization." }, "description": { "type": "string", "description": "The public one-paragraph description." }, "rules": { "type": "string", "description": "Community rules as numbered plain text: \"1. Title\\nDetails\\n\\n2. …\"." }, "weekly_active_users": { "description": "Weekly visitors, as shown on the community page.", "type": [ "number", "null" ] }, "weekly_contributions": { "description": "Posts plus comments in the last week.", "type": [ "number", "null" ] }, "icon_img": { "description": "Community icon URL; null if none.", "type": [ "string", "null" ] }, "header_img": { "description": "Banner image URL; null if none.", "type": [ "string", "null" ] }, "created_at": { "type": "string", "description": "When the subreddit was created, ISO 8601." } }, "required": [ "success", "credits_remaining", "credits_charged", "subreddit_id", "display_name", "description", "rules", "weekly_active_users", "weekly_contributions", "icon_img", "header_img", "created_at" ], "additionalProperties": false } } } }, "404": { "description": "not_found: The endpoint, or the thing you asked for (ad, post, subreddit), doesn't exist. Charged when the platform was checked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error. Not charged, except the endpoint's own 4xx answers such as not_found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/reddit/subreddit/search": { "get": { "operationId": "reddit_subreddit_search", "tags": [ "Reddit" ], "summary": "Subreddit search", "description": "Search one subreddit's posts by keyword, returned as compact result cards.\n\nUse it to find what one community says about a product, competitor or problem. Results are compact cards without the body; pass a result's `url` to post comments (reddit_post_comments) for the text and replies.\n\nKeyword search inside one subreddit, like the search box on a community page. Results carry `votes`, `num_comments`, `created_at` and subreddit info.\n\n**Pagination.** Pass the response's `cursor` back as `cursor`; it's null at the end.\n\nCost: 1 credit.", "externalDocs": { "url": "https://lurkapi.com/docs/reddit/subreddit-search" }, "x-credits": 1, "parameters": [ { "name": "subreddit", "in": "query", "required": true, "description": "Subreddit name without r/, e.g. `marketing`.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9_]{1,21}$", "description": "Subreddit name without r/, e.g. `marketing`." }, "example": "marketing" }, { "name": "query", "in": "query", "required": false, "description": "Keywords. Leave empty to list the subreddit's posts in `sort` order.", "schema": { "default": "", "description": "Keywords. Leave empty to list the subreddit's posts in `sort` order.", "type": "string" }, "example": "AI video" }, { "name": "sort", "in": "query", "required": false, "description": "Result order. `comments` = most commented.", "schema": { "description": "Result order. `comments` = most commented.", "default": "relevance", "type": "string", "enum": [ "relevance", "hot", "top", "new", "comments" ] } }, { "name": "timeframe", "in": "query", "required": false, "description": "Only posts from the last hour, day, week, month, year, or all time.", "schema": { "description": "Only posts from the last hour, day, week, month, year, or all time.", "default": "all", "type": "string", "enum": [ "all", "hour", "day", "week", "month", "year" ] } }, { "name": "cursor", "in": "query", "required": false, "description": "The `cursor` from the previous response, to get the next page.", "schema": { "description": "The `cursor` from the previous response, to get the next page.", "type": "string" } } ], "responses": { "200": { "description": "Search one subreddit's posts by keyword, returned as compact result cards.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "const": true, "description": "Always true here; errors have `success: false`." }, "credits_remaining": { "type": "number", "description": "Your balance after this call. On anonymous playground calls: free tries left today." }, "credits_charged": { "type": "number", "description": "Credits this call cost; 0 on free endpoints. On anonymous playground calls: tries used (1)." }, "posts": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Fullname, e.g. `t3_1t673is`." }, "post_id": { "type": "string", "description": "Same as id." }, "title": { "type": "string", "description": "Post title." }, "url": { "type": "string", "description": "The post on reddit.com. Pass it to post comments for the body and replies." }, "permalink": { "type": "string", "description": "Path on reddit.com." }, "votes": { "type": "number", "description": "Score (upvotes minus downvotes)." }, "num_comments": { "type": "number", "description": "Comment count when fetched." }, "created_at": { "type": "string", "description": "Posted at, e.g. `2026-05-07T10:59:35.000+0000`." }, "created_at_iso": { "type": "string", "description": "Posted at, ISO 8601." }, "nsfw": { "type": "boolean", "description": "Marked NSFW." }, "spoiler": { "type": "boolean", "description": "Marked as a spoiler." }, "is_crosspost": { "type": "boolean", "description": "Always false: search results don't say whether a post is a crosspost." }, "thumbnail": { "description": "Preview image URL; null for posts without media.", "type": [ "string", "null" ] }, "thumbnail_blurred": { "type": "boolean", "description": "Always false: search results don't include it." }, "position": { "type": "number", "description": "Rank in the results, from 0." }, "relative_position": { "type": "number", "description": "Rank as Reddit reports it; usually equal to position." }, "subreddit": { "type": "object", "properties": { "id": { "description": "Subreddit fullname, `t5_` + id.", "type": [ "string", "null" ] }, "name": { "type": "string", "description": "Subreddit name without r/." }, "nsfw": { "type": "boolean", "description": "The subreddit is NSFW." }, "quarantined": { "type": "boolean", "description": "The subreddit is quarantined." }, "icon": { "description": "Subreddit icon URL, when the result shows one.", "type": [ "string", "null" ] }, "banner": { "description": "Always null here; get it from subreddit details.", "type": [ "string", "null" ] }, "description": { "description": "Always null here; get it from subreddit details.", "type": [ "string", "null" ] }, "weekly_visitors": { "description": "Always null here; get it from subreddit details.", "type": [ "number", "null" ] }, "weekly_contributions": { "description": "Always null here; get it from subreddit details.", "type": [ "number", "null" ] } }, "required": [ "id", "name", "nsfw", "quarantined", "icon", "banner", "description", "weekly_visitors", "weekly_contributions" ], "additionalProperties": false, "description": "The subreddit the post is in." } }, "required": [ "id", "post_id", "title", "url", "permalink", "votes", "num_comments", "created_at", "created_at_iso", "nsfw", "spoiler", "is_crosspost", "thumbnail", "thumbnail_blurred", "position", "relative_position", "subreddit" ], "additionalProperties": false }, "description": "Matching posts, best match first (or in `sort` order)." }, "cursor": { "description": "Pass as `cursor` for the next page. null on the last page.", "type": [ "string", "null" ] } }, "required": [ "success", "credits_remaining", "credits_charged", "posts", "cursor" ], "additionalProperties": false } } } }, "default": { "description": "Error. Not charged, except the endpoint's own 4xx answers such as not_found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/reddit/search": { "get": { "operationId": "reddit_search", "tags": [ "Reddit" ], "summary": "Search Reddit", "description": "Search all of Reddit for posts matching a keyword.\n\nUse it for brand monitoring and finding where a topic is discussed. Results have no body text or link; pass https://www.reddit.com + `permalink` as `url` to post comments (reddit_post_comments) for the full post. Posts only, no comment search.\n\nSite-wide post search, like reddit.com/search: title, author, subreddit, score, comment count and date.\n\n**Pagination.** Pass the response's `after` back as `after`; it's null at the end.\n\nCost: 1 credit.", "externalDocs": { "url": "https://lurkapi.com/docs/reddit/search" }, "x-credits": 1, "parameters": [ { "name": "query", "in": "query", "required": true, "description": "Keywords, e.g. `claude mcp`.", "schema": { "type": "string", "minLength": 1, "description": "Keywords, e.g. `claude mcp`." }, "example": "claude mcp" }, { "name": "filter", "in": "query", "required": false, "description": "What to search. Only `posts` for now; comment search isn't supported yet.", "schema": { "description": "What to search. Only `posts` for now; comment search isn't supported yet.", "default": "posts", "type": "string", "enum": [ "posts" ] } }, { "name": "sort", "in": "query", "required": false, "description": "Result order.", "schema": { "description": "Result order.", "default": "relevance", "type": "string", "enum": [ "relevance", "new", "top", "comment_count" ] } }, { "name": "timeframe", "in": "query", "required": false, "description": "Only posts from the last hour, day, week, month, year, or all time.", "schema": { "description": "Only posts from the last hour, day, week, month, year, or all time.", "default": "all", "type": "string", "enum": [ "all", "hour", "day", "week", "month", "year" ] } }, { "name": "after", "in": "query", "required": false, "description": "The `after` from the previous response, to get the next page.", "schema": { "description": "The `after` from the previous response, to get the next page.", "type": "string" } }, { "name": "trim", "in": "query", "required": false, "description": "Has no effect here: search results have no HTML body to drop.", "schema": { "description": "Has no effect here: search results have no HTML body to drop.", "default": "false", "type": "string", "enum": [ "true", "false" ] } } ], "responses": { "200": { "description": "Search all of Reddit for posts matching a keyword.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "const": true, "description": "Always true here; errors have `success: false`." }, "credits_remaining": { "type": "number", "description": "Your balance after this call. On anonymous playground calls: free tries left today." }, "credits_charged": { "type": "number", "description": "Credits this call cost; 0 on free endpoints. On anonymous playground calls: tries used (1)." }, "posts": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Post id. Pass the post's URL to post comments for the full post." }, "name": { "type": "string", "description": "Fullname, `t3_` + id." }, "title": { "type": "string", "description": "Post title." }, "author": { "description": "Username, without u/; null if unknown.", "type": [ "string", "null" ] }, "author_fullname": { "description": "Author's account fullname, `t2_` + id.", "type": [ "string", "null" ] }, "subreddit": { "type": "string", "description": "Subreddit name without r/." }, "subreddit_id": { "description": "Subreddit fullname, `t5_` + id.", "type": [ "string", "null" ] }, "subreddit_name_prefixed": { "type": "string", "description": "e.g. `r/ClaudeAI`." }, "quarantine": { "type": "boolean", "description": "The subreddit is quarantined." }, "permalink": { "description": "Path on reddit.com; prepend https://www.reddit.com.", "type": [ "string", "null" ] }, "score": { "type": "number", "description": "Upvotes minus downvotes." }, "ups": { "type": "number", "description": "Same as score." }, "num_comments": { "type": "number", "description": "Comment count when fetched." }, "created": { "type": "number", "description": "Posted at, Unix seconds." }, "created_utc": { "type": "number", "description": "Posted at, Unix seconds." }, "created_at_iso": { "type": "string", "description": "Posted at, ISO 8601." }, "over_18": { "type": "boolean", "description": "Marked NSFW." }, "spoiler": { "type": "boolean", "description": "Marked as a spoiler." }, "thumbnail": { "description": "Preview image URL; null for posts without media.", "type": [ "string", "null" ] } }, "required": [ "id", "name", "title", "author", "author_fullname", "subreddit", "subreddit_id", "subreddit_name_prefixed", "quarantine", "permalink", "score", "ups", "num_comments", "created", "created_utc", "created_at_iso", "over_18", "spoiler", "thumbnail" ], "additionalProperties": false }, "description": "Matching posts, in `sort` order." }, "after": { "description": "Pass as `after` for the next page. null on the last page.", "type": [ "string", "null" ] } }, "required": [ "success", "credits_remaining", "credits_charged", "posts", "after" ], "additionalProperties": false } } } }, "default": { "description": "Error. Not charged, except the endpoint's own 4xx answers such as not_found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/reddit/post/comments": { "get": { "operationId": "reddit_post_comments", "tags": [ "Reddit" ], "summary": "Post comments", "description": "A Reddit post and its comment thread, with nested replies.\n\nUse it to read a thread: the post plus comments, best first, with replies nested under `replies.items`. Where `more.has_more` is true, pass `more.next_cursor` as `cursor` with the same `url` to load more.\n\nGood for what people really think: objections, feature requests, the words customers use.\n\n**Loading more.** Reddit loads long threads in batches. Wherever `more.has_more` is true (at the top level, or inside any comment's `replies`), pass that `more.next_cursor` as `cursor` with the same `url` to load the batch. Cursor responses have `post: null`.\n\nUnknown or removed posts return 404 `not_found`.\n\nCost: 1 credit.", "externalDocs": { "url": "https://lurkapi.com/docs/reddit/post-comments" }, "x-credits": 1, "parameters": [ { "name": "url", "in": "query", "required": true, "description": "The post's URL, e.g. `https://www.reddit.com/r/marketing/comments/1wsx466/`. A /r/… path works too.", "schema": { "type": "string", "description": "The post's URL, e.g. `https://www.reddit.com/r/marketing/comments/1wsx466/`. A /r/… path works too." }, "example": "https://www.reddit.com/r/marketing/comments/1wsx466/want_to_become_an_llm_expert_in_marketing_where/" }, { "name": "cursor", "in": "query", "required": false, "description": "A `more.next_cursor` from a previous response, to load that batch of comments.", "schema": { "description": "A `more.next_cursor` from a previous response, to load that batch of comments.", "type": "string" } }, { "name": "trim", "in": "query", "required": false, "description": "`true` omits the post's `selftext_html`.", "schema": { "description": "`true` omits the post's `selftext_html`.", "default": "false", "type": "string", "enum": [ "true", "false" ] } } ], "responses": { "200": { "description": "A Reddit post and its comment thread, with nested replies.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "const": true, "description": "Always true here; errors have `success: false`." }, "credits_remaining": { "type": "number", "description": "Your balance after this call. On anonymous playground calls: free tries left today." }, "credits_charged": { "type": "number", "description": "Credits this call cost; 0 on free endpoints. On anonymous playground calls: tries used (1)." }, "post": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "description": "Post id, e.g. `1wtfnyr`." }, "name": { "type": "string", "description": "Fullname, `t3_` + id. Subreddit listings paginate with it." }, "title": { "type": "string", "description": "Post title." }, "author": { "description": "Username, without u/; null if unknown.", "type": [ "string", "null" ] }, "author_fullname": { "description": "Author's account fullname, `t2_` + id; null if unknown.", "type": [ "string", "null" ] }, "subreddit": { "type": "string", "description": "Subreddit name without r/, e.g. `marketing`." }, "subreddit_id": { "description": "Subreddit fullname, `t5_` + id.", "type": [ "string", "null" ] }, "subreddit_name_prefixed": { "description": "e.g. `r/marketing`.", "type": [ "string", "null" ] }, "permalink": { "type": "string", "description": "Path on reddit.com; prepend https://www.reddit.com." }, "url": { "type": "string", "description": "The link a link post points to, or the post itself for text posts." }, "url_overridden_by_dest": { "description": "Outbound link, on link posts only.", "type": "string" }, "domain": { "description": "`self.` for text posts, else the linked site.", "type": [ "string", "null" ] }, "selftext": { "type": "string", "description": "Post body as plain text. Empty for link posts." }, "selftext_html": { "description": "Post body as HTML. Omitted with trim=true.", "type": [ "string", "null" ] }, "score": { "type": "number", "description": "Upvotes minus downvotes." }, "ups": { "type": "number", "description": "Same as score." }, "upvote_ratio": { "description": "Share of votes that are upvotes, 0–1.", "type": [ "number", "null" ] }, "num_comments": { "type": "number", "description": "Comment count when fetched." }, "created": { "type": "number", "description": "Posted at, Unix seconds." }, "created_utc": { "type": "number", "description": "Posted at, Unix seconds." }, "is_self": { "type": "boolean", "description": "A text post rather than a link." }, "is_video": { "type": "boolean", "description": "A video post." }, "is_gallery": { "description": "Present (true) on image galleries; absent otherwise.", "type": "boolean" }, "over_18": { "type": "boolean", "description": "Marked NSFW." }, "spoiler": { "type": "boolean", "description": "Marked as a spoiler." }, "stickied": { "type": "boolean", "description": "Pinned by moderators." }, "locked": { "type": "boolean", "description": "Locked: no new comments allowed." }, "link_flair_text": { "description": "Post flair, e.g. \"Question\"; null without flair.", "type": [ "string", "null" ] }, "link_flair_background_color": { "description": "Flair color as a hex code, e.g. #94E044; null without flair.", "type": [ "string", "null" ] }, "thumbnail": { "description": "Preview image URL; null for posts without media.", "type": [ "string", "null" ] }, "total_awards_received": { "type": "number", "description": "Awards the post received." } }, "required": [ "id", "name", "title", "author", "author_fullname", "subreddit", "subreddit_id", "subreddit_name_prefixed", "permalink", "url", "domain", "selftext", "score", "ups", "upvote_ratio", "num_comments", "created", "created_utc", "is_self", "is_video", "over_18", "spoiler", "stickied", "locked", "link_flair_text", "link_flair_background_color", "thumbnail", "total_awards_received" ], "additionalProperties": false }, { "type": "null" } ], "description": "The post. null on cursor responses." }, "comments": { "type": "array", "items": { "$ref": "#/components/schemas/RedditComment" }, "description": "Top-level comments, each with nested `replies`." }, "more": { "type": "object", "properties": { "has_more": { "type": "boolean", "description": "Whether there are more comments to load here." }, "next_cursor": { "description": "Pass as `cursor` (with the same url) to load them; null when has_more is false.", "type": [ "string", "null" ] } }, "required": [ "has_more", "next_cursor" ], "additionalProperties": false, "description": "More comments that weren't loaded yet." } }, "required": [ "success", "credits_remaining", "credits_charged", "post", "comments", "more" ], "additionalProperties": false } } } }, "404": { "description": "not_found: The endpoint, or the thing you asked for (ad, post, subreddit), doesn't exist. Charged when the platform was checked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error. Not charged, except the endpoint's own 4xx answers such as not_found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/youtube/video": { "get": { "operationId": "youtube_video", "tags": [ "YouTube" ], "summary": "Video details", "description": "A video's or Short's title, description, exact views and likes, publish date, length, tags, chapters and channel.\n\nUse it to track how a video performs or to pull its metadata: exact view and like counts, the full description and its links, tags, category, chapters, the \"Most replayed\" graph and the videos YouTube recommends next. Works for Shorts too (`type: \"short\"`).\n\nThe comment count is rounded the way YouTube shows it; video comments returns the exact total. For what's said in the video, use video transcript.\n\nOnce in a while YouTube's player refuses us: then `type`, `durationMs`, `durationFormatted`, `keywords`, `genre`, `publishDate`, `uploadDate`, `isFamilySafe` and `isUnlisted` are null and everything else is still filled in.\n\nPrivate, removed and unknown videos return 404 `not_found`.\n\nCost: 1 credit.", "externalDocs": { "url": "https://lurkapi.com/docs/youtube/video" }, "x-credits": 1, "parameters": [ { "name": "url", "in": "query", "required": true, "description": "The video's URL (watch, youtu.be, /shorts/, /live/ or /embed/ links all work) or its 11-character id, e.g. `https://www.youtube.com/watch?v=dQw4w9WgXcQ`.", "schema": { "type": "string", "description": "The video's URL (watch, youtu.be, /shorts/, /live/ or /embed/ links all work) or its 11-character id, e.g. `https://www.youtube.com/watch?v=dQw4w9WgXcQ`." }, "example": "https://www.youtube.com/watch?v=dQw4w9WgXcQ" } ], "responses": { "200": { "description": "A video's or Short's title, description, exact views and likes, publish date, length, tags, chapters and channel.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "const": true, "description": "Always true here; errors have `success: false`." }, "credits_remaining": { "type": "number", "description": "Your balance after this call. On anonymous playground calls: free tries left today." }, "credits_charged": { "type": "number", "description": "Credits this call cost; 0 on free endpoints. On anonymous playground calls: tries used (1)." }, "id": { "type": "string", "description": "Video id, e.g. `dQw4w9WgXcQ`." }, "type": { "anyOf": [ { "type": "string", "enum": [ "video", "short" ] }, { "type": "null" } ], "description": "`short` for YouTube Shorts, else `video`. null in the rare case the player details were unavailable (see `durationMs`)." }, "url": { "type": "string", "description": "Canonical link: /shorts/ for Shorts, /watch?v= otherwise." }, "title": { "type": "string", "description": "Video title." }, "description": { "type": "string", "description": "Full description, plain text." }, "descriptionLinks": { "type": "array", "items": { "type": "object", "properties": { "text": { "type": "string", "description": "The link as it appears in the description." }, "url": { "type": "string", "description": "Where it goes (YouTube's redirect wrapper removed)." } }, "required": [ "text", "url" ], "additionalProperties": false }, "description": "Outbound links in the description, in order." }, "thumbnail": { "type": "string", "description": "Largest thumbnail URL." }, "viewCountText": { "description": "Views as YouTube shows them, e.g. \"1,821,613,271 views\".", "type": [ "string", "null" ] }, "viewCountInt": { "description": "Exact view count.", "type": [ "number", "null" ] }, "likeCountText": { "description": "Likes as YouTube shows them, e.g. \"19M\"; null when the creator hides likes.", "type": [ "string", "null" ] }, "likeCountInt": { "description": "Exact like count. null when the creator hides likes.", "type": [ "number", "null" ] }, "commentCountText": { "description": "Comments as YouTube shows them, e.g. \"2.4M\"; null when comments are off.", "type": [ "string", "null" ] }, "commentCountInt": { "description": "Comment count from that text, so rounded above 1,000 (2.4M → 2400000). The comments endpoint returns the exact total.", "type": [ "number", "null" ] }, "publishDate": { "description": "Published at, ISO 8601 with YouTube's offset, e.g. `2009-10-24T23:57:33-07:00`. null if unavailable.", "type": [ "string", "null" ] }, "uploadDate": { "description": "Uploaded at, ISO 8601 (differs from publishDate for scheduled videos and premieres). null if unavailable.", "type": [ "string", "null" ] }, "publishDateText": { "description": "The date line under the video, e.g. \"Oct 24, 2009\" or \"Premiered 3 hours ago\".", "type": [ "string", "null" ] }, "channel": { "type": "object", "properties": { "id": { "description": "Channel id, `UC…`.", "type": [ "string", "null" ] }, "url": { "description": "Channel page, e.g. `https://www.youtube.com/@RickAstleyYT`.", "type": [ "string", "null" ] }, "handle": { "description": "Handle without the @, e.g. `RickAstleyYT`; null if YouTube shows none.", "type": [ "string", "null" ] }, "title": { "description": "Channel name.", "type": [ "string", "null" ] }, "subscriberCountText": { "description": "Subscribers as YouTube shows them, e.g. \"4.55M subscribers\".", "type": [ "string", "null" ] }, "subscriberCount": { "description": "Subscribers as a number, from that rounded text (4.55M → 4550000).", "type": [ "number", "null" ] }, "isVerified": { "type": "boolean", "description": "Has a verified or official artist badge." }, "avatar": { "description": "Channel avatar URL.", "type": [ "string", "null" ] } }, "required": [ "id", "url", "handle", "title", "subscriberCountText", "subscriberCount", "isVerified", "avatar" ], "additionalProperties": false, "description": "The channel that posted it." }, "chapters": { "type": "array", "items": { "type": "object", "properties": { "title": { "type": "string", "description": "Chapter title." }, "startMs": { "type": "number", "description": "Where the chapter starts, ms from the start of the video." }, "thumbnail": { "description": "Chapter thumbnail URL.", "type": [ "string", "null" ] } }, "required": [ "title", "startMs", "thumbnail" ], "additionalProperties": false }, "description": "Chapters from the description (or YouTube's automatic ones), in order. Empty if the video has none." }, "keywords": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ], "description": "The creator's tags. null if unavailable." }, "genre": { "description": "YouTube category, e.g. \"Music\" or \"Education\". null if unavailable.", "type": [ "string", "null" ] }, "durationMs": { "description": "Length in ms. null if unavailable: this and the other fields marked \"if unavailable\" come from YouTube's player, which occasionally refuses us; the rest of the response is still complete.", "type": [ "number", "null" ] }, "durationFormatted": { "description": "Length as `HH:MM:SS`, e.g. \"00:03:33\". null if unavailable.", "type": [ "string", "null" ] }, "isFamilySafe": { "description": "YouTube considers it family safe. null if unavailable.", "type": [ "boolean", "null" ] }, "isUnlisted": { "description": "Unlisted (only people with the link can find it). null if unavailable.", "type": [ "boolean", "null" ] }, "most_replayed": { "anyOf": [ { "type": "object", "properties": { "markers": { "type": "array", "items": { "type": "object", "properties": { "startMillis": { "type": "number", "description": "Start of this slice of the video, ms." }, "durationMillis": { "type": "number", "description": "Length of the slice, ms." }, "intensityScoreNormalized": { "type": "number", "description": "How often this slice is replayed, 0–1 (1 = the most replayed slice)." } }, "required": [ "startMillis", "durationMillis", "intensityScoreNormalized" ], "additionalProperties": false }, "description": "The replay graph over the timeline, usually 100 equal slices." }, "ranges": { "type": "array", "items": { "type": "object", "properties": { "visibleTimeRangeStartMillis": { "type": "number", "description": "Start of the highlighted range, ms." }, "visibleTimeRangeEndMillis": { "type": "number", "description": "End of the highlighted range, ms." }, "decorationTimeMillis": { "type": "number", "description": "The peak YouTube points at, ms." }, "label": { "description": "YouTube's label, e.g. \"Most replayed\".", "type": [ "string", "null" ] } }, "required": [ "visibleTimeRangeStartMillis", "visibleTimeRangeEndMillis", "decorationTimeMillis", "label" ], "additionalProperties": false }, "description": "Ranges YouTube highlights as most replayed." } }, "required": [ "markers", "ranges" ], "additionalProperties": false }, { "type": "null" } ], "description": "The \"Most replayed\" graph. null when YouTube doesn't show one (newer or less-watched videos)." }, "watchNextVideos": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Video id." }, "title": { "description": "Video title.", "type": [ "string", "null" ] }, "thumbnail": { "description": "Thumbnail URL.", "type": [ "string", "null" ] }, "channel": { "type": "object", "properties": { "id": { "description": "Channel id, `UC…`.", "type": [ "string", "null" ] }, "url": { "description": "Channel page, e.g. `https://www.youtube.com/@RickAstleyYT`.", "type": [ "string", "null" ] }, "handle": { "description": "Handle without the @, e.g. `RickAstleyYT`; null if YouTube shows none.", "type": [ "string", "null" ] }, "title": { "description": "Channel name.", "type": [ "string", "null" ] } }, "required": [ "id", "url", "handle", "title" ], "additionalProperties": false, "description": "The channel that posted it." }, "publishedTimeText": { "description": "When it was posted, relative, e.g. \"3 months ago\".", "type": [ "string", "null" ] }, "viewCountText": { "description": "Views as YouTube shows them, e.g. \"3.9M\".", "type": [ "string", "null" ] }, "viewCountInt": { "description": "Views from that rounded text (3.9M → 3900000).", "type": [ "number", "null" ] }, "lengthText": { "description": "Length as shown on the thumbnail, e.g. \"4:05\".", "type": [ "string", "null" ] }, "lengthInSeconds": { "description": "Length in seconds.", "type": [ "number", "null" ] }, "videoUrl": { "type": "string", "description": "Link to the video." } }, "required": [ "id", "title", "thumbnail", "channel", "publishedTimeText", "viewCountText", "viewCountInt", "lengthText", "lengthInSeconds", "videoUrl" ], "additionalProperties": false }, "description": "The \"Up next\" videos YouTube recommends beside this one (videos only, no mixes or playlists)." } }, "required": [ "success", "credits_remaining", "credits_charged", "id", "type", "url", "title", "description", "descriptionLinks", "thumbnail", "viewCountText", "viewCountInt", "likeCountText", "likeCountInt", "commentCountText", "commentCountInt", "publishDate", "uploadDate", "publishDateText", "channel", "chapters", "keywords", "genre", "durationMs", "durationFormatted", "isFamilySafe", "isUnlisted", "most_replayed", "watchNextVideos" ], "additionalProperties": false } } } }, "404": { "description": "not_found: The endpoint, or the thing you asked for (ad, post, subreddit), doesn't exist. Charged when the platform was checked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error. Not charged, except the endpoint's own 4xx answers such as not_found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/youtube/video/transcript": { "get": { "operationId": "youtube_transcript", "tags": [ "YouTube" ], "summary": "Video transcript", "description": "What's said in a video or Short: its captions as timed segments and as one block of text.\n\nUse it to turn a video into text for summaries, search, research or repurposing. It reads the video's captions: the creator's own or YouTube's auto-generated ones (`isGenerated` tells them apart).\n\nPick a language with `language` (e.g. `es`); without it you get English when the video has it, else the video's main language. `availableLanguages` lists every caption track. YouTube's machine translation isn't available, so a language the video has no captions in returns 404.\n\nVideos without captions, and private or removed ones, return 404 `not_found`.\n\nCost: 1 credit.", "externalDocs": { "url": "https://lurkapi.com/docs/youtube/transcript" }, "x-credits": 1, "parameters": [ { "name": "url", "in": "query", "required": true, "description": "The video's URL (watch, youtu.be, /shorts/, /live/ or /embed/ links all work) or its 11-character id, e.g. `https://www.youtube.com/watch?v=dQw4w9WgXcQ`.", "schema": { "type": "string", "description": "The video's URL (watch, youtu.be, /shorts/, /live/ or /embed/ links all work) or its 11-character id, e.g. `https://www.youtube.com/watch?v=dQw4w9WgXcQ`." }, "example": "https://www.youtube.com/watch?v=dQw4w9WgXcQ" }, { "name": "language", "in": "query", "required": false, "description": "Language code, e.g. `en`, `es` or `pt-BR`. `pt` also matches `pt-BR`. Default: English if the video has it, else its main language.", "schema": { "description": "Language code, e.g. `en`, `es` or `pt-BR`. `pt` also matches `pt-BR`. Default: English if the video has it, else its main language.", "type": "string", "pattern": "^[A-Za-z]{2,3}(-[A-Za-z0-9]{2,8})*$" } } ], "responses": { "200": { "description": "What's said in a video or Short: its captions as timed segments and as one block of text.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "const": true, "description": "Always true here; errors have `success: false`." }, "credits_remaining": { "type": "number", "description": "Your balance after this call. On anonymous playground calls: free tries left today." }, "credits_charged": { "type": "number", "description": "Credits this call cost; 0 on free endpoints. On anonymous playground calls: tries used (1)." }, "videoId": { "type": "string", "description": "Video id." }, "url": { "type": "string", "description": "Link to the video." }, "language": { "type": "string", "description": "Language of the transcript, e.g. \"English\"." }, "languageCode": { "type": "string", "description": "Its code as YouTube names the track, e.g. `en` or `pt-BR`." }, "isGenerated": { "type": "boolean", "description": "Auto-generated by YouTube's speech recognition, rather than captions the creator uploaded." }, "transcript": { "type": "array", "items": { "type": "object", "properties": { "text": { "type": "string", "description": "What's said in this segment." }, "startMs": { "type": "number", "description": "Segment start, ms from the start of the video." }, "endMs": { "type": "number", "description": "Segment end, ms; never past the next segment's start." }, "startTimeText": { "type": "string", "description": "Segment start as a timestamp, e.g. \"1:23\"." } }, "required": [ "text", "startMs", "endMs", "startTimeText" ], "additionalProperties": false }, "description": "Timed segments, in order." }, "transcript_only_text": { "type": "string", "description": "The whole transcript as one string, without timestamps." }, "availableLanguages": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "description": "Language code; pass it as `language`." }, "name": { "type": "string", "description": "Language name, e.g. \"English\"." }, "isGenerated": { "type": "boolean", "description": "Auto-generated rather than uploaded by the creator." } }, "required": [ "code", "name", "isGenerated" ], "additionalProperties": false }, "description": "Every caption track the video has." } }, "required": [ "success", "credits_remaining", "credits_charged", "videoId", "url", "language", "languageCode", "isGenerated", "transcript", "transcript_only_text", "availableLanguages" ], "additionalProperties": false } } } }, "404": { "description": "not_found: The endpoint, or the thing you asked for (ad, post, subreddit), doesn't exist. Charged when the platform was checked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error. Not charged, except the endpoint's own 4xx answers such as not_found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/youtube/video/comments": { "get": { "operationId": "youtube_comments", "tags": [ "YouTube" ], "summary": "Video comments", "description": "A video's comments, top or newest first, with likes, reply counts and who wrote them.\n\nUse it for audience research and sentiment: what viewers say, which comments get the most likes, and what the creator pinned or hearted. About 20 comments per page; the first page also has the exact `commentCount`.\n\n**Pagination.** Pass the response's `continuationToken` back as `continuationToken` (with the same `url`) for the next page; it's null at the end. YouTube stops at about 1,000 top comments, or a few thousand newest ones.\n\n**Replies.** Comments with replies have a `repliesContinuationToken`; pass it to comment replies.\n\nVideos with comments turned off, and unknown videos, return an empty `comments` list.\n\nCost: 1 credit.", "externalDocs": { "url": "https://lurkapi.com/docs/youtube/comments" }, "x-credits": 1, "parameters": [ { "name": "url", "in": "query", "required": true, "description": "The video's URL (watch, youtu.be, /shorts/, /live/ or /embed/ links all work) or its 11-character id, e.g. `https://www.youtube.com/watch?v=dQw4w9WgXcQ`.", "schema": { "type": "string", "description": "The video's URL (watch, youtu.be, /shorts/, /live/ or /embed/ links all work) or its 11-character id, e.g. `https://www.youtube.com/watch?v=dQw4w9WgXcQ`." }, "example": "https://www.youtube.com/watch?v=dQw4w9WgXcQ" }, { "name": "order", "in": "query", "required": false, "description": "`top` (YouTube's ranking) or `newest` first.", "schema": { "description": "`top` (YouTube's ranking) or `newest` first.", "default": "top", "type": "string", "enum": [ "top", "newest" ] } }, { "name": "continuationToken", "in": "query", "required": false, "description": "The `continuationToken` from the previous response, to get the next page.", "schema": { "description": "The `continuationToken` from the previous response, to get the next page.", "type": "string", "minLength": 1 } } ], "responses": { "200": { "description": "A video's comments, top or newest first, with likes, reply counts and who wrote them.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "const": true, "description": "Always true here; errors have `success: false`." }, "credits_remaining": { "type": "number", "description": "Your balance after this call. On anonymous playground calls: free tries left today." }, "credits_charged": { "type": "number", "description": "Credits this call cost; 0 on free endpoints. On anonymous playground calls: tries used (1)." }, "comments": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Comment id. Replies are `.`." }, "content": { "type": "string", "description": "Comment text." }, "publishedTimeText": { "type": "string", "description": "When it was posted, as YouTube shows it, e.g. \"3 days ago\" or \"6 years ago (edited)\"." }, "publishedTime": { "description": "Approximate post time, ISO 8601, worked out from publishedTimeText: only as precise as that text (\"6 years ago\" is ±6 months).", "type": [ "string", "null" ] }, "replyLevel": { "type": "number", "description": "0 for a comment, 1 for a reply." }, "author": { "type": "object", "properties": { "name": { "type": "string", "description": "Author's handle, e.g. `@YouTube`." }, "channelId": { "description": "Author's channel id, `UC…`.", "type": [ "string", "null" ] }, "isVerified": { "type": "boolean", "description": "The author has a verified badge." }, "isCreator": { "type": "boolean", "description": "The author is the video's creator." }, "avatarUrl": { "description": "Author's avatar URL.", "type": [ "string", "null" ] }, "channelUrl": { "description": "Author's channel page.", "type": [ "string", "null" ] } }, "required": [ "name", "channelId", "isVerified", "isCreator", "avatarUrl", "channelUrl" ], "additionalProperties": false, "description": "Who wrote it." }, "engagement": { "type": "object", "properties": { "likes": { "type": "number", "description": "Likes; YouTube rounds above 1,000 (321K → 321000)." }, "replies": { "type": "number", "description": "Number of replies." } }, "required": [ "likes", "replies" ], "additionalProperties": false, "description": "Likes and replies." }, "repliesContinuationToken": { "description": "Pass as `continuationToken` to comment replies to read the replies. null when there are none (and always on replies).", "type": [ "string", "null" ] }, "isPinned": { "type": "boolean", "description": "Pinned by the creator." }, "isHearted": { "type": "boolean", "description": "Hearted by the creator." } }, "required": [ "id", "content", "publishedTimeText", "publishedTime", "replyLevel", "author", "engagement", "repliesContinuationToken", "isPinned", "isHearted" ], "additionalProperties": false }, "description": "One page of comments, in the requested order." }, "continuationToken": { "description": "Pass as `continuationToken` for the next page. null on the last page.", "type": [ "string", "null" ] }, "commentCount": { "description": "Exact number of comments on the video (replies included). First page only; null on later pages.", "type": [ "number", "null" ] } }, "required": [ "success", "credits_remaining", "credits_charged", "comments", "continuationToken", "commentCount" ], "additionalProperties": false } } } }, "default": { "description": "Error. Not charged, except the endpoint's own 4xx answers such as not_found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/youtube/video/comment/replies": { "get": { "operationId": "youtube_comment_replies", "tags": [ "YouTube" ], "summary": "Comment replies", "description": "The replies to one YouTube comment.\n\nUse it to read the conversation under a comment. Pass a comment's `repliesContinuationToken` from video comments as `continuationToken`. About 10 replies on the first page and up to 50 on later ones, oldest first.\n\n**Pagination.** Pass the response's `continuationToken` back as `continuationToken` for more replies; it's null at the end.\n\nCost: 1 credit.", "externalDocs": { "url": "https://lurkapi.com/docs/youtube/comment-replies" }, "x-credits": 1, "parameters": [ { "name": "continuationToken", "in": "query", "required": true, "description": "A comment's `repliesContinuationToken` from video comments, or the `continuationToken` from a previous replies page.", "schema": { "type": "string", "minLength": 1, "description": "A comment's `repliesContinuationToken` from video comments, or the `continuationToken` from a previous replies page." }, "example": "Eg0SC2RRdzR3OVdnWGNRGAYygwEaUBIaVWd6Z2UzNDBkQmdCNzVoV0JtNTRBYUFCQWciAggAKhhVQ3VBWEZrZ3N3MUw3eGFDZm5kNUpKT3cyC2RRdzR3OVdnWGNRQABICoIBAggBQi9jb21tZW50LXJlcGxpZXMtaXRlbS1VZ3pnZTM0MGRCZ0I3NWhXQm01NEFhQUJBZw%3D%3D" } ], "responses": { "200": { "description": "The replies to one YouTube comment.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "const": true, "description": "Always true here; errors have `success: false`." }, "credits_remaining": { "type": "number", "description": "Your balance after this call. On anonymous playground calls: free tries left today." }, "credits_charged": { "type": "number", "description": "Credits this call cost; 0 on free endpoints. On anonymous playground calls: tries used (1)." }, "comments": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Comment id. Replies are `.`." }, "content": { "type": "string", "description": "Comment text." }, "publishedTimeText": { "type": "string", "description": "When it was posted, as YouTube shows it, e.g. \"3 days ago\" or \"6 years ago (edited)\"." }, "publishedTime": { "description": "Approximate post time, ISO 8601, worked out from publishedTimeText: only as precise as that text (\"6 years ago\" is ±6 months).", "type": [ "string", "null" ] }, "replyLevel": { "type": "number", "description": "0 for a comment, 1 for a reply." }, "author": { "type": "object", "properties": { "name": { "type": "string", "description": "Author's handle, e.g. `@YouTube`." }, "channelId": { "description": "Author's channel id, `UC…`.", "type": [ "string", "null" ] }, "isVerified": { "type": "boolean", "description": "The author has a verified badge." }, "isCreator": { "type": "boolean", "description": "The author is the video's creator." }, "avatarUrl": { "description": "Author's avatar URL.", "type": [ "string", "null" ] }, "channelUrl": { "description": "Author's channel page.", "type": [ "string", "null" ] } }, "required": [ "name", "channelId", "isVerified", "isCreator", "avatarUrl", "channelUrl" ], "additionalProperties": false, "description": "Who wrote it." }, "engagement": { "type": "object", "properties": { "likes": { "type": "number", "description": "Likes; YouTube rounds above 1,000 (321K → 321000)." }, "replies": { "type": "number", "description": "Number of replies." } }, "required": [ "likes", "replies" ], "additionalProperties": false, "description": "Likes and replies." }, "repliesContinuationToken": { "description": "Pass as `continuationToken` to comment replies to read the replies. null when there are none (and always on replies).", "type": [ "string", "null" ] }, "isPinned": { "type": "boolean", "description": "Pinned by the creator." }, "isHearted": { "type": "boolean", "description": "Hearted by the creator." } }, "required": [ "id", "content", "publishedTimeText", "publishedTime", "replyLevel", "author", "engagement", "repliesContinuationToken", "isPinned", "isHearted" ], "additionalProperties": false }, "description": "One page of replies (`replyLevel: 1`)." }, "continuationToken": { "description": "Pass as `continuationToken` for more replies. null on the last page.", "type": [ "string", "null" ] } }, "required": [ "success", "credits_remaining", "credits_charged", "comments", "continuationToken" ], "additionalProperties": false } } } }, "default": { "description": "Error. Not charged, except the endpoint's own 4xx answers such as not_found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/youtube/channel": { "get": { "operationId": "youtube_channel", "tags": [ "YouTube" ], "summary": "Channel details", "description": "A channel's subscribers, total views, video count, join date, country, links and description.\n\nUse it to size up a creator: subscribers, lifetime views, number of videos, when they joined, where they're based and the links on their profile. Pass `channelId`, `handle` or a channel `url` (/@handle, /channel/UC…, /c/… and /user/… links all work).\n\nYouTube rounds subscriber counts (519M), so `subscriberCount` is rounded too; `viewCount` and `videoCount` are exact from the about panel. If that panel is unavailable, the header supplies rounded `videoCount`, while views, join date, country and links can be missing. `email` is always null: YouTube only shows business emails to signed-in viewers.\n\nUnknown and terminated channels return 404 `not_found`.\n\nCost: 1 credit.", "externalDocs": { "url": "https://lurkapi.com/docs/youtube/channel" }, "x-credits": 1, "parameters": [ { "name": "channelId", "in": "query", "required": false, "description": "Channel id, e.g. `UCX6OQ3DkcsbYNE6H8uQQuVA`. Pass this or `handle`.", "schema": { "description": "Channel id, e.g. `UCX6OQ3DkcsbYNE6H8uQQuVA`. Pass this or `handle`.", "type": "string" } }, { "name": "handle", "in": "query", "required": false, "description": "Channel handle, with or without the @, e.g. `MrBeast`. Pass this or `channelId`.", "schema": { "description": "Channel handle, with or without the @, e.g. `MrBeast`. Pass this or `channelId`.", "type": "string" }, "example": "MrBeast" }, { "name": "url", "in": "query", "required": false, "description": "Channel URL, e.g. `https://www.youtube.com/@MrBeast`. Instead of `channelId` or `handle`.", "schema": { "description": "Channel URL, e.g. `https://www.youtube.com/@MrBeast`. Instead of `channelId` or `handle`.", "type": "string" } } ], "responses": { "200": { "description": "A channel's subscribers, total views, video count, join date, country, links and description.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "const": true, "description": "Always true here; errors have `success: false`." }, "credits_remaining": { "type": "number", "description": "Your balance after this call. On anonymous playground calls: free tries left today." }, "credits_charged": { "type": "number", "description": "Credits this call cost; 0 on free endpoints. On anonymous playground calls: tries used (1)." }, "channelId": { "type": "string", "description": "Channel id, `UC…`." }, "channel": { "type": "string", "description": "Channel page, e.g. `https://www.youtube.com/@MrBeast` (or /channel/UC… without a handle)." }, "handle": { "description": "Handle without the @, e.g. `MrBeast`; null if the channel has none.", "type": [ "string", "null" ] }, "name": { "type": "string", "description": "Channel name." }, "description": { "type": "string", "description": "The full channel description." }, "avatar": { "anyOf": [ { "type": "object", "properties": { "image": { "type": "object", "properties": { "sources": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string", "description": "Image URL." }, "width": { "type": "number", "description": "Width in pixels." }, "height": { "type": "number", "description": "Height in pixels." } }, "required": [ "url", "width", "height" ], "additionalProperties": false }, "description": "The same picture in several sizes, smallest first." } }, "required": [ "sources" ], "additionalProperties": false, "description": "The picture." } }, "required": [ "image" ], "additionalProperties": false }, { "type": "null" } ], "description": "Channel picture in several sizes (YouTube's own shape). `avatarUrl` is the largest." }, "avatarUrl": { "description": "Largest channel picture URL (900 px).", "type": [ "string", "null" ] }, "banner": { "description": "Largest banner image URL; null without a banner.", "type": [ "string", "null" ] }, "isVerified": { "type": "boolean", "description": "Has YouTube's verified or official artist badge." }, "isFamilySafe": { "type": "boolean", "description": "YouTube marks the channel family safe." }, "subscriberCount": { "description": "Subscribers, rounded as YouTube shows them (519M → 519000000). null when hidden.", "type": [ "number", "null" ] }, "subscriberCountText": { "description": "e.g. \"519M subscribers\".", "type": [ "string", "null" ] }, "videoCount": { "description": "Public videos, Shorts and past streams. Exact from the about panel; rounded as videoCountText if that panel is unavailable.", "type": [ "number", "null" ] }, "videoCountText": { "description": "e.g. \"1,004 videos\".", "type": [ "string", "null" ] }, "viewCount": { "description": "Lifetime views across the channel, exact; null if the about panel is unavailable.", "type": [ "number", "null" ] }, "viewCountText": { "description": "e.g. \"141,227,305,543 views\".", "type": [ "string", "null" ] }, "joinedDate": { "description": "When the channel was created, `YYYY-MM-DD`.", "type": [ "string", "null" ] }, "joinedDateText": { "description": "e.g. \"Joined Feb 19, 2012\".", "type": [ "string", "null" ] }, "country": { "description": "Country the channel lists, e.g. \"United States\"; null if it lists none.", "type": [ "string", "null" ] }, "email": { "type": "null", "description": "Always null: YouTube only shows a channel's business email to signed-in viewers." }, "links": { "type": "array", "items": { "type": "string" }, "description": "The links on the channel's profile (website, socials, store), in the channel's order." }, "twitter": { "description": "The X / Twitter link from `links`, if any.", "type": [ "string", "null" ] }, "instagram": { "description": "The Instagram link from `links`, if any.", "type": [ "string", "null" ] }, "tags": { "description": "The channel's keywords, comma-separated, e.g. \"mrbeast6000, beast, mrbeast\"; null if none.", "type": [ "string", "null" ] }, "keywords": { "type": "array", "items": { "type": "string" }, "description": "The same keywords as a list." } }, "required": [ "success", "credits_remaining", "credits_charged", "channelId", "channel", "handle", "name", "description", "avatar", "avatarUrl", "banner", "isVerified", "isFamilySafe", "subscriberCount", "subscriberCountText", "videoCount", "videoCountText", "viewCount", "viewCountText", "joinedDate", "joinedDateText", "country", "email", "links", "twitter", "instagram", "tags", "keywords" ], "additionalProperties": false } } } }, "404": { "description": "not_found: The endpoint, or the thing you asked for (ad, post, subreddit), doesn't exist. Charged when the platform was checked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error. Not charged, except the endpoint's own 4xx answers such as not_found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/youtube/channel-videos": { "get": { "operationId": "youtube_channel_videos", "tags": [ "YouTube" ], "summary": "Channel videos", "description": "A channel's videos, newest or most popular first, with views, length and upload time.\n\nUse it to see what a creator publishes and what performs: about 30 videos per page from the channel's Videos tab, newest first, or most viewed first with `sort=popular`. Shorts are on their own tab (channel Shorts).\n\nViews are rounded as the channel page shows them (82M views). For exact views, likes, comments and the full description, pass a video's `url` to the video endpoint.\n\n**Pagination.** Pass the response's `continuationToken` back as `continuationToken` for the next page; it's null on the last page.\n\nUnknown channels return 404 `not_found`; a channel without a Videos tab returns an empty list.\n\nCost: 1 credit.", "externalDocs": { "url": "https://lurkapi.com/docs/youtube/channel-videos" }, "x-credits": 1, "parameters": [ { "name": "channelId", "in": "query", "required": false, "description": "Channel id, e.g. `UCX6OQ3DkcsbYNE6H8uQQuVA`. Pass this or `handle`.", "schema": { "description": "Channel id, e.g. `UCX6OQ3DkcsbYNE6H8uQQuVA`. Pass this or `handle`.", "type": "string" } }, { "name": "handle", "in": "query", "required": false, "description": "Channel handle, with or without the @, e.g. `MrBeast`. Pass this or `channelId`.", "schema": { "description": "Channel handle, with or without the @, e.g. `MrBeast`. Pass this or `channelId`.", "type": "string" }, "example": "MrBeast" }, { "name": "sort", "in": "query", "required": false, "description": "Order: `latest` (newest first), `popular` (most viewed) or `oldest`.", "schema": { "description": "Order: `latest` (newest first), `popular` (most viewed) or `oldest`.", "default": "latest", "type": "string", "enum": [ "latest", "popular", "oldest" ] } }, { "name": "continuationToken", "in": "query", "required": false, "description": "The `continuationToken` from the previous response, for the next page. The channel can be left out then.", "schema": { "description": "The `continuationToken` from the previous response, for the next page. The channel can be left out then.", "type": "string" } } ], "responses": { "200": { "description": "A channel's videos, newest or most popular first, with views, length and upload time.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "const": true, "description": "Always true here; errors have `success: false`." }, "credits_remaining": { "type": "number", "description": "Your balance after this call. On anonymous playground calls: free tries left today." }, "credits_charged": { "type": "number", "description": "Credits this call cost; 0 on free endpoints. On anonymous playground calls: tries used (1)." }, "videos": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "const": "video", "description": "Always `video`." }, "id": { "type": "string", "description": "Video id, e.g. `v9QtM6qnG50`." }, "url": { "type": "string", "description": "Watch link. Pass it to the video endpoint for likes, comments, the full description and exact views." }, "title": { "type": "string", "description": "Video title." }, "thumbnail": { "description": "Largest thumbnail URL.", "type": [ "string", "null" ] }, "viewCountText": { "description": "Views as YouTube shows them, e.g. \"82M views\", or \"1,204 watching\" while live.", "type": [ "string", "null" ] }, "viewCountInt": { "description": "viewCountText as a number, rounded whenever YouTube abbreviates it (82M views → 82000000). Use video details for exact views.", "type": [ "number", "null" ] }, "publishedTimeText": { "description": "When it went up, as YouTube shows it, e.g. \"10 days ago\". null for live and upcoming videos.", "type": [ "string", "null" ] }, "publishedTime": { "description": "publishedTimeText as an estimated ISO 8601 time, counted back from when we fetched the page. Only as precise as the text: \"1 year ago\" means sometime that year.", "type": [ "string", "null" ] }, "lengthText": { "description": "Length as shown, e.g. \"19:03\". null for live and upcoming videos.", "type": [ "string", "null" ] }, "lengthSeconds": { "description": "Length in seconds.", "type": [ "number", "null" ] }, "badges": { "type": "array", "items": { "type": "string" }, "description": "Labels YouTube shows on the result, e.g. \"4K\", \"CC\", \"New\" or \"LIVE\". Often empty." } }, "required": [ "type", "id", "url", "title", "thumbnail", "viewCountText", "viewCountInt", "publishedTimeText", "publishedTime", "lengthText", "lengthSeconds", "badges" ], "additionalProperties": false }, "description": "One page of videos, in `sort` order." }, "continuationToken": { "description": "Pass as `continuationToken` for the next page. null on the last page.", "type": [ "string", "null" ] } }, "required": [ "success", "credits_remaining", "credits_charged", "videos", "continuationToken" ], "additionalProperties": false } } } }, "404": { "description": "not_found: The endpoint, or the thing you asked for (ad, post, subreddit), doesn't exist. Charged when the platform was checked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error. Not charged, except the endpoint's own 4xx answers such as not_found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/youtube/channel/shorts": { "get": { "operationId": "youtube_channel_shorts", "tags": [ "YouTube" ], "summary": "Channel Shorts", "description": "A channel's Shorts, newest or most popular first, with titles and view counts.\n\nUse it to track a creator's short-form output: about 48 Shorts per page from the channel's Shorts tab, newest first, or most viewed first with `sort=popular`.\n\nThe Shorts tab only shows title, thumbnail and views. For likes, comments, upload date and length, pass a Short's `url` to the video endpoint; we don't fetch those for every Short, so a page stays one fast request.\n\n**Pagination.** Pass the response's `continuationToken` back as `continuationToken` for the next page; it's null on the last page.\n\nUnknown channels return 404 `not_found`; a channel without Shorts returns an empty list.\n\nCost: 1 credit.", "externalDocs": { "url": "https://lurkapi.com/docs/youtube/channel-shorts" }, "x-credits": 1, "parameters": [ { "name": "channelId", "in": "query", "required": false, "description": "Channel id, e.g. `UCX6OQ3DkcsbYNE6H8uQQuVA`. Pass this or `handle`.", "schema": { "description": "Channel id, e.g. `UCX6OQ3DkcsbYNE6H8uQQuVA`. Pass this or `handle`.", "type": "string" } }, { "name": "handle", "in": "query", "required": false, "description": "Channel handle, with or without the @, e.g. `MrBeast`. Pass this or `channelId`.", "schema": { "description": "Channel handle, with or without the @, e.g. `MrBeast`. Pass this or `channelId`.", "type": "string" }, "example": "MrBeast" }, { "name": "sort", "in": "query", "required": false, "description": "Order: `newest` first, `popular` (most viewed) or `oldest`.", "schema": { "description": "Order: `newest` first, `popular` (most viewed) or `oldest`.", "default": "newest", "type": "string", "enum": [ "newest", "popular", "oldest" ] } }, { "name": "continuationToken", "in": "query", "required": false, "description": "The `continuationToken` from the previous response, for the next page. The channel can be left out then.", "schema": { "description": "The `continuationToken` from the previous response, for the next page. The channel can be left out then.", "type": "string" } } ], "responses": { "200": { "description": "A channel's Shorts, newest or most popular first, with titles and view counts.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "const": true, "description": "Always true here; errors have `success: false`." }, "credits_remaining": { "type": "number", "description": "Your balance after this call. On anonymous playground calls: free tries left today." }, "credits_charged": { "type": "number", "description": "Credits this call cost; 0 on free endpoints. On anonymous playground calls: tries used (1)." }, "shorts": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "const": "short", "description": "Always `short`." }, "id": { "type": "string", "description": "The Short's video id." }, "url": { "type": "string", "description": "`https://www.youtube.com/shorts/`. Pass it to the video endpoint for likes, comments, date and length." }, "title": { "type": "string", "description": "The Short's title." }, "thumbnail": { "description": "Largest (vertical) thumbnail URL.", "type": [ "string", "null" ] }, "viewCountText": { "description": "Views as YouTube shows them, e.g. \"22M views\".", "type": [ "string", "null" ] }, "viewCountInt": { "description": "viewCountText as a number, rounded as shown (22M views → 22000000).", "type": [ "number", "null" ] } }, "required": [ "type", "id", "url", "title", "thumbnail", "viewCountText", "viewCountInt" ], "additionalProperties": false }, "description": "One page of Shorts, in `sort` order." }, "continuationToken": { "description": "Pass as `continuationToken` for the next page. null on the last page.", "type": [ "string", "null" ] } }, "required": [ "success", "credits_remaining", "credits_charged", "shorts", "continuationToken" ], "additionalProperties": false } } } }, "404": { "description": "not_found: The endpoint, or the thing you asked for (ad, post, subreddit), doesn't exist. Charged when the platform was checked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error. Not charged, except the endpoint's own 4xx answers such as not_found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/youtube/search": { "get": { "operationId": "youtube_search", "tags": [ "YouTube" ], "summary": "Search YouTube", "description": "Search YouTube by keyword for videos, Shorts, channels and playlists, with date, length and type filters.\n\nUse it for trend, topic and competitor research: what YouTube's search page shows for a keyword, split into `videos`, `shorts`, `channels`, `playlists` and `lives` (streaming now). About 20 results per page. Narrow it with `type`, `uploadDate`, `duration` (videos only) and `sortBy=popular`.\n\nVideo results carry views as YouTube shows them, a description snippet and the channel. Counts may be rounded; video details returns exact views. Shorts carry title and views only; pass a Short's `url` to the video endpoint for the rest.\n\n**Pagination.** Pass the response's `continuationToken` back as `continuationToken` (with the same query) for the next page; it's null on the last page.\n\nCost: 1 credit.", "externalDocs": { "url": "https://lurkapi.com/docs/youtube/search" }, "x-credits": 1, "parameters": [ { "name": "query", "in": "query", "required": true, "description": "Keywords, e.g. `running shoes`. YouTube's operators work, e.g. `intitle:\"air max\"`.", "schema": { "type": "string", "minLength": 1, "description": "Keywords, e.g. `running shoes`. YouTube's operators work, e.g. `intitle:\"air max\"`." }, "example": "running shoes" }, { "name": "type", "in": "query", "required": false, "description": "What to search for. `all` mixes them like youtube.com.", "schema": { "description": "What to search for. `all` mixes them like youtube.com.", "default": "all", "type": "string", "enum": [ "all", "videos", "shorts", "channels", "playlists" ] } }, { "name": "uploadDate", "in": "query", "required": false, "description": "Only results uploaded in this window.", "schema": { "description": "Only results uploaded in this window.", "default": "any", "type": "string", "enum": [ "any", "today", "this_week", "this_month", "this_year" ] } }, { "name": "duration", "in": "query", "required": false, "description": "Video length. Doesn't apply to Shorts.", "schema": { "description": "Video length. Doesn't apply to Shorts.", "default": "any", "type": "string", "enum": [ "any", "under_3_min", "between_3_and_20_min", "over_20_min" ] } }, { "name": "sortBy", "in": "query", "required": false, "description": "`relevance` (YouTube's default) or `popular` (most viewed first).", "schema": { "description": "`relevance` (YouTube's default) or `popular` (most viewed first).", "default": "relevance", "type": "string", "enum": [ "relevance", "popular" ] } }, { "name": "continuationToken", "in": "query", "required": false, "description": "The `continuationToken` from the previous response, for the next page.", "schema": { "description": "The `continuationToken` from the previous response, for the next page.", "type": "string" } } ], "responses": { "200": { "description": "Search YouTube by keyword for videos, Shorts, channels and playlists, with date, length and type filters.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "const": true, "description": "Always true here; errors have `success: false`." }, "credits_remaining": { "type": "number", "description": "Your balance after this call. On anonymous playground calls: free tries left today." }, "credits_charged": { "type": "number", "description": "Credits this call cost; 0 on free endpoints. On anonymous playground calls: tries used (1)." }, "videos": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "const": "video", "description": "Always `video`." }, "id": { "type": "string", "description": "Video id, e.g. `v9QtM6qnG50`." }, "url": { "type": "string", "description": "Watch link. Pass it to the video endpoint for likes, comments, the full description and exact views." }, "title": { "type": "string", "description": "Video title." }, "thumbnail": { "description": "Largest thumbnail URL.", "type": [ "string", "null" ] }, "viewCountText": { "description": "Views as YouTube shows them, e.g. \"82M views\", or \"1,204 watching\" while live.", "type": [ "string", "null" ] }, "viewCountInt": { "description": "viewCountText as a number, rounded whenever YouTube abbreviates it (82M views → 82000000). Use video details for exact views.", "type": [ "number", "null" ] }, "publishedTimeText": { "description": "When it went up, as YouTube shows it, e.g. \"10 days ago\". null for live and upcoming videos.", "type": [ "string", "null" ] }, "publishedTime": { "description": "publishedTimeText as an estimated ISO 8601 time, counted back from when we fetched the page. Only as precise as the text: \"1 year ago\" means sometime that year.", "type": [ "string", "null" ] }, "lengthText": { "description": "Length as shown, e.g. \"19:03\". null for live and upcoming videos.", "type": [ "string", "null" ] }, "lengthSeconds": { "description": "Length in seconds.", "type": [ "number", "null" ] }, "badges": { "type": "array", "items": { "type": "string" }, "description": "Labels YouTube shows on the result, e.g. \"4K\", \"CC\", \"New\" or \"LIVE\". Often empty." }, "description": { "description": "The description snippet shown under the result, usually its first line or two.", "type": [ "string", "null" ] }, "channel": { "anyOf": [ { "type": "object", "properties": { "id": { "description": "Channel id, `UC…`.", "type": [ "string", "null" ] }, "title": { "description": "Channel name.", "type": [ "string", "null" ] }, "handle": { "description": "Handle without the @, e.g. `BenParkes`; null if YouTube shows none.", "type": [ "string", "null" ] }, "url": { "description": "Channel page, e.g. `https://www.youtube.com/@BenParkes`.", "type": [ "string", "null" ] }, "thumbnail": { "description": "Channel picture URL; null when the result doesn't show one.", "type": [ "string", "null" ] } }, "required": [ "id", "title", "handle", "url", "thumbnail" ], "additionalProperties": false, "description": "The channel behind it." }, { "type": "null" } ] } }, "required": [ "type", "id", "url", "title", "thumbnail", "viewCountText", "viewCountInt", "publishedTimeText", "publishedTime", "lengthText", "lengthSeconds", "badges", "description", "channel" ], "additionalProperties": false }, "description": "Videos, in result order." }, "shorts": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "const": "short", "description": "Always `short`." }, "id": { "type": "string", "description": "The Short's video id." }, "url": { "type": "string", "description": "`https://www.youtube.com/shorts/`. Pass it to the video endpoint for likes, comments, date and length." }, "title": { "type": "string", "description": "The Short's title." }, "thumbnail": { "description": "Largest (vertical) thumbnail URL.", "type": [ "string", "null" ] }, "viewCountText": { "description": "Views as YouTube shows them, e.g. \"22M views\".", "type": [ "string", "null" ] }, "viewCountInt": { "description": "viewCountText as a number, rounded as shown (22M views → 22000000).", "type": [ "number", "null" ] } }, "required": [ "type", "id", "url", "title", "thumbnail", "viewCountText", "viewCountInt" ], "additionalProperties": false }, "description": "Shorts, in result order." }, "channels": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "const": "channel", "description": "Always `channel`." }, "id": { "type": "string", "description": "Channel id, `UC…`. Pass it to channel details for the full stats." }, "url": { "type": "string", "description": "Channel page." }, "title": { "type": "string", "description": "Channel name." }, "handle": { "description": "Handle without the @; null if YouTube shows none.", "type": [ "string", "null" ] }, "thumbnail": { "description": "Channel picture URL.", "type": [ "string", "null" ] }, "description": { "description": "The description snippet shown in the result.", "type": [ "string", "null" ] }, "subscriberCountText": { "description": "Subscribers as YouTube shows them, e.g. \"128K subscribers\".", "type": [ "string", "null" ] }, "subscriberCount": { "description": "subscriberCountText as a number, rounded as shown.", "type": [ "number", "null" ] }, "isVerified": { "type": "boolean", "description": "Has YouTube's verified or official artist badge." } }, "required": [ "type", "id", "url", "title", "handle", "thumbnail", "description", "subscriberCountText", "subscriberCount", "isVerified" ], "additionalProperties": false }, "description": "Channels, in result order." }, "playlists": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "const": "playlist", "description": "Always `playlist`." }, "id": { "type": "string", "description": "Playlist id, e.g. `PLB50X6wE7gSWNQJElg3NX4AH42QoouHOk` (mixes start with `RD`)." }, "url": { "type": "string", "description": "Playlist page, `https://www.youtube.com/playlist?list=`." }, "title": { "type": "string", "description": "Playlist title." }, "thumbnail": { "description": "Cover thumbnail URL (its first video).", "type": [ "string", "null" ] }, "videoCountText": { "description": "Size as YouTube shows it, e.g. \"30 videos\".", "type": [ "string", "null" ] }, "videoCount": { "description": "videoCountText as a number.", "type": [ "number", "null" ] }, "channel": { "anyOf": [ { "type": "object", "properties": { "id": { "description": "Channel id, `UC…`.", "type": [ "string", "null" ] }, "title": { "description": "Channel name.", "type": [ "string", "null" ] }, "handle": { "description": "Handle without the @, e.g. `BenParkes`; null if YouTube shows none.", "type": [ "string", "null" ] }, "url": { "description": "Channel page, e.g. `https://www.youtube.com/@BenParkes`.", "type": [ "string", "null" ] }, "thumbnail": { "description": "Channel picture URL; null when the result doesn't show one.", "type": [ "string", "null" ] } }, "required": [ "id", "title", "handle", "url", "thumbnail" ], "additionalProperties": false, "description": "The channel behind it." }, { "type": "null" } ] } }, "required": [ "type", "id", "url", "title", "thumbnail", "videoCountText", "videoCount", "channel" ], "additionalProperties": false }, "description": "Playlists and mixes, in result order." }, "lives": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "const": "video", "description": "Always `video`." }, "id": { "type": "string", "description": "Video id, e.g. `v9QtM6qnG50`." }, "url": { "type": "string", "description": "Watch link. Pass it to the video endpoint for likes, comments, the full description and exact views." }, "title": { "type": "string", "description": "Video title." }, "thumbnail": { "description": "Largest thumbnail URL.", "type": [ "string", "null" ] }, "viewCountText": { "description": "Views as YouTube shows them, e.g. \"82M views\", or \"1,204 watching\" while live.", "type": [ "string", "null" ] }, "viewCountInt": { "description": "viewCountText as a number, rounded whenever YouTube abbreviates it (82M views → 82000000). Use video details for exact views.", "type": [ "number", "null" ] }, "publishedTimeText": { "description": "When it went up, as YouTube shows it, e.g. \"10 days ago\". null for live and upcoming videos.", "type": [ "string", "null" ] }, "publishedTime": { "description": "publishedTimeText as an estimated ISO 8601 time, counted back from when we fetched the page. Only as precise as the text: \"1 year ago\" means sometime that year.", "type": [ "string", "null" ] }, "lengthText": { "description": "Length as shown, e.g. \"19:03\". null for live and upcoming videos.", "type": [ "string", "null" ] }, "lengthSeconds": { "description": "Length in seconds.", "type": [ "number", "null" ] }, "badges": { "type": "array", "items": { "type": "string" }, "description": "Labels YouTube shows on the result, e.g. \"4K\", \"CC\", \"New\" or \"LIVE\". Often empty." }, "description": { "description": "The description snippet shown under the result, usually its first line or two.", "type": [ "string", "null" ] }, "channel": { "anyOf": [ { "type": "object", "properties": { "id": { "description": "Channel id, `UC…`.", "type": [ "string", "null" ] }, "title": { "description": "Channel name.", "type": [ "string", "null" ] }, "handle": { "description": "Handle without the @, e.g. `BenParkes`; null if YouTube shows none.", "type": [ "string", "null" ] }, "url": { "description": "Channel page, e.g. `https://www.youtube.com/@BenParkes`.", "type": [ "string", "null" ] }, "thumbnail": { "description": "Channel picture URL; null when the result doesn't show one.", "type": [ "string", "null" ] } }, "required": [ "id", "title", "handle", "url", "thumbnail" ], "additionalProperties": false, "description": "The channel behind it." }, { "type": "null" } ] } }, "required": [ "type", "id", "url", "title", "thumbnail", "viewCountText", "viewCountInt", "publishedTimeText", "publishedTime", "lengthText", "lengthSeconds", "badges", "description", "channel" ], "additionalProperties": false }, "description": "Streams that are live right now." }, "continuationToken": { "description": "Pass as `continuationToken` for the next page. null on the last page.", "type": [ "string", "null" ] } }, "required": [ "success", "credits_remaining", "credits_charged", "videos", "shorts", "channels", "playlists", "lives", "continuationToken" ], "additionalProperties": false } } } }, "default": { "description": "Error. Not charged, except the endpoint's own 4xx answers such as not_found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/tiktok/profile": { "get": { "operationId": "tiktok_profile", "tags": [ "TikTok" ], "summary": "Profile", "description": "A creator's bio, avatar, verification and exact follower, like and video counts.\n\nUse it to size up a creator or brand account: followers, total likes and video count as exact numbers, plus bio, link and category. `user.secUid` is TikTok's stable id; `user.roomId` is set while they're live.\n\nUnknown, banned and deleted accounts return 404 `not_found`. Private accounts return their profile with `privateAccount: true`.\n\nCost: 1 credit.", "externalDocs": { "url": "https://lurkapi.com/docs/tiktok/profile" }, "x-credits": 1, "parameters": [ { "name": "handle", "in": "query", "required": true, "description": "TikTok username, with or without @ (e.g. `nike`), or the profile URL.", "schema": { "description": "TikTok username, with or without @ (e.g. `nike`), or the profile URL.", "type": "string" }, "example": "nike" } ], "responses": { "200": { "description": "A creator's bio, avatar, verification and exact follower, like and video counts.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "const": true, "description": "Always true here; errors have `success: false`." }, "credits_remaining": { "type": "number", "description": "Your balance after this call. On anonymous playground calls: free tries left today." }, "credits_charged": { "type": "number", "description": "Credits this call cost; 0 on free endpoints. On anonymous playground calls: tries used (1)." }, "user": { "type": "object", "properties": { "id": { "type": "string", "description": "Numeric user id." }, "uniqueId": { "type": "string", "description": "Username (handle), without @." }, "nickname": { "type": "string", "description": "Display name." }, "signature": { "type": "string", "description": "Bio text." }, "secUid": { "type": "string", "description": "TikTok's long, stable user id; other tools ask for it." }, "verified": { "type": "boolean", "description": "Has the verified badge." }, "privateAccount": { "type": "boolean", "description": "The account is private: videos and follower lists are hidden." }, "createTime": { "type": "number", "description": "Account created, Unix seconds." }, "avatarLarger": { "description": "Large avatar URL (expires after a few days); null if TikTok has none.", "type": [ "string", "null" ] }, "avatarMedium": { "description": "Medium avatar URL (expires after a few days); null if TikTok has none.", "type": [ "string", "null" ] }, "avatarThumb": { "description": "Small avatar URL (expires after a few days); null if TikTok has none.", "type": [ "string", "null" ] }, "bioLink": { "description": "The link in the bio; null if none.", "type": [ "string", "null" ] }, "language": { "description": "Account language, e.g. `en`; null if unknown.", "type": [ "string", "null" ] }, "category": { "description": "Business category, e.g. \"Sports, Fitness & Outdoors\"; null for personal accounts.", "type": [ "string", "null" ] }, "commerceUser": { "type": "boolean", "description": "A business account." }, "ttSeller": { "type": "boolean", "description": "Sells on TikTok Shop." }, "isOrganization": { "type": "boolean", "description": "Registered as an organization." }, "roomId": { "description": "Live room id TikTok reports; may belong to a finished stream. Use live status to verify; null when none.", "type": [ "string", "null" ] } }, "required": [ "id", "uniqueId", "nickname", "signature", "secUid", "verified", "privateAccount", "createTime", "avatarLarger", "avatarMedium", "avatarThumb", "bioLink", "language", "category", "commerceUser", "ttSeller", "isOrganization", "roomId" ], "additionalProperties": false, "description": "The account." }, "stats": { "type": "object", "properties": { "followerCount": { "type": "number", "description": "Followers, exact." }, "followingCount": { "type": "number", "description": "Accounts they follow." }, "heartCount": { "type": "number", "description": "Total likes received across all videos." }, "videoCount": { "type": "number", "description": "Public videos." }, "diggCount": { "type": "number", "description": "Videos they liked (0 when hidden)." }, "friendCount": { "type": "number", "description": "Mutual follows." } }, "required": [ "followerCount", "followingCount", "heartCount", "videoCount", "diggCount", "friendCount" ], "additionalProperties": false, "description": "Counts when fetched." } }, "required": [ "success", "credits_remaining", "credits_charged", "user", "stats" ], "additionalProperties": false } } } }, "404": { "description": "not_found: The endpoint, or the thing you asked for (ad, post, subreddit), doesn't exist. Charged when the platform was checked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error. Not charged, except the endpoint's own 4xx answers such as not_found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v2/tiktok/video": { "get": { "operationId": "tiktok_video", "tags": [ "TikTok" ], "summary": "Video details", "description": "One video or photo post: caption, stats, author, sound, hashtags and a playable MP4 URL.\n\nUse it to track a post's views, likes, comments, shares and saves, or to get its media. `video.playUrl` plays without cookies until `video.expires_at` (about two days); fetch the post again for a fresh one. Photo posts have their slides in `images`.\n\nPass `get_transcript=true` to also get the captions as WEBVTT in `transcript` (same credit).\n\nDeleted, private and region-locked posts return 404 `not_found`.\n\nCost: 1 credit.", "externalDocs": { "url": "https://lurkapi.com/docs/tiktok/video" }, "x-credits": 1, "parameters": [ { "name": "url", "in": "query", "required": true, "description": "The video's URL, e.g. `https://www.tiktok.com/@hubspot/video/7671325437229845774`. Photo post URLs and bare video ids work too.", "schema": { "description": "The video's URL, e.g. `https://www.tiktok.com/@hubspot/video/7671325437229845774`. Photo post URLs and bare video ids work too.", "type": "string" }, "example": "https://www.tiktok.com/@hubspot/video/7671325437229845774" }, { "name": "get_transcript", "in": "query", "required": false, "description": "`true` adds the captions as WEBVTT in `transcript` (null if the video has none).", "schema": { "description": "`true` adds the captions as WEBVTT in `transcript` (null if the video has none).", "default": "false", "type": "string", "enum": [ "true", "false" ] } } ], "responses": { "200": { "description": "One video or photo post: caption, stats, author, sound, hashtags and a playable MP4 URL.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "const": true, "description": "Always true here; errors have `success: false`." }, "credits_remaining": { "type": "number", "description": "Your balance after this call. On anonymous playground calls: free tries left today." }, "credits_charged": { "type": "number", "description": "Credits this call cost; 0 on free endpoints. On anonymous playground calls: tries used (1)." }, "id": { "type": "string", "description": "Video id, e.g. `7671325437229845774`." }, "url": { "type": "string", "description": "The post on tiktok.com." }, "desc": { "type": "string", "description": "Caption, hashtags included." }, "createTime": { "type": "number", "description": "Posted at, Unix seconds." }, "textLanguage": { "description": "Caption language as TikTok detects it, e.g. `en`; null if unknown.", "type": [ "string", "null" ] }, "locationCreated": { "description": "Country the post was made in, as a 2-letter code; null if unknown.", "type": [ "string", "null" ] }, "isAd": { "type": "boolean", "description": "A paid ad (Spark Ad or promoted post)." }, "author": { "type": "object", "properties": { "id": { "type": "string", "description": "Numeric user id." }, "uniqueId": { "type": "string", "description": "Username (handle), without @." }, "nickname": { "type": "string", "description": "Display name." }, "secUid": { "type": "string", "description": "TikTok's long, stable user id; other tools ask for it." }, "verified": { "type": "boolean", "description": "Has the verified badge." }, "privateAccount": { "type": "boolean", "description": "The account is private." }, "avatarThumb": { "description": "Small avatar URL (expires after a few days); null if TikTok has none.", "type": [ "string", "null" ] }, "avatarLarger": { "description": "Large avatar URL (expires after a few days); null if TikTok has none.", "type": [ "string", "null" ] } }, "required": [ "id", "uniqueId", "nickname", "secUid", "verified", "privateAccount", "avatarThumb", "avatarLarger" ], "additionalProperties": false, "description": "Who posted it." }, "stats": { "type": "object", "properties": { "playCount": { "type": "number", "description": "Views." }, "diggCount": { "type": "number", "description": "Likes." }, "commentCount": { "type": "number", "description": "Comments." }, "shareCount": { "type": "number", "description": "Shares." }, "collectCount": { "description": "Saves (favorites); null where TikTok doesn't show it.", "type": [ "number", "null" ] }, "repostCount": { "description": "Reposts; null where TikTok doesn't show it.", "type": [ "number", "null" ] } }, "required": [ "playCount", "diggCount", "commentCount", "shareCount", "collectCount", "repostCount" ], "additionalProperties": false, "description": "Engagement when fetched. Exact numbers, not rounded." }, "video": { "type": "object", "properties": { "duration": { "type": "number", "description": "Length in seconds; 0 for photo posts." }, "width": { "type": "number", "description": "Width in pixels; 0 for photo posts." }, "height": { "type": "number", "description": "Height in pixels; 0 for photo posts." }, "definition": { "description": "Quality of the default rendition, e.g. `720p`.", "type": [ "string", "null" ] }, "cover": { "description": "Cover image URL (expires after a few days); null if TikTok has none.", "type": [ "string", "null" ] }, "dynamicCover": { "description": "Animated cover URL (expires after a few days); null if TikTok has none.", "type": [ "string", "null" ] }, "playUrl": { "description": "MP4 URL that plays without cookies (h264, best quality). It redirects to TikTok's CDN and expires at `expires_at`; null if TikTok has none.", "type": [ "string", "null" ] }, "expires_at": { "description": "When `playUrl` stops working, Unix seconds; null if unknown.", "type": [ "number", "null" ] } }, "required": [ "duration", "width", "height", "definition", "cover", "dynamicCover", "playUrl", "expires_at" ], "additionalProperties": false, "description": "The video file. For photo posts see `images`." }, "music": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "description": "Sound id; pass it to song endpoints." }, "title": { "type": "string", "description": "Sound title, e.g. `original sound`." }, "authorName": { "description": "Artist, or the creator for original sounds.", "type": [ "string", "null" ] }, "original": { "type": "boolean", "description": "An original sound made with this post rather than a track." }, "duration": { "description": "Length in seconds.", "type": [ "number", "null" ] }, "playUrl": { "description": "Audio URL (expires after a few hours); null if TikTok has none.", "type": [ "string", "null" ] }, "cover": { "description": "Sound cover image URL; null if TikTok has none.", "type": [ "string", "null" ] } }, "required": [ "id", "title", "authorName", "original", "duration", "playUrl", "cover" ], "additionalProperties": false }, { "type": "null" } ], "description": "The sound; null if the post has none." }, "hashtags": { "type": "array", "items": { "type": "string", "description": "Hashtag without #." }, "description": "Hashtags in the caption, without #." }, "mentions": { "type": "array", "items": { "type": "string", "description": "Username without @." }, "description": "Usernames @mentioned in the caption." }, "images": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string", "description": "Image URL (expires after a few days)." }, "width": { "type": "number", "description": "Width in pixels." }, "height": { "type": "number", "description": "Height in pixels." } }, "required": [ "url", "width", "height" ], "additionalProperties": false }, "description": "The slides of a photo post, in order. Empty for videos." }, "transcript": { "description": "With `get_transcript=true`: the captions as WEBVTT in the video's original language; null if it has none.", "type": [ "string", "null" ] } }, "required": [ "success", "credits_remaining", "credits_charged", "id", "url", "desc", "createTime", "textLanguage", "locationCreated", "isAd", "author", "stats", "video", "music", "hashtags", "mentions", "images" ], "additionalProperties": false } } } }, "404": { "description": "not_found: The endpoint, or the thing you asked for (ad, post, subreddit), doesn't exist. Charged when the platform was checked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error. Not charged, except the endpoint's own 4xx answers such as not_found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/tiktok/video/transcript": { "get": { "operationId": "tiktok_transcript", "tags": [ "TikTok" ], "summary": "Video transcript", "description": "What's said in a video, from TikTok's captions: WEBVTT with timestamps plus plain text.\n\nUse it to turn a TikTok into text: repurpose a script, search what creators say, or feed it to an LLM. `transcript` is WEBVTT with timestamps (the same format other TikTok APIs return); `text` is the same words as plain text.\n\nTranscripts come from TikTok's own captions: auto-generated speech captions (`source: asr`), the creator's own captions, or TikTok's translations. Most spoken videos have them. A video without captions (music only, or captions off) returns `transcript: null` with `languages: []`.\n\n**No captions?** Pass `use_ai_as_fallback=true` and we transcribe the audio ourselves (`source: ai`) for videos up to 2 minutes. That costs 5 credits in total, and only when it runs; with captions it's still 1.\n\nBy default you get the original language. Pass `language` (e.g. `es`) to pick one of `languages`.\n\nDeleted, private and region-locked videos return 404 `not_found`.\n\nCost: 1 credit; 5 if speech-to-text runs.", "externalDocs": { "url": "https://lurkapi.com/docs/tiktok/transcript" }, "x-credits": 1, "x-extra-credits": { "asr": 4 }, "parameters": [ { "name": "url", "in": "query", "required": true, "description": "The video's URL, e.g. `https://www.tiktok.com/@hubspot/video/7671325437229845774`. Photo post URLs and bare video ids work too.", "schema": { "description": "The video's URL, e.g. `https://www.tiktok.com/@hubspot/video/7671325437229845774`. Photo post URLs and bare video ids work too.", "type": "string" }, "example": "https://www.tiktok.com/@hubspot/video/7671325437229845774" }, { "name": "language", "in": "query", "required": false, "description": "2-letter language code, e.g. `en` or `es`. Default: the video's original language.", "schema": { "description": "2-letter language code, e.g. `en` or `es`. Default: the video's original language.", "type": "string", "pattern": "^[a-z]{2,3}(-[a-z]{2})?$" } }, { "name": "use_ai_as_fallback", "in": "query", "required": false, "description": "`true`: if the video has no captions, transcribe its audio with speech-to-text (videos up to 2 minutes; 5 credits in total, only when it runs).", "schema": { "description": "`true`: if the video has no captions, transcribe its audio with speech-to-text (videos up to 2 minutes; 5 credits in total, only when it runs).", "default": "false", "type": "string", "enum": [ "true", "false" ] } } ], "responses": { "200": { "description": "What's said in a video, from TikTok's captions: WEBVTT with timestamps plus plain text.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "const": true, "description": "Always true here; errors have `success: false`." }, "credits_remaining": { "type": "number", "description": "Your balance after this call. On anonymous playground calls: free tries left today." }, "credits_charged": { "type": "number", "description": "Credits this call cost; 0 on free endpoints. On anonymous playground calls: tries used (1)." }, "id": { "type": "string", "description": "Video id." }, "url": { "type": "string", "description": "The video on tiktok.com." }, "transcript": { "description": "The captions as WEBVTT, with timestamps. null if the video has none in that language.", "type": [ "string", "null" ] }, "text": { "description": "The same captions as plain text, one cue per line. null if none.", "type": [ "string", "null" ] }, "language": { "description": "Language of `transcript`, e.g. `en`. null if none.", "type": [ "string", "null" ] }, "source": { "anyOf": [ { "type": "string", "enum": [ "asr", "creator", "translation", "ai" ] }, { "type": "null" } ], "description": "`asr`: TikTok's auto-generated speech captions. `creator`: captions the creator wrote. `translation`: TikTok's machine translation. `ai`: our speech-to-text (`use_ai_as_fallback`). null if none." }, "languages": { "type": "array", "items": { "type": "object", "properties": { "language": { "type": "string", "description": "Language code, usually 2 letters, e.g. `en`." }, "source": { "type": "string", "enum": [ "asr", "creator", "translation" ], "description": "Where these captions come from (see `source`)." } }, "required": [ "language", "source" ], "additionalProperties": false }, "description": "Every caption language TikTok has for the video. Empty when it has none." } }, "required": [ "success", "credits_remaining", "credits_charged", "id", "url", "transcript", "text", "language", "source", "languages" ], "additionalProperties": false } } } }, "404": { "description": "not_found: The endpoint, or the thing you asked for (ad, post, subreddit), doesn't exist. Charged when the platform was checked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error. Not charged, except the endpoint's own 4xx answers such as not_found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v3/tiktok/profile/videos": { "get": { "operationId": "tiktok_profile_videos", "tags": [ "TikTok" ], "summary": "Profile videos", "description": "A creator's videos and photo posts, newest first, up to 15 per page.\n\nUse it to audit a creator's recent content: every post with views, likes, comments, shares, saves, caption and media. Posts come newest first, up to 15 per page. Pinned posts appear in date order, like every other post.\n\n**Pagination.** Pass the response's `max_cursor` back as `max_cursor` (with the same `handle`) for older posts. `has_more` is false at the end. A creator who hasn't posted for weeks can give a page with no posts but `has_more: true`; keep paging.\n\nUnknown, banned and deleted accounts return 404 `not_found`. Private accounts return an empty `videos` list.\n\nCost: 1 credit.", "externalDocs": { "url": "https://lurkapi.com/docs/tiktok/profile-videos" }, "x-credits": 1, "parameters": [ { "name": "handle", "in": "query", "required": true, "description": "TikTok username, with or without @ (e.g. `nike`), or the profile URL.", "schema": { "description": "TikTok username, with or without @ (e.g. `nike`), or the profile URL.", "type": "string" }, "example": "hubspot" }, { "name": "max_cursor", "in": "query", "required": false, "description": "The `max_cursor` from the previous response, to get older posts.", "schema": { "description": "The `max_cursor` from the previous response, to get older posts.", "type": "string", "pattern": "^\\d{1,20}$" } } ], "responses": { "200": { "description": "A creator's videos and photo posts, newest first, up to 15 per page.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "const": true, "description": "Always true here; errors have `success: false`." }, "credits_remaining": { "type": "number", "description": "Your balance after this call. On anonymous playground calls: free tries left today." }, "credits_charged": { "type": "number", "description": "Credits this call cost; 0 on free endpoints. On anonymous playground calls: tries used (1)." }, "videos": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Video id, e.g. `7671325437229845774`." }, "url": { "type": "string", "description": "The post on tiktok.com." }, "desc": { "type": "string", "description": "Caption, hashtags included." }, "createTime": { "type": "number", "description": "Posted at, Unix seconds." }, "textLanguage": { "description": "Caption language as TikTok detects it, e.g. `en`; null if unknown.", "type": [ "string", "null" ] }, "locationCreated": { "description": "Country the post was made in, as a 2-letter code; null if unknown.", "type": [ "string", "null" ] }, "isAd": { "type": "boolean", "description": "A paid ad (Spark Ad or promoted post)." }, "author": { "type": "object", "properties": { "id": { "type": "string", "description": "Numeric user id." }, "uniqueId": { "type": "string", "description": "Username (handle), without @." }, "nickname": { "type": "string", "description": "Display name." }, "secUid": { "type": "string", "description": "TikTok's long, stable user id; other tools ask for it." }, "verified": { "type": "boolean", "description": "Has the verified badge." }, "privateAccount": { "type": "boolean", "description": "The account is private." }, "avatarThumb": { "description": "Small avatar URL (expires after a few days); null if TikTok has none.", "type": [ "string", "null" ] }, "avatarLarger": { "description": "Large avatar URL (expires after a few days); null if TikTok has none.", "type": [ "string", "null" ] } }, "required": [ "id", "uniqueId", "nickname", "secUid", "verified", "privateAccount", "avatarThumb", "avatarLarger" ], "additionalProperties": false, "description": "Who posted it." }, "stats": { "type": "object", "properties": { "playCount": { "type": "number", "description": "Views." }, "diggCount": { "type": "number", "description": "Likes." }, "commentCount": { "type": "number", "description": "Comments." }, "shareCount": { "type": "number", "description": "Shares." }, "collectCount": { "description": "Saves (favorites); null where TikTok doesn't show it.", "type": [ "number", "null" ] }, "repostCount": { "description": "Reposts; null where TikTok doesn't show it.", "type": [ "number", "null" ] } }, "required": [ "playCount", "diggCount", "commentCount", "shareCount", "collectCount", "repostCount" ], "additionalProperties": false, "description": "Engagement when fetched. Exact numbers, not rounded." }, "video": { "type": "object", "properties": { "duration": { "type": "number", "description": "Length in seconds; 0 for photo posts." }, "width": { "type": "number", "description": "Width in pixels; 0 for photo posts." }, "height": { "type": "number", "description": "Height in pixels; 0 for photo posts." }, "definition": { "description": "Quality of the default rendition, e.g. `720p`.", "type": [ "string", "null" ] }, "cover": { "description": "Cover image URL (expires after a few days); null if TikTok has none.", "type": [ "string", "null" ] }, "dynamicCover": { "description": "Animated cover URL (expires after a few days); null if TikTok has none.", "type": [ "string", "null" ] }, "playUrl": { "description": "MP4 URL that plays without cookies (h264, best quality). It redirects to TikTok's CDN and expires at `expires_at`; null if TikTok has none.", "type": [ "string", "null" ] }, "expires_at": { "description": "When `playUrl` stops working, Unix seconds; null if unknown.", "type": [ "number", "null" ] } }, "required": [ "duration", "width", "height", "definition", "cover", "dynamicCover", "playUrl", "expires_at" ], "additionalProperties": false, "description": "The video file. For photo posts see `images`." }, "music": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "description": "Sound id; pass it to song endpoints." }, "title": { "type": "string", "description": "Sound title, e.g. `original sound`." }, "authorName": { "description": "Artist, or the creator for original sounds.", "type": [ "string", "null" ] }, "original": { "type": "boolean", "description": "An original sound made with this post rather than a track." }, "duration": { "description": "Length in seconds.", "type": [ "number", "null" ] }, "playUrl": { "description": "Audio URL (expires after a few hours); null if TikTok has none.", "type": [ "string", "null" ] }, "cover": { "description": "Sound cover image URL; null if TikTok has none.", "type": [ "string", "null" ] } }, "required": [ "id", "title", "authorName", "original", "duration", "playUrl", "cover" ], "additionalProperties": false }, { "type": "null" } ], "description": "The sound; null if the post has none." }, "hashtags": { "type": "array", "items": { "type": "string", "description": "Hashtag without #." }, "description": "Hashtags in the caption, without #." }, "mentions": { "type": "array", "items": { "type": "string", "description": "Username without @." }, "description": "Usernames @mentioned in the caption." }, "images": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string", "description": "Image URL (expires after a few days)." }, "width": { "type": "number", "description": "Width in pixels." }, "height": { "type": "number", "description": "Height in pixels." } }, "required": [ "url", "width", "height" ], "additionalProperties": false }, "description": "The slides of a photo post, in order. Empty for videos." } }, "required": [ "id", "url", "desc", "createTime", "textLanguage", "locationCreated", "isAd", "author", "stats", "video", "music", "hashtags", "mentions", "images" ], "additionalProperties": false }, "description": "Posts, newest first." }, "has_more": { "type": "boolean", "description": "There are older posts." }, "max_cursor": { "description": "Pass as `max_cursor` for older posts. null on the last page.", "type": [ "string", "null" ] } }, "required": [ "success", "credits_remaining", "credits_charged", "videos", "has_more", "max_cursor" ], "additionalProperties": false } } } }, "404": { "description": "not_found: The endpoint, or the thing you asked for (ad, post, subreddit), doesn't exist. Charged when the platform was checked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error. Not charged, except the endpoint's own 4xx answers such as not_found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/tiktok/video/comments": { "get": { "operationId": "tiktok_comments", "tags": [ "TikTok" ], "summary": "Video comments", "description": "A video's top-level comments, most relevant first, with like and reply counts.\n\nUse it to read what viewers say: objections, questions, praise and the words your audience uses. Each comment has its likes, reply count and author; pass a comment's `cid` as `comment_id` to comment replies for its thread.\n\n**Pagination.** 50 comments per page. Pass the response's `cursor` back as `cursor` (with the same `url`) for more; it's null at the end.\n\nDeleted or private videos return 404 `not_found`; videos with comments turned off return an empty list.\n\nCost: 1 credit.", "externalDocs": { "url": "https://lurkapi.com/docs/tiktok/comments" }, "x-credits": 1, "parameters": [ { "name": "url", "in": "query", "required": true, "description": "The video's URL, e.g. `https://www.tiktok.com/@hubspot/video/7671325437229845774`. Photo post URLs and bare video ids work too.", "schema": { "description": "The video's URL, e.g. `https://www.tiktok.com/@hubspot/video/7671325437229845774`. Photo post URLs and bare video ids work too.", "type": "string" }, "example": "https://www.tiktok.com/@scout2015/video/6718335390845095173" }, { "name": "cursor", "in": "query", "required": false, "description": "The `cursor` from the previous response, to get the next page.", "schema": { "description": "The `cursor` from the previous response, to get the next page.", "type": "string", "pattern": "^\\d{1,20}$" } } ], "responses": { "200": { "description": "A video's top-level comments, most relevant first, with like and reply counts.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "const": true, "description": "Always true here; errors have `success: false`." }, "credits_remaining": { "type": "number", "description": "Your balance after this call. On anonymous playground calls: free tries left today." }, "credits_charged": { "type": "number", "description": "Credits this call cost; 0 on free endpoints. On anonymous playground calls: tries used (1)." }, "comments": { "type": "array", "items": { "type": "object", "properties": { "cid": { "type": "string", "description": "Comment id; pass it as `comment_id` to comment replies." }, "text": { "type": "string", "description": "Comment text." }, "create_time": { "type": "number", "description": "Posted at, Unix seconds." }, "digg_count": { "type": "number", "description": "Likes." }, "reply_comment_total": { "type": "number", "description": "Replies to this comment. Always 0 on replies." }, "comment_language": { "description": "Language as TikTok detects it, e.g. `en`; `un` = undetermined.", "type": [ "string", "null" ] }, "author_pin": { "type": "boolean", "description": "Pinned by the video's creator." }, "is_author_digged": { "type": "boolean", "description": "Liked by the video's creator." }, "reply_id": { "type": "string", "description": "On replies: the comment it belongs to. `0` on top-level comments." }, "reply_to_reply_id": { "type": "string", "description": "On replies: the reply it answers, if any. `0` otherwise." }, "aweme_id": { "type": "string", "description": "The video's id." }, "user": { "type": "object", "properties": { "uid": { "type": "string", "description": "Numeric user id." }, "unique_id": { "type": "string", "description": "Username (handle), without @." }, "nickname": { "type": "string", "description": "Display name." }, "sec_uid": { "type": "string", "description": "TikTok's long, stable user id." }, "avatar_thumb": { "description": "Small avatar URL (expires after a few days); null if TikTok has none.", "type": [ "string", "null" ] } }, "required": [ "uid", "unique_id", "nickname", "sec_uid", "avatar_thumb" ], "additionalProperties": false, "description": "Who wrote it." } }, "required": [ "cid", "text", "create_time", "digg_count", "reply_comment_total", "comment_language", "author_pin", "is_author_digged", "reply_id", "reply_to_reply_id", "aweme_id", "user" ], "additionalProperties": false }, "description": "Comments, in TikTok's order." }, "total": { "type": "number", "description": "Comments TikTok counts in this thread (may include some it no longer shows)." }, "has_more": { "type": "boolean", "description": "More comments after this page." }, "cursor": { "description": "Pass as `cursor` for the next page. null on the last page.", "type": [ "string", "null" ] } }, "required": [ "success", "credits_remaining", "credits_charged", "comments", "total", "has_more", "cursor" ], "additionalProperties": false } } } }, "404": { "description": "not_found: The endpoint, or the thing you asked for (ad, post, subreddit), doesn't exist. Charged when the platform was checked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error. Not charged, except the endpoint's own 4xx answers such as not_found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/tiktok/video/comment/replies": { "get": { "operationId": "tiktok_comment_replies", "tags": [ "TikTok" ], "summary": "Comment replies", "description": "The replies under one comment, oldest first.\n\nUse it to read a comment's thread. Get `comment_id` from a comment's `cid` in video comments. `reply_to_reply_id` shows which reply a reply answers.\n\n**Pagination.** 50 replies per page. Pass the response's `cursor` back as `cursor` (with the same `url` and `comment_id`); it's null at the end.\n\nCost: 1 credit.", "externalDocs": { "url": "https://lurkapi.com/docs/tiktok/comment-replies" }, "x-credits": 1, "parameters": [ { "name": "url", "in": "query", "required": true, "description": "The video's URL, e.g. `https://www.tiktok.com/@hubspot/video/7671325437229845774`. Photo post URLs and bare video ids work too.", "schema": { "description": "The video's URL, e.g. `https://www.tiktok.com/@hubspot/video/7671325437229845774`. Photo post URLs and bare video ids work too.", "type": "string" }, "example": "https://www.tiktok.com/@scout2015/video/6718335390845095173" }, { "name": "comment_id", "in": "query", "required": true, "description": "The comment's `cid`, from video comments.", "schema": { "type": "string", "pattern": "^\\d{1,21}$", "description": "The comment's `cid`, from video comments." }, "example": "6718335906996502534" }, { "name": "cursor", "in": "query", "required": false, "description": "The `cursor` from the previous response, to get the next page.", "schema": { "description": "The `cursor` from the previous response, to get the next page.", "type": "string", "pattern": "^\\d{1,20}$" } } ], "responses": { "200": { "description": "The replies under one comment, oldest first.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "const": true, "description": "Always true here; errors have `success: false`." }, "credits_remaining": { "type": "number", "description": "Your balance after this call. On anonymous playground calls: free tries left today." }, "credits_charged": { "type": "number", "description": "Credits this call cost; 0 on free endpoints. On anonymous playground calls: tries used (1)." }, "comments": { "type": "array", "items": { "type": "object", "properties": { "cid": { "type": "string", "description": "Comment id; pass it as `comment_id` to comment replies." }, "text": { "type": "string", "description": "Comment text." }, "create_time": { "type": "number", "description": "Posted at, Unix seconds." }, "digg_count": { "type": "number", "description": "Likes." }, "reply_comment_total": { "type": "number", "description": "Replies to this comment. Always 0 on replies." }, "comment_language": { "description": "Language as TikTok detects it, e.g. `en`; `un` = undetermined.", "type": [ "string", "null" ] }, "author_pin": { "type": "boolean", "description": "Pinned by the video's creator." }, "is_author_digged": { "type": "boolean", "description": "Liked by the video's creator." }, "reply_id": { "type": "string", "description": "On replies: the comment it belongs to. `0` on top-level comments." }, "reply_to_reply_id": { "type": "string", "description": "On replies: the reply it answers, if any. `0` otherwise." }, "aweme_id": { "type": "string", "description": "The video's id." }, "user": { "type": "object", "properties": { "uid": { "type": "string", "description": "Numeric user id." }, "unique_id": { "type": "string", "description": "Username (handle), without @." }, "nickname": { "type": "string", "description": "Display name." }, "sec_uid": { "type": "string", "description": "TikTok's long, stable user id." }, "avatar_thumb": { "description": "Small avatar URL (expires after a few days); null if TikTok has none.", "type": [ "string", "null" ] } }, "required": [ "uid", "unique_id", "nickname", "sec_uid", "avatar_thumb" ], "additionalProperties": false, "description": "Who wrote it." } }, "required": [ "cid", "text", "create_time", "digg_count", "reply_comment_total", "comment_language", "author_pin", "is_author_digged", "reply_id", "reply_to_reply_id", "aweme_id", "user" ], "additionalProperties": false }, "description": "Replies, oldest first." }, "total": { "type": "number", "description": "Comments TikTok counts in this thread (may include some it no longer shows)." }, "has_more": { "type": "boolean", "description": "More comments after this page." }, "cursor": { "description": "Pass as `cursor` for the next page. null on the last page.", "type": [ "string", "null" ] } }, "required": [ "success", "credits_remaining", "credits_charged", "comments", "total", "has_more", "cursor" ], "additionalProperties": false } } } }, "404": { "description": "not_found: The endpoint, or the thing you asked for (ad, post, subreddit), doesn't exist. Charged when the platform was checked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error. Not charged, except the endpoint's own 4xx answers such as not_found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/tiktok/search/hashtag": { "get": { "operationId": "tiktok_hashtag_videos", "tags": [ "TikTok" ], "summary": "Hashtag videos", "description": "Videos posted with a hashtag, plus how big the hashtag is: total posts and views.\n\nUse it to research a trend, a niche or a campaign hashtag: which creators post under it, what performs, and how big it is (`hashtag.videoCount` and `hashtag.viewCount`, exact). Videos come in the order tiktok.com's hashtag page shows them: neither newest nor most viewed first, and often months old.\n\n**Pagination.** Up to 30 videos per page. Pass the response's `cursor` back as `cursor` (with the same `hashtag`) for more; `has_more` is false at the end. A few videos can repeat across pages, so dedupe by `id`. At times TikTok shows logged-out visitors only a handful of a hashtag's videos (with `has_more: false`), even for a big one; it serves full pages again later.\n\nUnknown hashtags return 404 `not_found`.\n\nCost: 1 credit.", "externalDocs": { "url": "https://lurkapi.com/docs/tiktok/hashtag-videos" }, "x-credits": 1, "parameters": [ { "name": "hashtag", "in": "query", "required": true, "description": "The hashtag, with or without # (e.g. `skincare`), or its tiktok.com/tag/… URL.", "schema": { "description": "The hashtag, with or without # (e.g. `skincare`), or its tiktok.com/tag/… URL.", "type": "string" }, "example": "smallbusiness" }, { "name": "cursor", "in": "query", "required": false, "description": "The `cursor` from the previous response, to get the next page.", "schema": { "description": "The `cursor` from the previous response, to get the next page.", "type": "string", "pattern": "^\\d{1,20}$" } } ], "responses": { "200": { "description": "Videos posted with a hashtag, plus how big the hashtag is: total posts and views.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "const": true, "description": "Always true here; errors have `success: false`." }, "credits_remaining": { "type": "number", "description": "Your balance after this call. On anonymous playground calls: free tries left today." }, "credits_charged": { "type": "number", "description": "Credits this call cost; 0 on free endpoints. On anonymous playground calls: tries used (1)." }, "hashtag": { "type": "object", "properties": { "id": { "type": "string", "description": "TikTok's id for the hashtag." }, "title": { "type": "string", "description": "The hashtag, without #." }, "desc": { "type": "string", "description": "TikTok's description of the hashtag; empty for most." }, "videoCount": { "type": "number", "description": "Posts using the hashtag, exact." }, "viewCount": { "type": "number", "description": "Total views of those posts, exact." }, "isCommerce": { "type": "boolean", "description": "A branded hashtag (a sponsored hashtag challenge)." } }, "required": [ "id", "title", "desc", "videoCount", "viewCount", "isCommerce" ], "additionalProperties": false, "description": "The hashtag." }, "videos": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Video id, e.g. `7671325437229845774`." }, "url": { "type": "string", "description": "The post on tiktok.com." }, "desc": { "type": "string", "description": "Caption, hashtags included." }, "createTime": { "type": "number", "description": "Posted at, Unix seconds." }, "textLanguage": { "description": "Caption language as TikTok detects it, e.g. `en`; null if unknown.", "type": [ "string", "null" ] }, "locationCreated": { "description": "Country the post was made in, as a 2-letter code; null if unknown.", "type": [ "string", "null" ] }, "isAd": { "type": "boolean", "description": "A paid ad (Spark Ad or promoted post)." }, "author": { "type": "object", "properties": { "id": { "type": "string", "description": "Numeric user id." }, "uniqueId": { "type": "string", "description": "Username (handle), without @." }, "nickname": { "type": "string", "description": "Display name." }, "secUid": { "type": "string", "description": "TikTok's long, stable user id; other tools ask for it." }, "verified": { "type": "boolean", "description": "Has the verified badge." }, "privateAccount": { "type": "boolean", "description": "The account is private." }, "avatarThumb": { "description": "Small avatar URL (expires after a few days); null if TikTok has none.", "type": [ "string", "null" ] }, "avatarLarger": { "description": "Large avatar URL (expires after a few days); null if TikTok has none.", "type": [ "string", "null" ] } }, "required": [ "id", "uniqueId", "nickname", "secUid", "verified", "privateAccount", "avatarThumb", "avatarLarger" ], "additionalProperties": false, "description": "Who posted it." }, "stats": { "type": "object", "properties": { "playCount": { "type": "number", "description": "Views." }, "diggCount": { "type": "number", "description": "Likes." }, "commentCount": { "type": "number", "description": "Comments." }, "shareCount": { "type": "number", "description": "Shares." }, "collectCount": { "description": "Saves (favorites); null where TikTok doesn't show it.", "type": [ "number", "null" ] }, "repostCount": { "description": "Reposts; null where TikTok doesn't show it.", "type": [ "number", "null" ] } }, "required": [ "playCount", "diggCount", "commentCount", "shareCount", "collectCount", "repostCount" ], "additionalProperties": false, "description": "Engagement when fetched. Exact numbers, not rounded." }, "video": { "type": "object", "properties": { "duration": { "type": "number", "description": "Length in seconds; 0 for photo posts." }, "width": { "type": "number", "description": "Width in pixels; 0 for photo posts." }, "height": { "type": "number", "description": "Height in pixels; 0 for photo posts." }, "definition": { "description": "Quality of the default rendition, e.g. `720p`.", "type": [ "string", "null" ] }, "cover": { "description": "Cover image URL (expires after a few days); null if TikTok has none.", "type": [ "string", "null" ] }, "dynamicCover": { "description": "Animated cover URL (expires after a few days); null if TikTok has none.", "type": [ "string", "null" ] }, "playUrl": { "description": "MP4 URL that plays without cookies (h264, best quality). It redirects to TikTok's CDN and expires at `expires_at`; null if TikTok has none.", "type": [ "string", "null" ] }, "expires_at": { "description": "When `playUrl` stops working, Unix seconds; null if unknown.", "type": [ "number", "null" ] } }, "required": [ "duration", "width", "height", "definition", "cover", "dynamicCover", "playUrl", "expires_at" ], "additionalProperties": false, "description": "The video file. For photo posts see `images`." }, "music": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "description": "Sound id; pass it to song endpoints." }, "title": { "type": "string", "description": "Sound title, e.g. `original sound`." }, "authorName": { "description": "Artist, or the creator for original sounds.", "type": [ "string", "null" ] }, "original": { "type": "boolean", "description": "An original sound made with this post rather than a track." }, "duration": { "description": "Length in seconds.", "type": [ "number", "null" ] }, "playUrl": { "description": "Audio URL (expires after a few hours); null if TikTok has none.", "type": [ "string", "null" ] }, "cover": { "description": "Sound cover image URL; null if TikTok has none.", "type": [ "string", "null" ] } }, "required": [ "id", "title", "authorName", "original", "duration", "playUrl", "cover" ], "additionalProperties": false }, { "type": "null" } ], "description": "The sound; null if the post has none." }, "hashtags": { "type": "array", "items": { "type": "string", "description": "Hashtag without #." }, "description": "Hashtags in the caption, without #." }, "mentions": { "type": "array", "items": { "type": "string", "description": "Username without @." }, "description": "Usernames @mentioned in the caption." }, "images": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string", "description": "Image URL (expires after a few days)." }, "width": { "type": "number", "description": "Width in pixels." }, "height": { "type": "number", "description": "Height in pixels." } }, "required": [ "url", "width", "height" ], "additionalProperties": false }, "description": "The slides of a photo post, in order. Empty for videos." } }, "required": [ "id", "url", "desc", "createTime", "textLanguage", "locationCreated", "isAd", "author", "stats", "video", "music", "hashtags", "mentions", "images" ], "additionalProperties": false }, "description": "Posts, in the order tiktok.com shows them (not newest first)." }, "has_more": { "type": "boolean", "description": "There are more posts after this page." }, "cursor": { "description": "Pass as `cursor` for the next page. null on the last page.", "type": [ "string", "null" ] } }, "required": [ "success", "credits_remaining", "credits_charged", "hashtag", "videos", "has_more", "cursor" ], "additionalProperties": false } } } }, "404": { "description": "not_found: The endpoint, or the thing you asked for (ad, post, subreddit), doesn't exist. Charged when the platform was checked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error. Not charged, except the endpoint's own 4xx answers such as not_found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/tiktok/song": { "get": { "operationId": "tiktok_song", "tags": [ "TikTok" ], "summary": "Song", "description": "A TikTok sound: title, artist, album, length, cover, audio URL and how many videos use it.\n\nUse it to size up a sound before you build content on it: `videoCount` is how many posts use it. `original: true` means a creator's original sound rather than a released track, and `is_commerce_music` is TikTok's flag for sounds cleared for commercial use (the ones business accounts can pick). Get the id from any video's `music.id`, or pass the sound's tiktok.com/music/… URL.\n\nUnknown and removed sounds return 404 `not_found`.\n\nCost: 1 credit.", "externalDocs": { "url": "https://lurkapi.com/docs/tiktok/song" }, "x-credits": 1, "parameters": [ { "name": "clipId", "in": "query", "required": true, "description": "The sound's id, e.g. `7433619007506761744`, or its URL (`https://www.tiktok.com/music/…-`). Every video carries it as `music.id`.", "schema": { "description": "The sound's id, e.g. `7433619007506761744`, or its URL (`https://www.tiktok.com/music/…-`). Every video carries it as `music.id`.", "type": "string" }, "example": "7433619007506761744" } ], "responses": { "200": { "description": "A TikTok sound: title, artist, album, length, cover, audio URL and how many videos use it.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "const": true, "description": "Always true here; errors have `success: false`." }, "credits_remaining": { "type": "number", "description": "Your balance after this call. On anonymous playground calls: free tries left today." }, "credits_charged": { "type": "number", "description": "Credits this call cost; 0 on free endpoints. On anonymous playground calls: tries used (1)." }, "id": { "type": "string", "description": "Sound id." }, "url": { "type": "string", "description": "The sound's page on tiktok.com." }, "title": { "type": "string", "description": "Sound title, e.g. `original sound` or the track name." }, "authorName": { "description": "Artist, or the creator's display name for original sounds.", "type": [ "string", "null" ] }, "album": { "description": "Album of a released track; null for original sounds and when TikTok doesn't say.", "type": [ "string", "null" ] }, "original": { "type": "boolean", "description": "An original sound a creator made, rather than a released track." }, "duration": { "description": "Length in seconds (for tracks, the clip TikTok offers); null if unknown.", "type": [ "number", "null" ] }, "cover": { "description": "Cover art URL (may expire after a few days); null if TikTok has none.", "type": [ "string", "null" ] }, "playUrl": { "description": "Audio URL (may expire after a few hours); null if TikTok has none.", "type": [ "string", "null" ] }, "videoCount": { "type": "number", "description": "Posts using this sound." }, "isCopyrighted": { "type": "boolean", "description": "TikTok marks the sound as copyrighted." }, "is_commerce_music": { "type": "boolean", "description": "TikTok's commercial-use flag: cleared for business accounts and ads." }, "author": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "description": "Numeric user id." }, "uniqueId": { "type": "string", "description": "Username (handle), without @." }, "nickname": { "type": "string", "description": "Display name." }, "secUid": { "type": "string", "description": "TikTok's long, stable user id." }, "avatarThumb": { "description": "Small avatar URL (expires after a few days); null if TikTok has none.", "type": [ "string", "null" ] } }, "required": [ "id", "uniqueId", "nickname", "secUid", "avatarThumb" ], "additionalProperties": false }, { "type": "null" } ], "description": "The TikTok account behind the sound: its creator for original sounds, the artist's account for tracks; null if none." } }, "required": [ "success", "credits_remaining", "credits_charged", "id", "url", "title", "authorName", "album", "original", "duration", "cover", "playUrl", "videoCount", "isCopyrighted", "is_commerce_music", "author" ], "additionalProperties": false } } } }, "404": { "description": "not_found: The endpoint, or the thing you asked for (ad, post, subreddit), doesn't exist. Charged when the platform was checked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error. Not charged, except the endpoint's own 4xx answers such as not_found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/tiktok/song/videos": { "get": { "operationId": "tiktok_song_videos", "tags": [ "TikTok" ], "summary": "Song videos", "description": "Videos that use a sound, 30 per page, with stats and creators.\n\nUse it to see how a sound is being used: which creators and brands post with it and how their posts perform. Videos come in the order tiktok.com shows them on the sound's page, roughly most viewed first.\n\n**Pagination.** Up to 30 videos per page. Pass the response's `cursor` back as `cursor` (with the same `clipId`) for more; `has_more` is false at the end. TikTok only lists posts it still shows, so older sounds can list far fewer videos than their `videoCount` in song.\n\nUnknown sounds return 404 `not_found`.\n\nCost: 1 credit.", "externalDocs": { "url": "https://lurkapi.com/docs/tiktok/song-videos" }, "x-credits": 1, "parameters": [ { "name": "clipId", "in": "query", "required": true, "description": "The sound's id, e.g. `7433619007506761744`, or its URL (`https://www.tiktok.com/music/…-`). Every video carries it as `music.id`.", "schema": { "description": "The sound's id, e.g. `7433619007506761744`, or its URL (`https://www.tiktok.com/music/…-`). Every video carries it as `music.id`.", "type": "string" }, "example": "7433619007506761744" }, { "name": "cursor", "in": "query", "required": false, "description": "The `cursor` from the previous response, to get the next page.", "schema": { "description": "The `cursor` from the previous response, to get the next page.", "type": "string", "pattern": "^\\d{1,20}$" } } ], "responses": { "200": { "description": "Videos that use a sound, 30 per page, with stats and creators.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "const": true, "description": "Always true here; errors have `success: false`." }, "credits_remaining": { "type": "number", "description": "Your balance after this call. On anonymous playground calls: free tries left today." }, "credits_charged": { "type": "number", "description": "Credits this call cost; 0 on free endpoints. On anonymous playground calls: tries used (1)." }, "videos": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Video id, e.g. `7671325437229845774`." }, "url": { "type": "string", "description": "The post on tiktok.com." }, "desc": { "type": "string", "description": "Caption, hashtags included." }, "createTime": { "type": "number", "description": "Posted at, Unix seconds." }, "textLanguage": { "description": "Caption language as TikTok detects it, e.g. `en`; null if unknown.", "type": [ "string", "null" ] }, "locationCreated": { "description": "Country the post was made in, as a 2-letter code; null if unknown.", "type": [ "string", "null" ] }, "isAd": { "type": "boolean", "description": "A paid ad (Spark Ad or promoted post)." }, "author": { "type": "object", "properties": { "id": { "type": "string", "description": "Numeric user id." }, "uniqueId": { "type": "string", "description": "Username (handle), without @." }, "nickname": { "type": "string", "description": "Display name." }, "secUid": { "type": "string", "description": "TikTok's long, stable user id; other tools ask for it." }, "verified": { "type": "boolean", "description": "Has the verified badge." }, "privateAccount": { "type": "boolean", "description": "The account is private." }, "avatarThumb": { "description": "Small avatar URL (expires after a few days); null if TikTok has none.", "type": [ "string", "null" ] }, "avatarLarger": { "description": "Large avatar URL (expires after a few days); null if TikTok has none.", "type": [ "string", "null" ] } }, "required": [ "id", "uniqueId", "nickname", "secUid", "verified", "privateAccount", "avatarThumb", "avatarLarger" ], "additionalProperties": false, "description": "Who posted it." }, "stats": { "type": "object", "properties": { "playCount": { "type": "number", "description": "Views." }, "diggCount": { "type": "number", "description": "Likes." }, "commentCount": { "type": "number", "description": "Comments." }, "shareCount": { "type": "number", "description": "Shares." }, "collectCount": { "description": "Saves (favorites); null where TikTok doesn't show it.", "type": [ "number", "null" ] }, "repostCount": { "description": "Reposts; null where TikTok doesn't show it.", "type": [ "number", "null" ] } }, "required": [ "playCount", "diggCount", "commentCount", "shareCount", "collectCount", "repostCount" ], "additionalProperties": false, "description": "Engagement when fetched. Exact numbers, not rounded." }, "video": { "type": "object", "properties": { "duration": { "type": "number", "description": "Length in seconds; 0 for photo posts." }, "width": { "type": "number", "description": "Width in pixels; 0 for photo posts." }, "height": { "type": "number", "description": "Height in pixels; 0 for photo posts." }, "definition": { "description": "Quality of the default rendition, e.g. `720p`.", "type": [ "string", "null" ] }, "cover": { "description": "Cover image URL (expires after a few days); null if TikTok has none.", "type": [ "string", "null" ] }, "dynamicCover": { "description": "Animated cover URL (expires after a few days); null if TikTok has none.", "type": [ "string", "null" ] }, "playUrl": { "description": "MP4 URL that plays without cookies (h264, best quality). It redirects to TikTok's CDN and expires at `expires_at`; null if TikTok has none.", "type": [ "string", "null" ] }, "expires_at": { "description": "When `playUrl` stops working, Unix seconds; null if unknown.", "type": [ "number", "null" ] } }, "required": [ "duration", "width", "height", "definition", "cover", "dynamicCover", "playUrl", "expires_at" ], "additionalProperties": false, "description": "The video file. For photo posts see `images`." }, "music": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "description": "Sound id; pass it to song endpoints." }, "title": { "type": "string", "description": "Sound title, e.g. `original sound`." }, "authorName": { "description": "Artist, or the creator for original sounds.", "type": [ "string", "null" ] }, "original": { "type": "boolean", "description": "An original sound made with this post rather than a track." }, "duration": { "description": "Length in seconds.", "type": [ "number", "null" ] }, "playUrl": { "description": "Audio URL (expires after a few hours); null if TikTok has none.", "type": [ "string", "null" ] }, "cover": { "description": "Sound cover image URL; null if TikTok has none.", "type": [ "string", "null" ] } }, "required": [ "id", "title", "authorName", "original", "duration", "playUrl", "cover" ], "additionalProperties": false }, { "type": "null" } ], "description": "The sound; null if the post has none." }, "hashtags": { "type": "array", "items": { "type": "string", "description": "Hashtag without #." }, "description": "Hashtags in the caption, without #." }, "mentions": { "type": "array", "items": { "type": "string", "description": "Username without @." }, "description": "Usernames @mentioned in the caption." }, "images": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string", "description": "Image URL (expires after a few days)." }, "width": { "type": "number", "description": "Width in pixels." }, "height": { "type": "number", "description": "Height in pixels." } }, "required": [ "url", "width", "height" ], "additionalProperties": false }, "description": "The slides of a photo post, in order. Empty for videos." } }, "required": [ "id", "url", "desc", "createTime", "textLanguage", "locationCreated", "isAd", "author", "stats", "video", "music", "hashtags", "mentions", "images" ], "additionalProperties": false }, "description": "Posts, in the order tiktok.com shows them (not newest first)." }, "has_more": { "type": "boolean", "description": "There are more posts after this page." }, "cursor": { "description": "Pass as `cursor` for the next page. null on the last page.", "type": [ "string", "null" ] } }, "required": [ "success", "credits_remaining", "credits_charged", "videos", "has_more", "cursor" ], "additionalProperties": false } } } }, "404": { "description": "not_found: The endpoint, or the thing you asked for (ad, post, subreddit), doesn't exist. Charged when the platform was checked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error. Not charged, except the endpoint's own 4xx answers such as not_found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/tiktok/ad-library/search": { "get": { "operationId": "tiktok_ad_library_search", "tags": [ "TikTok" ], "summary": "Search TikTok Ad Library", "description": "Ads shown in the EU, the UK, Switzerland and Turkey that match a keyword or an advertiser, 12 per page.\n\nUse it to see what a brand or a category advertises on TikTok: each ad with its advertiser, caption, video or images, when it ran and roughly how many people saw it. This is TikTok's Ad Library under the EU Digital Services Act, so it only has ads shown in the EU/EEA, Switzerland, the UK and Turkey. Ads shown only in the US or elsewhere aren't in it.\n\nSearch by `query`, a keyword matched against ad text and advertiser names (so resellers show up too), or by `advertiser_name` for one advertiser's ads, spelled as the library shows it (e.g. `NIKE Retail B.V.`, as in a result's `advertiser_name`). Results are ads shown in the last 30 days, most relevant first. `region` narrows them to one country; an ad that ran in several countries appears under each.\n\n**Pagination.** 12 ads per page. Pass the response's `cursor` back as `cursor` (with the same params) for more; `has_more` is false at the end. For keyword searches `total` stops counting at 5,000.\n\nAn `advertiser_name` the library doesn't know returns 404 `not_found`, with close matches in the message.\n\nCost: 1 credit.", "externalDocs": { "url": "https://lurkapi.com/docs/tiktok/ad-library-search" }, "x-credits": 1, "parameters": [ { "name": "query", "in": "query", "required": false, "description": "Keyword, e.g. `running shoes`. Pass this or `advertiser_name`.", "schema": { "description": "Keyword, e.g. `running shoes`. Pass this or `advertiser_name`.", "type": "string", "minLength": 1, "maxLength": 100 }, "example": "running shoes" }, { "name": "advertiser_name", "in": "query", "required": false, "description": "One advertiser's name as the library shows it, e.g. `NIKE Retail B.V.` Pass this or `query`.", "schema": { "description": "One advertiser's name as the library shows it, e.g. `NIKE Retail B.V.` Pass this or `query`.", "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "region", "in": "query", "required": false, "description": "Where the ads were shown: a 2-letter country code (DE, FR, GB, …) of the 33 countries the library covers, or `all`.", "schema": { "description": "Where the ads were shown: a 2-letter country code (DE, FR, GB, …) of the 33 countries the library covers, or `all`.", "default": "all", "type": "string", "enum": [ "all", "AT", "BE", "BG", "CH", "CY", "CZ", "DE", "DK", "EE", "ES", "FI", "FR", "GB", "GR", "HR", "HU", "IE", "IS", "IT", "LI", "LT", "LU", "LV", "MT", "NL", "NO", "PL", "PT", "RO", "SE", "SI", "SK", "TR" ] }, "example": "DE" }, { "name": "cursor", "in": "query", "required": false, "description": "The `cursor` from the previous response, to get the next page. Keep every other param the same.", "schema": { "description": "The `cursor` from the previous response, to get the next page. Keep every other param the same.", "type": "string", "pattern": "^[A-Za-z0-9+/=_-]{1,400}$" } } ], "responses": { "200": { "description": "Ads shown in the EU, the UK, Switzerland and Turkey that match a keyword or an advertiser, 12 per page.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "const": true, "description": "Always true here; errors have `success: false`." }, "credits_remaining": { "type": "number", "description": "Your balance after this call. On anonymous playground calls: free tries left today." }, "credits_charged": { "type": "number", "description": "Credits this call cost; 0 on free endpoints. On anonymous playground calls: tries used (1)." }, "ads": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Ad id. Pass it as `ad_id` to TikTok Ad Library ad for targeting and reach." }, "url": { "type": "string", "description": "The ad on library.tiktok.com." }, "advertiser_name": { "description": "The advertiser as registered with TikTok; null for the few ads published without one.", "type": [ "string", "null" ] }, "title": { "description": "The ad's caption text; null if it has none.", "type": [ "string", "null" ] }, "category": { "description": "TikTok's category for the ad, e.g. `Apparel & Accessories` or `Apps`; null if none.", "type": [ "string", "null" ] }, "first_shown": { "type": "number", "description": "First day the ad was shown in the library's countries, Unix seconds (midnight UTC)." }, "last_shown": { "type": "number", "description": "Latest day it was shown, Unix seconds (midnight UTC). Yesterday or today for ads still running." }, "estimated_audience": { "description": "TikTok's estimate of unique users who saw the ad at least once, as a range such as `10K-100K`; null if not given.", "type": [ "string", "null" ] }, "videos": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string", "description": "MP4 URL. It redirects to TikTok's CDN and expires about 6 hours after we fetched the ad." }, "cover": { "description": "Cover image URL (expires about 6 hours after we fetched the ad); null if none.", "type": [ "string", "null" ] } }, "required": [ "url", "cover" ], "additionalProperties": false }, "description": "The ad's videos, usually one. Empty for image ads." }, "image_urls": { "type": "array", "items": { "type": "string", "description": "Image URL (expires after a few hours)." }, "description": "The ad's images, in order. Empty for most video ads." } }, "required": [ "id", "url", "advertiser_name", "title", "category", "first_shown", "last_shown", "estimated_audience", "videos", "image_urls" ], "additionalProperties": false }, "description": "Ads, most relevant first." }, "total": { "type": "number", "description": "Ads matching the search in the last 30 days. Keyword searches stop counting at 5,000." }, "has_more": { "type": "boolean", "description": "There are more ads after this page." }, "cursor": { "description": "Pass as `cursor` for the next page. null on the last page.", "type": [ "string", "null" ] } }, "required": [ "success", "credits_remaining", "credits_charged", "ads", "total", "has_more", "cursor" ], "additionalProperties": false } } } }, "404": { "description": "not_found: The endpoint, or the thing you asked for (ad, post, subreddit), doesn't exist. Charged when the platform was checked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error. Not charged, except the endpoint's own 4xx answers such as not_found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/tiktok/ad-library/ad": { "get": { "operationId": "tiktok_ad_library_ad", "tags": [ "TikTok" ], "summary": "TikTok Ad Library ad", "description": "One ad from TikTok's EU Ad Library: creative, landing page, advertiser, who paid, targeting and reach by country, age and gender.\n\nUse it to see how an ad was targeted and whom it reached: the countries, ages, genders and interests the advertiser chose, TikTok's estimate of how many users matched, and unique reach per country (split by age and gender for ads shown since June 2026). You also get the landing page, call to action, objective, who paid for the ad and the advertiser's TikTok account.\n\nGet `ad_id` from TikTok Ad Library search, or paste the ad's library.tiktok.com URL. Like the search, it only covers ads shown in the EU/EEA, Switzerland, the UK and Turkey.\n\nUnknown ids return 404 `not_found`.\n\nCost: 1 credit.", "externalDocs": { "url": "https://lurkapi.com/docs/tiktok/ad-library-ad" }, "x-credits": 1, "parameters": [ { "name": "ad_id", "in": "query", "required": true, "description": "The ad's `id` from TikTok Ad Library search, e.g. `1876319908813409`, or its library.tiktok.com/ads/detail/?ad_id=… URL.", "schema": { "description": "The ad's `id` from TikTok Ad Library search, e.g. `1876319908813409`, or its library.tiktok.com/ads/detail/?ad_id=… URL.", "type": "string" }, "example": "1876319908813409" } ], "responses": { "200": { "description": "One ad from TikTok's EU Ad Library: creative, landing page, advertiser, who paid, targeting and reach by country, age and gender.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "const": true, "description": "Always true here; errors have `success: false`." }, "credits_remaining": { "type": "number", "description": "Your balance after this call. On anonymous playground calls: free tries left today." }, "credits_charged": { "type": "number", "description": "Credits this call cost; 0 on free endpoints. On anonymous playground calls: tries used (1)." }, "id": { "type": "string", "description": "Ad id. Pass it as `ad_id` to TikTok Ad Library ad for targeting and reach." }, "url": { "type": "string", "description": "The ad on library.tiktok.com." }, "advertiser_name": { "description": "The advertiser as registered with TikTok; null for the few ads published without one.", "type": [ "string", "null" ] }, "title": { "description": "The ad's caption text; null if it has none.", "type": [ "string", "null" ] }, "category": { "description": "TikTok's category for the ad, e.g. `Apparel & Accessories` or `Apps`; null if none.", "type": [ "string", "null" ] }, "first_shown": { "type": "number", "description": "First day the ad was shown in the library's countries, Unix seconds (midnight UTC)." }, "last_shown": { "type": "number", "description": "Latest day it was shown, Unix seconds (midnight UTC). Yesterday or today for ads still running." }, "estimated_audience": { "description": "TikTok's estimate of unique users who saw the ad at least once, as a range such as `10K-100K`; null if not given.", "type": [ "string", "null" ] }, "videos": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string", "description": "MP4 URL. It redirects to TikTok's CDN and expires about 6 hours after we fetched the ad." }, "cover": { "description": "Cover image URL (expires about 6 hours after we fetched the ad); null if none.", "type": [ "string", "null" ] } }, "required": [ "url", "cover" ], "additionalProperties": false }, "description": "The ad's videos, usually one. Empty for image ads." }, "image_urls": { "type": "array", "items": { "type": "string", "description": "Image URL (expires after a few hours)." }, "description": "The ad's images, in order. Empty for most video ads." }, "external_url": { "description": "Where the ad sends people: the landing page, or the app store page for app ads; null if none.", "type": [ "string", "null" ] }, "call_to_action": { "description": "The button text, e.g. `Shop now`; null if none.", "type": [ "string", "null" ] }, "objective": { "description": "The advertiser's campaign objective, e.g. `Traffic` or `Sales`; null if not given.", "type": [ "string", "null" ] }, "advertiser": { "type": "object", "properties": { "name": { "description": "The advertiser as registered with TikTok.", "type": [ "string", "null" ] }, "adv_biz_ids": { "description": "TikTok's business id for the advertiser, e.g. `6876453864464188162`.", "type": [ "string", "null" ] }, "registry_location": { "description": "Country the advertiser is registered in, e.g. `Germany`.", "type": [ "string", "null" ] }, "sponsor": { "description": "Who paid for the ad (\"Ad paid for by\"), often an agency or the advertiser itself; null if not given.", "type": [ "string", "null" ] }, "tiktok_user": { "anyOf": [ { "type": "object", "properties": { "username": { "type": "string", "description": "TikTok username (handle), without @. Pass it to the profile endpoint." }, "display_name": { "description": "Display name.", "type": [ "string", "null" ] }, "followers": { "description": "Followers as TikTok rounds them in the library, e.g. `319.1K`.", "type": [ "string", "null" ] }, "avatar_url": { "description": "Avatar URL (expires after a few days).", "type": [ "string", "null" ] }, "url": { "type": "string", "description": "The account on tiktok.com." } }, "required": [ "username", "display_name", "followers", "avatar_url", "url" ], "additionalProperties": false }, { "type": "null" } ], "description": "The advertiser's TikTok account; null when the ad didn't run from one." } }, "required": [ "name", "adv_biz_ids", "registry_location", "sponsor", "tiktok_user" ], "additionalProperties": false, "description": "Who ran the ad." }, "targeting": { "type": "object", "properties": { "countries": { "type": "array", "items": { "type": "string" }, "description": "Countries targeted, as 2-letter codes." }, "age": { "type": "array", "items": { "type": "string" }, "description": "Age ranges targeted, e.g. `18-24`, `25-34` or `55+` (in any of the countries)." }, "gender": { "type": "array", "items": { "type": "string" }, "description": "Genders targeted: `female`, `male` and/or `unknown`." }, "audience_size": { "description": "TikTok's estimate of how many users matched the targeting, e.g. `3.9M-4.8M`.", "type": [ "string", "null" ] }, "interests": { "type": "array", "items": { "type": "string" }, "description": "Interest categories targeted, e.g. `Sports`. Empty if none." }, "video_interactions": { "type": "array", "items": { "type": "string" }, "description": "Categories of videos the audience interacted with. Empty if not used." }, "creator_interactions": { "type": "array", "items": { "type": "string" }, "description": "Categories of creators the audience followed or watched. Empty if not used." }, "languages": { "type": "array", "items": { "type": "string" }, "description": "Languages targeted. Empty means any." }, "operating_systems": { "type": "array", "items": { "type": "string" }, "description": "Operating systems targeted, e.g. `ANDROID`. Empty means any." } }, "required": [ "countries", "age", "gender", "audience_size", "interests", "video_interactions", "creator_interactions", "languages", "operating_systems" ], "additionalProperties": false, "description": "The main ways the advertiser chose to reach people. TikTok may also have shown the ad for other reasons." }, "reach_by_country": { "type": "array", "items": { "type": "object", "properties": { "country": { "type": "string", "description": "2-letter country code." }, "users": { "type": "string", "description": "Unique users reached there, e.g. `540K` or a range like `0-1K`." }, "by_age_gender": { "type": "array", "items": { "type": "object", "properties": { "age": { "type": "string", "description": "Age range, e.g. `18-24` or `55+`." }, "gender": { "type": "string", "description": "`female`, `male` or `unknown`." }, "users": { "type": "string", "description": "Unique users reached in this group, e.g. `302K` or `0-1K`." } }, "required": [ "age", "gender", "users" ], "additionalProperties": false }, "description": "Reach split by age and gender. TikTok only publishes it for ads shown since June 2026; empty otherwise." } }, "required": [ "country", "users", "by_age_gender" ], "additionalProperties": false, "description": "Reach in one country." }, "description": "Unique users reached, per country." } }, "required": [ "success", "credits_remaining", "credits_charged", "id", "url", "advertiser_name", "title", "category", "first_shown", "last_shown", "estimated_audience", "videos", "image_urls", "external_url", "call_to_action", "objective", "advertiser", "targeting", "reach_by_country" ], "additionalProperties": false } } } }, "404": { "description": "not_found: The endpoint, or the thing you asked for (ad, post, subreddit), doesn't exist. Charged when the platform was checked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error. Not charged, except the endpoint's own 4xx answers such as not_found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/tiktok/user/live": { "get": { "operationId": "tiktok_live", "tags": [ "TikTok" ], "summary": "Live status", "description": "Whether a public creator is live, with the current room title, viewers and start time.\n\nCheck a creator before a campaign or live collaboration. A room id on the profile can belong to a finished stream, so this endpoint verifies the room's status. Only an active stream returns room details; offline accounts return `is_live: false` and null room fields. Refreshes every 30 seconds. Unknown accounts return 404 `not_found`.\n\nCost: 1 credit.", "externalDocs": { "url": "https://lurkapi.com/docs/tiktok/live" }, "x-credits": 1, "parameters": [ { "name": "handle", "in": "query", "required": true, "description": "TikTok username, with or without @ (e.g. `nike`), or the profile URL.", "schema": { "description": "TikTok username, with or without @ (e.g. `nike`), or the profile URL.", "type": "string" }, "example": "tiktok" } ], "responses": { "200": { "description": "Whether a public creator is live, with the current room title, viewers and start time.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "const": true, "description": "Always true here; errors have `success: false`." }, "credits_remaining": { "type": "number", "description": "Your balance after this call. On anonymous playground calls: free tries left today." }, "credits_charged": { "type": "number", "description": "Credits this call cost; 0 on free endpoints. On anonymous playground calls: tries used (1)." }, "user": { "type": "object", "properties": { "id": { "type": "string", "description": "Numeric user id." }, "uniqueId": { "type": "string", "description": "Username (handle), without @." }, "nickname": { "type": "string", "description": "Display name." }, "avatarThumb": { "description": "Small avatar URL (expires after a few days); null if TikTok has none.", "type": [ "string", "null" ] }, "verified": { "type": "boolean", "description": "Has the verified badge." } }, "required": [ "id", "uniqueId", "nickname", "avatarThumb", "verified" ], "additionalProperties": false, "description": "The creator." }, "is_live": { "type": "boolean", "description": "TikTok reports an active livestream (room status 2)." }, "room_id": { "description": "Current live room id; null when offline.", "type": [ "string", "null" ] }, "title": { "description": "Current stream title; null when offline or unavailable.", "type": [ "string", "null" ] }, "started_at": { "description": "Current stream start time, Unix seconds; null when offline or unknown.", "type": [ "number", "null" ] }, "viewer_count": { "description": "Current concurrent viewers; null when offline or unknown.", "type": [ "number", "null" ] }, "total_joins": { "description": "Total joins since this stream started; null when offline or unknown.", "type": [ "number", "null" ] } }, "required": [ "success", "credits_remaining", "credits_charged", "user", "is_live", "room_id", "title", "started_at", "viewer_count", "total_joins" ], "additionalProperties": false } } } }, "404": { "description": "not_found: The endpoint, or the thing you asked for (ad, post, subreddit), doesn't exist. Charged when the platform was checked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error. Not charged, except the endpoint's own 4xx answers such as not_found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/tiktok/user/stories": { "get": { "operationId": "tiktok_stories", "tags": [ "TikTok" ], "summary": "Public stories", "description": "A creator's active public stories, with captions, media and expiration times.\n\nSee the temporary content a public creator shares alongside regular posts. Each story includes the usual post fields and its `expires_at` time. Returns up to 20 stories, oldest first; `has_more` warns if TikTok reports additional stories beyond this page. This endpoint does not paginate. No active stories returns an empty list. Only stories TikTok exposes to logged-out visitors are available; private stories are excluded. Unknown accounts return 404 `not_found`.\n\nCost: 1 credit.", "externalDocs": { "url": "https://lurkapi.com/docs/tiktok/stories" }, "x-credits": 1, "parameters": [ { "name": "handle", "in": "query", "required": true, "description": "TikTok username, with or without @ (e.g. `nike`), or the profile URL.", "schema": { "description": "TikTok username, with or without @ (e.g. `nike`), or the profile URL.", "type": "string" }, "example": "nono95118" } ], "responses": { "200": { "description": "A creator's active public stories, with captions, media and expiration times.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "const": true, "description": "Always true here; errors have `success: false`." }, "credits_remaining": { "type": "number", "description": "Your balance after this call. On anonymous playground calls: free tries left today." }, "credits_charged": { "type": "number", "description": "Credits this call cost; 0 on free endpoints. On anonymous playground calls: tries used (1)." }, "user": { "type": "object", "properties": { "id": { "type": "string", "description": "Numeric user id." }, "uniqueId": { "type": "string", "description": "Username (handle), without @." }, "nickname": { "type": "string", "description": "Display name." }, "avatarThumb": { "description": "Small avatar URL (expires after a few days); null if TikTok has none.", "type": [ "string", "null" ] }, "verified": { "type": "boolean", "description": "Has the verified badge." } }, "required": [ "id", "uniqueId", "nickname", "avatarThumb", "verified" ], "additionalProperties": false, "description": "The creator." }, "stories": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Video id, e.g. `7671325437229845774`." }, "url": { "type": "string", "description": "The post on tiktok.com." }, "desc": { "type": "string", "description": "Caption, hashtags included." }, "createTime": { "type": "number", "description": "Posted at, Unix seconds." }, "textLanguage": { "description": "Caption language as TikTok detects it, e.g. `en`; null if unknown.", "type": [ "string", "null" ] }, "locationCreated": { "description": "Country the post was made in, as a 2-letter code; null if unknown.", "type": [ "string", "null" ] }, "isAd": { "type": "boolean", "description": "A paid ad (Spark Ad or promoted post)." }, "author": { "type": "object", "properties": { "id": { "type": "string", "description": "Numeric user id." }, "uniqueId": { "type": "string", "description": "Username (handle), without @." }, "nickname": { "type": "string", "description": "Display name." }, "secUid": { "type": "string", "description": "TikTok's long, stable user id; other tools ask for it." }, "verified": { "type": "boolean", "description": "Has the verified badge." }, "privateAccount": { "type": "boolean", "description": "The account is private." }, "avatarThumb": { "description": "Small avatar URL (expires after a few days); null if TikTok has none.", "type": [ "string", "null" ] }, "avatarLarger": { "description": "Large avatar URL (expires after a few days); null if TikTok has none.", "type": [ "string", "null" ] } }, "required": [ "id", "uniqueId", "nickname", "secUid", "verified", "privateAccount", "avatarThumb", "avatarLarger" ], "additionalProperties": false, "description": "Who posted it." }, "stats": { "type": "object", "properties": { "playCount": { "type": "number", "description": "Views." }, "diggCount": { "type": "number", "description": "Likes." }, "commentCount": { "type": "number", "description": "Comments." }, "shareCount": { "type": "number", "description": "Shares." }, "collectCount": { "description": "Saves (favorites); null where TikTok doesn't show it.", "type": [ "number", "null" ] }, "repostCount": { "description": "Reposts; null where TikTok doesn't show it.", "type": [ "number", "null" ] } }, "required": [ "playCount", "diggCount", "commentCount", "shareCount", "collectCount", "repostCount" ], "additionalProperties": false, "description": "Engagement when fetched. Exact numbers, not rounded." }, "video": { "type": "object", "properties": { "duration": { "type": "number", "description": "Length in seconds; 0 for photo posts." }, "width": { "type": "number", "description": "Width in pixels; 0 for photo posts." }, "height": { "type": "number", "description": "Height in pixels; 0 for photo posts." }, "definition": { "description": "Quality of the default rendition, e.g. `720p`.", "type": [ "string", "null" ] }, "cover": { "description": "Cover image URL (expires after a few days); null if TikTok has none.", "type": [ "string", "null" ] }, "dynamicCover": { "description": "Animated cover URL (expires after a few days); null if TikTok has none.", "type": [ "string", "null" ] }, "playUrl": { "description": "MP4 URL that plays without cookies (h264, best quality). It redirects to TikTok's CDN and expires at `expires_at`; null if TikTok has none.", "type": [ "string", "null" ] }, "expires_at": { "description": "When `playUrl` stops working, Unix seconds; null if unknown.", "type": [ "number", "null" ] } }, "required": [ "duration", "width", "height", "definition", "cover", "dynamicCover", "playUrl", "expires_at" ], "additionalProperties": false, "description": "The video file. For photo posts see `images`." }, "music": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "description": "Sound id; pass it to song endpoints." }, "title": { "type": "string", "description": "Sound title, e.g. `original sound`." }, "authorName": { "description": "Artist, or the creator for original sounds.", "type": [ "string", "null" ] }, "original": { "type": "boolean", "description": "An original sound made with this post rather than a track." }, "duration": { "description": "Length in seconds.", "type": [ "number", "null" ] }, "playUrl": { "description": "Audio URL (expires after a few hours); null if TikTok has none.", "type": [ "string", "null" ] }, "cover": { "description": "Sound cover image URL; null if TikTok has none.", "type": [ "string", "null" ] } }, "required": [ "id", "title", "authorName", "original", "duration", "playUrl", "cover" ], "additionalProperties": false }, { "type": "null" } ], "description": "The sound; null if the post has none." }, "hashtags": { "type": "array", "items": { "type": "string", "description": "Hashtag without #." }, "description": "Hashtags in the caption, without #." }, "mentions": { "type": "array", "items": { "type": "string", "description": "Username without @." }, "description": "Usernames @mentioned in the caption." }, "images": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string", "description": "Image URL (expires after a few days)." }, "width": { "type": "number", "description": "Width in pixels." }, "height": { "type": "number", "description": "Height in pixels." } }, "required": [ "url", "width", "height" ], "additionalProperties": false }, "description": "The slides of a photo post, in order. Empty for videos." }, "expires_at": { "type": "number", "description": "When this story expires, Unix seconds." } }, "required": [ "id", "url", "desc", "createTime", "textLanguage", "locationCreated", "isAd", "author", "stats", "video", "music", "hashtags", "mentions", "images", "expires_at" ], "additionalProperties": false }, "description": "Active public stories, oldest first, up to 20." }, "total_count": { "type": "number", "description": "Total stories TikTok reported when fetched; may exceed the returned page." }, "has_more": { "type": "boolean", "description": "TikTok reports stories beyond this page; this endpoint does not paginate." } }, "required": [ "success", "credits_remaining", "credits_charged", "user", "stories", "total_count", "has_more" ], "additionalProperties": false } } } }, "404": { "description": "not_found: The endpoint, or the thing you asked for (ad, post, subreddit), doesn't exist. Charged when the platform was checked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error. Not charged, except the endpoint's own 4xx answers such as not_found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/tiktok/product": { "get": { "operationId": "tiktok_product", "tags": [ "TikTok" ], "summary": "TikTok Shop product", "description": "A US TikTok Shop product's price, images, seller, variants, sales and review totals.\n\nInspect a product sold through the US TikTok Shop: public product copy, price, variant inventory, seller and category information. Prices are decimal strings in the reported currency and reflect the logged-out US storefront; checkout discounts and shipping can differ. Sales and reviews are lifetime totals, not a time series. This endpoint returns a single product, not Shop search or review pages. Other storefront countries are not supported.\n\nCost: 1 credit.", "externalDocs": { "url": "https://lurkapi.com/docs/tiktok/product" }, "x-credits": 1, "parameters": [ { "name": "url", "in": "query", "required": true, "description": "US product URL on shop.tiktok.com/us/pdp/… or its numeric product id.", "schema": { "description": "US product URL on shop.tiktok.com/us/pdp/… or its numeric product id.", "type": "string" }, "example": "https://shop.tiktok.com/us/pdp/biodance-collagen-mask-pdrn-sea-kelp-overnight-hydration/1732049122233848586" } ], "responses": { "200": { "description": "A US TikTok Shop product's price, images, seller, variants, sales and review totals.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "const": true, "description": "Always true here; errors have `success: false`." }, "credits_remaining": { "type": "number", "description": "Your balance after this call. On anonymous playground calls: free tries left today." }, "credits_charged": { "type": "number", "description": "Credits this call cost; 0 on free endpoints. On anonymous playground calls: tries used (1)." }, "id": { "type": "string", "description": "TikTok Shop product id." }, "url": { "type": "string", "description": "Canonical US storefront product URL." }, "region": { "type": "string", "const": "US", "description": "Storefront country; this endpoint supports US products." }, "title": { "type": "string", "description": "Product name." }, "description": { "type": "string", "description": "Public product description as plain text." }, "sold_count": { "description": "Lifetime items sold globally, excluding returns; null when unavailable.", "type": [ "number", "null" ] }, "price": { "type": "object", "properties": { "currency": { "description": "Currency code, e.g. USD; null when unavailable.", "type": [ "string", "null" ] }, "amount": { "description": "Lowest variant sale price as a decimal string; null when unavailable.", "type": [ "string", "null" ] }, "original_amount": { "description": "Lowest variant original price before discount, as a decimal string; null when unavailable.", "type": [ "string", "null" ] }, "display": { "description": "Storefront formatted sale price; null when unavailable.", "type": [ "string", "null" ] } }, "required": [ "currency", "amount", "original_amount", "display" ], "additionalProperties": false, "description": "Public logged-out storefront price." }, "images": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string", "description": "Product image URL." }, "width": { "description": "Image width in pixels; null when unknown.", "type": [ "number", "null" ] }, "height": { "description": "Image height in pixels; null when unknown.", "type": [ "number", "null" ] } }, "required": [ "url", "width", "height" ], "additionalProperties": false }, "description": "Product images in gallery order." }, "categories": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Category id." }, "name": { "type": "string", "description": "Category name." } }, "required": [ "id", "name" ], "additionalProperties": false }, "description": "Category hierarchy, broadest first." }, "specifications": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Specification name." }, "value": { "type": "string", "description": "Specification value." } }, "required": [ "name", "value" ], "additionalProperties": false }, "description": "Product specifications, such as brand and ingredients." }, "seller": { "type": "object", "properties": { "id": { "type": "string", "description": "Seller id." }, "name": { "description": "Seller storefront name; null when unavailable.", "type": [ "string", "null" ] }, "url": { "description": "Seller storefront URL; null when unavailable.", "type": [ "string", "null" ] }, "avatar": { "description": "Seller avatar URL; null when unavailable.", "type": [ "string", "null" ] }, "rating": { "description": "Seller rating out of 5; null when unavailable.", "type": [ "number", "null" ] }, "follower_count": { "description": "Store followers; null when unavailable.", "type": [ "number", "null" ] }, "product_count": { "description": "Products in the store; null when unavailable.", "type": [ "number", "null" ] } }, "required": [ "id", "name", "url", "avatar", "rating", "follower_count", "product_count" ], "additionalProperties": false, "description": "The seller." }, "rating": { "description": "Product rating out of 5; null when unavailable.", "type": [ "number", "null" ] }, "review_count": { "description": "Total product reviews; null when unavailable.", "type": [ "number", "null" ] }, "variants": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "SKU id." }, "stock": { "description": "Stock TikTok exposes for this variant; null when unavailable.", "type": [ "number", "null" ] }, "price": { "description": "Variant sale price as a decimal string; null when unavailable.", "type": [ "string", "null" ] }, "currency": { "description": "Variant currency code; null when unavailable.", "type": [ "string", "null" ] }, "properties": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Option name." }, "value": { "type": "string", "description": "Option value." } }, "required": [ "name", "value" ], "additionalProperties": false }, "description": "Variant options, such as size or color." } }, "required": [ "id", "stock", "price", "currency", "properties" ], "additionalProperties": false }, "description": "Publicly listed product variants." } }, "required": [ "success", "credits_remaining", "credits_charged", "id", "url", "region", "title", "description", "sold_count", "price", "images", "categories", "specifications", "seller", "rating", "review_count", "variants" ], "additionalProperties": false } } } }, "404": { "description": "not_found: The endpoint, or the thing you asked for (ad, post, subreddit), doesn't exist. Charged when the platform was checked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error. Not charged, except the endpoint's own 4xx answers such as not_found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/google/adLibrary/advertisers/search": { "get": { "operationId": "google_search_advertisers", "tags": [ "Google" ], "summary": "Search Google advertisers", "description": "Find an advertiser's Google Ads id by brand name, with how many ads they run, plus matching websites.\n\nUse it to turn a brand name into the `advertiser_id` that company ads (google_company_ads) needs, or to find the website to pass as `domain`. Big brands have one advertiser per country or agency; pick by `region` and `number_of_ads_estimate`.\n\nThe same suggestions as the search box on adstransparency.google.com: up to 10 advertisers and 10 websites, no pagination. `region` (default US) counts only ads shown there, so the list changes by region; pass ALL for every region.\n\nCost: 1 credit.", "externalDocs": { "url": "https://lurkapi.com/docs/google/search-advertisers" }, "x-credits": 1, "parameters": [ { "name": "query", "in": "query", "required": true, "description": "Brand or advertiser name, e.g. `nike`.", "schema": { "type": "string", "minLength": 1, "description": "Brand or advertiser name, e.g. `nike`." }, "example": "nike" }, { "name": "region", "in": "query", "required": false, "description": "Count only ads shown in this country: a 2-letter code (US, GB, DE…), or ALL for anywhere.", "schema": { "description": "Count only ads shown in this country: a 2-letter code (US, GB, DE…), or ALL for anywhere.", "default": "US", "type": "string" } } ], "responses": { "200": { "description": "Find an advertiser's Google Ads id by brand name, with how many ads they run, plus matching websites.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "const": true, "description": "Always true here; errors have `success: false`." }, "credits_remaining": { "type": "number", "description": "Your balance after this call. On anonymous playground calls: free tries left today." }, "credits_charged": { "type": "number", "description": "Credits this call cost; 0 on free endpoints. On anonymous playground calls: tries used (1)." }, "advertisers": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "The advertiser's verified name, e.g. `Nike, Inc.`." }, "advertiser_id": { "type": "string", "description": "The advertiser's id (`AR…`). Pass it as `advertiser_id` to company ads." }, "region": { "description": "Country the advertiser is based in, as a 2-letter code.", "type": [ "string", "null" ] }, "number_of_ads_estimate": { "description": "How many ads they have in `region`: the lower end of Google's range (exact for small advertisers).", "type": [ "number", "null" ] }, "number_of_ads_range": { "anyOf": [ { "type": "object", "properties": { "min": { "type": "number", "description": "Lower bound of the ad count." }, "max": { "type": "number", "description": "Upper bound of the ad count." } }, "required": [ "min", "max" ], "additionalProperties": false }, { "type": "null" } ], "description": "The ad count as the range Google shows, e.g. 9000–10000; null when it gives none." }, "is_verified": { "type": "boolean", "description": "false when Google marks the advertiser as not yet verified." } }, "required": [ "name", "advertiser_id", "region", "number_of_ads_estimate", "number_of_ads_range", "is_verified" ], "additionalProperties": false }, "description": "Matching advertisers, best match first." }, "websites": { "type": "array", "items": { "type": "object", "properties": { "domain": { "type": "string", "description": "A website with ads, e.g. `nike.com`. Pass it as `domain` to company ads." } }, "required": [ "domain" ], "additionalProperties": false }, "description": "Websites matching the query." } }, "required": [ "success", "credits_remaining", "credits_charged", "advertisers", "websites" ], "additionalProperties": false } } } }, "default": { "description": "Error. Not charged, except the endpoint's own 4xx answers such as not_found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/google/company/ads": { "get": { "operationId": "google_company_ads", "tags": [ "Google" ], "summary": "Google ads by company", "description": "Every ad an advertiser or website runs on Google Search, YouTube, Maps, Play and Shopping, from the Ads Transparency Center.\n\nUse it to study a competitor's Google and YouTube ads: formats, run dates and how long each ad has run. Pass `domain` (e.g. nike.com, every advertiser promoting it) or `advertiser_id` from search advertisers (google_search_advertisers).\n\nFilter by region, platform, format and date range. `topic=political` lists election ads with their spend and impressions, and needs a `region`. For an ad's text, landing page and per-country stats, pass its ids to ad details (google_ad).\n\n**Pagination.** Up to 100 ads per page. Pass `cursor` back with the same filters for the next page; it's null on the last page. Date ranges that start more than about a year back come back empty.\n\nCost: 1 credit.", "externalDocs": { "url": "https://lurkapi.com/docs/google/company-ads" }, "x-credits": 1, "parameters": [ { "name": "domain", "in": "query", "required": false, "description": "The advertiser's website, e.g. `nike.com`. Required unless you pass `advertiser_id`.", "schema": { "description": "The advertiser's website, e.g. `nike.com`. Required unless you pass `advertiser_id`.", "type": "string" }, "example": "nike.com" }, { "name": "advertiser_id", "in": "query", "required": false, "description": "The advertiser's id, e.g. `AR16735076323512287233` (Nike, Inc.). Required unless you pass `domain`.", "schema": { "description": "The advertiser's id, e.g. `AR16735076323512287233` (Nike, Inc.). Required unless you pass `domain`.", "type": "string", "pattern": "^AR\\d{1,30}$" } }, { "name": "topic", "in": "query", "required": false, "description": "`political` lists only election ads (with spend and impressions); it needs a `region`.", "schema": { "description": "`political` lists only election ads (with spend and impressions); it needs a `region`.", "default": "all", "type": "string", "enum": [ "all", "political" ] } }, { "name": "region", "in": "query", "required": false, "description": "Only ads shown in this country: a 2-letter code (US, GB, DE…), or ALL for anywhere.", "schema": { "description": "Only ads shown in this country: a 2-letter code (US, GB, DE…), or ALL for anywhere.", "default": "ALL", "type": "string" }, "example": "US" }, { "name": "start_date", "in": "query", "required": false, "description": "Only ads shown on or after this date (YYYY-MM-DD).", "schema": { "description": "Only ads shown on or after this date (YYYY-MM-DD).", "type": "string" } }, { "name": "end_date", "in": "query", "required": false, "description": "Only ads shown on or before this date (YYYY-MM-DD).", "schema": { "description": "Only ads shown on or before this date (YYYY-MM-DD).", "type": "string" } }, { "name": "platform", "in": "query", "required": false, "description": "Only ads shown on this Google product.", "schema": { "description": "Only ads shown on this Google product.", "default": "all", "type": "string", "enum": [ "all", "google_maps", "google_play", "google_search", "google_shopping", "youtube" ] } }, { "name": "format", "in": "query", "required": false, "description": "Only ads in this format.", "schema": { "description": "Only ads in this format.", "default": "all", "type": "string", "enum": [ "all", "text", "image", "video" ] } }, { "name": "cursor", "in": "query", "required": false, "description": "The `cursor` from the previous response, for the next page. Keep every other param the same.", "schema": { "description": "The `cursor` from the previous response, for the next page. Keep every other param the same.", "type": "string", "minLength": 1 } } ], "responses": { "200": { "description": "Every ad an advertiser or website runs on Google Search, YouTube, Maps, Play and Shopping, from the Ads Transparency Center.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "const": true, "description": "Always true here; errors have `success: false`." }, "credits_remaining": { "type": "number", "description": "Your balance after this call. On anonymous playground calls: free tries left today." }, "credits_charged": { "type": "number", "description": "Credits this call cost; 0 on free endpoints. On anonymous playground calls: tries used (1)." }, "ads": { "type": "array", "items": { "type": "object", "properties": { "advertiserId": { "type": "string", "description": "The advertiser's id (`AR…`). Pass it as `advertiser_id` to company ads." }, "creativeId": { "type": "string", "description": "The ad's id (`CR…`). Pass it with `advertiser_id` as `creative_id` to ad details." }, "format": { "anyOf": [ { "type": "string", "enum": [ "text", "image", "video" ] }, { "type": "null" } ], "description": "text, image or video. Text ads are often archived as a picture of the ad." }, "adUrl": { "type": "string", "description": "The ad's page on the Ads Transparency Center." }, "advertiserName": { "description": "The advertiser's verified name, e.g. `Nike, Inc.`.", "type": [ "string", "null" ] }, "domain": { "description": "The website this ad matched, on domain searches; null on advertiser searches.", "type": [ "string", "null" ] }, "imageUrl": { "description": "Picture of the ad, for image ads and text ads Google archived as an image. null when the ad only has a live preview (`previewUrl`).", "type": [ "string", "null" ] }, "previewUrl": { "description": "Google's live preview of the ad: a script the Transparency Center renders. null when there's an `imageUrl`.", "type": [ "string", "null" ] }, "firstShown": { "description": "When the ad was first shown, ISO 8601 (UTC).", "type": [ "string", "null" ] }, "lastShown": { "description": "When the ad was last shown, ISO 8601 (UTC). Today's date for ads still running.", "type": [ "string", "null" ] }, "daysShown": { "description": "How many days the ad has been shown. A long run usually means the ad works.", "type": [ "number", "null" ] }, "overallImpressions": { "anyOf": [ { "type": "object", "properties": { "min": { "type": "number", "description": "Lower bound of impressions." }, "max": { "type": "number", "description": "Upper bound of impressions." } }, "required": [ "min", "max" ], "additionalProperties": false }, { "type": "null" } ], "description": "Impressions as the range Google reports. Political ads only; null otherwise." }, "spend": { "anyOf": [ { "type": "object", "properties": { "currency": { "type": "string", "description": "Currency code, e.g. USD." }, "lower": { "type": "number", "description": "Lower bound of the spend, in `currency`." }, "upper": { "type": "number", "description": "Upper bound of the spend, in `currency`." } }, "required": [ "currency", "lower", "upper" ], "additionalProperties": false }, { "type": "null" } ], "description": "Spend as the range Google reports. Political ads only; null otherwise." } }, "required": [ "advertiserId", "creativeId", "format", "adUrl", "advertiserName", "domain", "imageUrl", "previewUrl", "firstShown", "lastShown", "daysShown", "overallImpressions", "spend" ], "additionalProperties": false }, "description": "The ads in Google's order: roughly most recently shown first." }, "cursor": { "description": "Pass as `cursor` for the next page. null on the last page.", "type": [ "string", "null" ] }, "number_of_ads_estimate": { "description": "How many ads match, as Google estimates it: the lower end of its range, or the exact count when it gives one.", "type": [ "number", "null" ] }, "number_of_ads_range": { "anyOf": [ { "type": "object", "properties": { "min": { "type": "number", "description": "Lower bound of the ad count." }, "max": { "type": "number", "description": "Upper bound of the ad count." } }, "required": [ "min", "max" ], "additionalProperties": false }, { "type": "null" } ], "description": "The ad count as the range Google shows (e.g. 7000–8000); null when it gives none." } }, "required": [ "success", "credits_remaining", "credits_charged", "ads", "cursor", "number_of_ads_estimate", "number_of_ads_range" ], "additionalProperties": false } } } }, "default": { "description": "Error. Not charged, except the endpoint's own 4xx answers such as not_found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/google/ad": { "get": { "operationId": "google_ad", "tags": [ "Google" ], "summary": "Google ad details", "description": "One ad from Google's Ads Transparency Center: every version of the creative, where it ran and, for political ads, spend and targeting.\n\nUse it after company ads (google_company_ads) for one ad's versions, regions and landing page. Pass the ad's Transparency Center link as `url`, or `advertiser_id` + `creative_id`.\n\nEach version has an `imageUrl` when Google archived it as a picture, else a `previewUrl`. For text and video ads we also read one live preview for the headline, description, landing page and YouTube video; image-only text stays null (we don't OCR). Impressions, spend and targeting are only published for political ads.\n\nReturns 404 `not_found` if the ad doesn't exist.\n\nCost: 1 credit.", "externalDocs": { "url": "https://lurkapi.com/docs/google/ad" }, "x-credits": 1, "parameters": [ { "name": "url", "in": "query", "required": false, "description": "The ad's Transparency Center link, e.g. `https://adstransparency.google.com/advertiser/AR16735076323512287233/creative/CR11071274990039990273`. Required unless you pass both ids.", "schema": { "description": "The ad's Transparency Center link, e.g. `https://adstransparency.google.com/advertiser/AR16735076323512287233/creative/CR11071274990039990273`. Required unless you pass both ids.", "type": "string" }, "example": "https://adstransparency.google.com/advertiser/AR16735076323512287233/creative/CR11071274990039990273?region=US" }, { "name": "advertiser_id", "in": "query", "required": false, "description": "The advertiser's id (`AR…`), with `creative_id`, instead of `url`.", "schema": { "description": "The advertiser's id (`AR…`), with `creative_id`, instead of `url`.", "type": "string", "pattern": "^AR\\d{1,30}$" } }, { "name": "creative_id", "in": "query", "required": false, "description": "The ad's id (`CR…`), with `advertiser_id`, instead of `url`.", "schema": { "description": "The ad's id (`CR…`), with `advertiser_id`, instead of `url`.", "type": "string", "pattern": "^CR\\d{1,30}$" } } ], "responses": { "200": { "description": "One ad from Google's Ads Transparency Center: every version of the creative, where it ran and, for political ads, spend and targeting.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "const": true, "description": "Always true here; errors have `success: false`." }, "credits_remaining": { "type": "number", "description": "Your balance after this call. On anonymous playground calls: free tries left today." }, "credits_charged": { "type": "number", "description": "Credits this call cost; 0 on free endpoints. On anonymous playground calls: tries used (1)." }, "advertiserId": { "type": "string", "description": "The advertiser's id (`AR…`). Pass it as `advertiser_id` to company ads." }, "creativeId": { "type": "string", "description": "The ad's id (`CR…`)." }, "advertiserName": { "description": "Who paid for the ad (Google's \"paid for by\" name), e.g. `Nike, Inc.`; it can differ from the advertiser account, e.g. for agencies. Often null for political ads.", "type": [ "string", "null" ] }, "format": { "anyOf": [ { "type": "string", "enum": [ "text", "image", "video" ] }, { "type": "null" } ], "description": "text, image or video. Text ads are often archived as a picture of the ad." }, "adUrl": { "type": "string", "description": "The ad's page on the Ads Transparency Center." }, "firstShown": { "description": "When the ad was first shown, ISO 8601 (UTC). Google often leaves it out here; company ads always has it.", "type": [ "string", "null" ] }, "lastShown": { "description": "When the ad was last shown, ISO 8601 (UTC). Today's date for ads still running.", "type": [ "string", "null" ] }, "daysShown": { "description": "How many days the ad has been shown. A long run usually means the ad works. null when Google leaves it out.", "type": [ "number", "null" ] }, "overallImpressions": { "anyOf": [ { "type": "object", "properties": { "min": { "type": "number", "description": "Lower bound of impressions." }, "max": { "type": "number", "description": "Upper bound of impressions." } }, "required": [ "min", "max" ], "additionalProperties": false }, { "type": "null" } ], "description": "Impressions as the range Google reports. Political ads only; null otherwise." }, "spend": { "anyOf": [ { "type": "object", "properties": { "currency": { "type": "string", "description": "Currency code, e.g. USD." }, "lower": { "type": "number", "description": "Lower bound of the spend, in `currency`." }, "upper": { "type": "number", "description": "Upper bound of the spend, in `currency`." } }, "required": [ "currency", "lower", "upper" ], "additionalProperties": false }, { "type": "null" } ], "description": "Spend as the range Google reports. Political ads only; null otherwise." }, "targeting": { "anyOf": [ { "type": "object", "properties": { "age": { "type": "object", "properties": { "included": { "type": "array", "items": { "type": "string" }, "description": "Age groups (0-17, 18-24, 25-34, 35-44, 45-54, 55-64, 65+, unknown) the ad targeted." }, "excluded": { "type": "array", "items": { "type": "string" }, "description": "Age groups (0-17, 18-24, 25-34, 35-44, 45-54, 55-64, 65+, unknown) the ad excluded." } }, "required": [ "included", "excluded" ], "additionalProperties": false, "description": "Age groups (0-17, 18-24, 25-34, 35-44, 45-54, 55-64, 65+, unknown) targeting." }, "gender": { "type": "object", "properties": { "included": { "type": "array", "items": { "type": "string" }, "description": "Genders (male, female, unknown) the ad targeted." }, "excluded": { "type": "array", "items": { "type": "string" }, "description": "Genders (male, female, unknown) the ad excluded." } }, "required": [ "included", "excluded" ], "additionalProperties": false, "description": "Genders (male, female, unknown) targeting." }, "location": { "type": "object", "properties": { "included": { "type": "array", "items": { "type": "object", "properties": { "criterionId": { "type": "string", "description": "Google's location id, e.g. 2840 (United States) or 1015229 (a city)." }, "name": { "description": "The country's name for country-level ids; null for cities and regions, which we don't resolve.", "type": [ "string", "null" ] }, "fullName": { "description": "Same as `name` for countries; null for cities and regions.", "type": [ "string", "null" ] }, "countryCodes": { "type": "array", "items": { "type": "string" }, "description": "The country code for country-level ids, e.g. [\"US\"]; empty otherwise." } }, "required": [ "criterionId", "name", "fullName", "countryCodes" ], "additionalProperties": false }, "description": "Locations the ad targeted." }, "excluded": { "type": "array", "items": { "type": "object", "properties": { "criterionId": { "type": "string", "description": "Google's location id, e.g. 2840 (United States) or 1015229 (a city)." }, "name": { "description": "The country's name for country-level ids; null for cities and regions, which we don't resolve.", "type": [ "string", "null" ] }, "fullName": { "description": "Same as `name` for countries; null for cities and regions.", "type": [ "string", "null" ] }, "countryCodes": { "type": "array", "items": { "type": "string" }, "description": "The country code for country-level ids, e.g. [\"US\"]; empty otherwise." } }, "required": [ "criterionId", "name", "fullName", "countryCodes" ], "additionalProperties": false }, "description": "Locations the ad excluded." } }, "required": [ "included", "excluded" ], "additionalProperties": false, "description": "Location targeting." } }, "required": [ "age", "gender", "location" ], "additionalProperties": false }, { "type": "null" } ], "description": "Who the ad targeted. Political ads only; null otherwise. Empty lists can still mean targeting was used: Google doesn't always list the groups." }, "creativeRegions": { "type": "array", "items": { "type": "object", "properties": { "regionCode": { "type": "string", "description": "2-letter country code, e.g. US." }, "regionName": { "type": "string", "description": "Country name in English." } }, "required": [ "regionCode", "regionName" ], "additionalProperties": false }, "description": "Countries where the ad was shown." }, "regionStats": { "type": "array", "items": { "type": "object", "properties": { "regionCode": { "type": "string", "description": "2-letter country code, e.g. US." }, "regionName": { "type": "string", "description": "Country name in English." }, "firstShown": { "description": "First day shown in this country, YYYY-MM-DD; often null outside political ads.", "type": [ "string", "null" ] }, "lastShown": { "description": "Last day shown in this country, YYYY-MM-DD.", "type": [ "string", "null" ] }, "impressions": { "anyOf": [ { "type": "object", "properties": { "min": { "type": "number", "description": "Lower bound of impressions." }, "max": { "type": "number", "description": "Upper bound of impressions." } }, "required": [ "min", "max" ], "additionalProperties": false }, { "type": "null" } ], "description": "Impressions in this country. Political ads only; null otherwise." }, "platformImpressions": { "type": "array", "items": { "type": "object", "properties": { "platform": { "anyOf": [ { "type": "string", "enum": [ "google_maps", "google_play", "google_search", "google_shopping", "youtube" ] }, { "type": "null" } ], "description": "The Google product." }, "min": { "description": "Lower bound of impressions there.", "type": [ "number", "null" ] }, "max": { "description": "Upper bound of impressions there.", "type": [ "number", "null" ] } }, "required": [ "platform", "min", "max" ], "additionalProperties": false }, "description": "Impressions per Google product in this country, when Google reports them; usually empty." } }, "required": [ "regionCode", "regionName", "firstShown", "lastShown", "impressions", "platformImpressions" ], "additionalProperties": false }, "description": "Per-country delivery: dates and, for political ads, impressions." }, "variations": { "type": "array", "items": { "type": "object", "properties": { "destinationUrl": { "description": "Landing page, from the version's live preview. For search ads it can be just the display URL (e.g. `nike.com`); null when we didn't read one.", "type": [ "string", "null" ] }, "headline": { "description": "Headline, from the live preview; null for image-only versions and ones we didn't read.", "type": [ "string", "null" ] }, "description": { "description": "Description text, from the live preview; null for image-only versions and ones we didn't read.", "type": [ "string", "null" ] }, "allText": { "description": "All text on the ad. Always null for now: reading text off archived images needs OCR, which we don't run.", "type": [ "string", "null" ] }, "imageUrl": { "description": "Picture of this version; null when it only has a live preview.", "type": [ "string", "null" ] }, "previewUrl": { "description": "Google's live preview of this version (a script); null when there's an `imageUrl`.", "type": [ "string", "null" ] }, "videoId": { "description": "The YouTube video id of a video ad, from the live preview (youtube.com/watch?v=); null otherwise.", "type": [ "string", "null" ] } }, "required": [ "destinationUrl", "headline", "description", "allText", "imageUrl", "previewUrl", "videoId" ], "additionalProperties": false }, "description": "Every version of the creative Google shows. We read the live preview of the first previewed version of text and video ads only." } }, "required": [ "success", "credits_remaining", "credits_charged", "advertiserId", "creativeId", "advertiserName", "format", "adUrl", "firstShown", "lastShown", "daysShown", "overallImpressions", "spend", "targeting", "creativeRegions", "regionStats", "variations" ], "additionalProperties": false } } } }, "404": { "description": "not_found: The endpoint, or the thing you asked for (ad, post, subreddit), doesn't exist. Charged when the platform was checked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error. Not charged, except the endpoint's own 4xx answers such as not_found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/bluesky/profile": { "get": { "operationId": "bluesky_profile", "tags": [ "Bluesky" ], "summary": "Profile", "description": "An account's bio, avatar, banner and exact follower, following and post counts.\n\nUse it to size up an account: exact followers, following and posts, plus bio, images and join date. `did` is the permanent id; the handle can change.\n\nAccounts that opted out of logged-out visibility (`!no-unauthenticated`) return 403 `not_public`.\n\nUnknown, deactivated and suspended accounts return 404 `not_found`.\n\nCost: 1 credit.", "externalDocs": { "url": "https://lurkapi.com/docs/bluesky/profile" }, "x-credits": 1, "parameters": [ { "name": "handle", "in": "query", "required": true, "description": "Handle (e.g. `bsky.app`, with or without @), a DID (`did:plc:…`) or the profile URL. A bare name like `jay` means `jay.bsky.social`.", "schema": { "description": "Handle (e.g. `bsky.app`, with or without @), a DID (`did:plc:…`) or the profile URL. A bare name like `jay` means `jay.bsky.social`.", "type": "string" }, "example": "bsky.app" } ], "responses": { "200": { "description": "An account's bio, avatar, banner and exact follower, following and post counts.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "const": true, "description": "Always true here; errors have `success: false`." }, "credits_remaining": { "type": "number", "description": "Your balance after this call. On anonymous playground calls: free tries left today." }, "credits_charged": { "type": "number", "description": "Credits this call cost; 0 on free endpoints. On anonymous playground calls: tries used (1)." }, "did": { "type": "string", "description": "The account's permanent id, e.g. `did:plc:z72i7hdynmk6r22z27h6tvur`." }, "handle": { "type": "string", "description": "Handle, e.g. `bsky.app`." }, "displayName": { "description": "Display name; null if not set.", "type": [ "string", "null" ] }, "description": { "description": "Bio text; null if not set.", "type": [ "string", "null" ] }, "url": { "type": "string", "description": "The profile on bsky.app." }, "avatar": { "description": "Avatar image URL; null if none.", "type": [ "string", "null" ] }, "banner": { "description": "Banner image URL; null if none.", "type": [ "string", "null" ] }, "followersCount": { "type": "number", "description": "Followers, exact." }, "followsCount": { "type": "number", "description": "Accounts they follow." }, "postsCount": { "type": "number", "description": "Posts, replies included." }, "createdAt": { "description": "When the account was created, ISO 8601.", "type": [ "string", "null" ] }, "pinnedPost": { "description": "`at://` URI of the pinned post; null if none.", "type": [ "string", "null" ] }, "verified": { "type": "boolean", "description": "Has Bluesky's blue verification check." }, "hiddenFromLoggedOut": { "type": "boolean", "description": "Always false for returned profiles. Accounts hidden from logged-out visitors return 403 `not_public`." } }, "required": [ "success", "credits_remaining", "credits_charged", "did", "handle", "displayName", "description", "url", "avatar", "banner", "followersCount", "followsCount", "postsCount", "createdAt", "pinnedPost", "verified", "hiddenFromLoggedOut" ], "additionalProperties": false } } } }, "403": { "description": "not_public: The platform confirmed this account or content isn't available to logged-out visitors. Use a publicly visible target.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "not_found: The endpoint, or the thing you asked for (ad, post, subreddit), doesn't exist. Charged when the platform was checked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error. Not charged, except the endpoint's own 4xx answers such as not_found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/bluesky/user/posts": { "get": { "operationId": "bluesky_user_posts", "tags": [ "Bluesky" ], "summary": "User posts", "description": "An account's latest posts and reposts, newest first, with text, media and engagement counts.\n\nUse it to track what an account posts and how it lands: likes, reposts, replies and quotes on every post. The default `filter` matches the Posts tab on bsky.app: posts, reposts and the account's own threads, without replies to others, with the pinned post first (`pinned: true`). Reposts have `repost: true` and the original poster as `author`.\n\nPass `handle` or `user_id`.\n\nAccounts that opted out of logged-out visibility return 403 `not_public`, including empty feeds. Posts and reposts by hidden authors are omitted; hidden quotes are null. Visibility of the requested account is checked with a 30-second cached profile lookup.\n\n**Pagination.** Up to 50 posts per page. Pass the response's `cursor` back as `cursor` (with the same account and filter); it's null at the end. Unknown, deactivated and suspended accounts return 404 `not_found`.\n\nCost: 1 credit.", "externalDocs": { "url": "https://lurkapi.com/docs/bluesky/user-posts" }, "x-credits": 1, "parameters": [ { "name": "handle", "in": "query", "required": false, "description": "Handle (e.g. `bsky.app`), a DID or the profile URL. Required unless you pass `user_id`.", "schema": { "description": "Handle (e.g. `bsky.app`), a DID or the profile URL. Required unless you pass `user_id`.", "type": "string" }, "example": "bsky.app" }, { "name": "user_id", "in": "query", "required": false, "description": "The account's DID, e.g. `did:plc:z72i7hdynmk6r22z27h6tvur`. Required unless you pass `handle`.", "schema": { "description": "The account's DID, e.g. `did:plc:z72i7hdynmk6r22z27h6tvur`. Required unless you pass `handle`.", "type": "string" } }, { "name": "filter", "in": "query", "required": false, "description": "`posts_and_author_threads` (the Posts tab), `posts_with_replies`, `posts_no_replies`, `posts_with_media` or `posts_with_video`.", "schema": { "description": "`posts_and_author_threads` (the Posts tab), `posts_with_replies`, `posts_no_replies`, `posts_with_media` or `posts_with_video`.", "default": "posts_and_author_threads", "type": "string", "enum": [ "posts_and_author_threads", "posts_with_replies", "posts_no_replies", "posts_with_media", "posts_with_video" ] } }, { "name": "cursor", "in": "query", "required": false, "description": "The `cursor` from the previous response, to get the next page.", "schema": { "description": "The `cursor` from the previous response, to get the next page.", "type": "string" } } ], "responses": { "200": { "description": "An account's latest posts and reposts, newest first, with text, media and engagement counts.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "const": true, "description": "Always true here; errors have `success: false`." }, "credits_remaining": { "type": "number", "description": "Your balance after this call. On anonymous playground calls: free tries left today." }, "credits_charged": { "type": "number", "description": "Credits this call cost; 0 on free endpoints. On anonymous playground calls: tries used (1)." }, "posts": { "type": "array", "items": { "type": "object", "properties": { "uri": { "type": "string", "description": "The post's `at://` URI, its permanent id." }, "cid": { "type": "string", "description": "Content hash of this version of the post." }, "url": { "type": "string", "description": "The post on bsky.app." }, "text": { "type": "string", "description": "Post text. Empty for media-only posts." }, "createdAt": { "type": "string", "description": "When it was posted, ISO 8601." }, "author": { "type": "object", "properties": { "did": { "type": "string", "description": "The account's permanent id, e.g. `did:plc:z72i7hdynmk6r22z27h6tvur`." }, "handle": { "type": "string", "description": "Handle, e.g. `bsky.app`. It can change; the DID doesn't." }, "displayName": { "description": "Display name; null if not set.", "type": [ "string", "null" ] }, "avatar": { "description": "Avatar image URL; null if none.", "type": [ "string", "null" ] } }, "required": [ "did", "handle", "displayName", "avatar" ], "additionalProperties": false, "description": "Who posted it." }, "replyCount": { "type": "number", "description": "Replies." }, "repostCount": { "type": "number", "description": "Reposts." }, "likeCount": { "type": "number", "description": "Likes." }, "quoteCount": { "type": "number", "description": "Quote posts." }, "bookmarkCount": { "type": "number", "description": "Times saved to bookmarks." }, "langs": { "type": "array", "items": { "type": "string" }, "description": "Languages the author tagged, e.g. `en`." }, "images": { "type": "array", "items": { "type": "object", "properties": { "thumbnail": { "type": "string", "description": "Small image URL." }, "fullsize": { "type": "string", "description": "Full-size image URL." }, "alt": { "type": "string", "description": "Alt text; empty if none." } }, "required": [ "thumbnail", "fullsize", "alt" ], "additionalProperties": false }, "description": "Attached images, in order. Empty if none." }, "video": { "anyOf": [ { "type": "object", "properties": { "playlist": { "type": "string", "description": "HLS playlist (.m3u8) URL." }, "thumbnail": { "description": "Poster image URL; null if none.", "type": [ "string", "null" ] }, "alt": { "description": "Alt text; null if none.", "type": [ "string", "null" ] } }, "required": [ "playlist", "thumbnail", "alt" ], "additionalProperties": false }, { "type": "null" } ], "description": "Attached video; null if none." }, "external": { "anyOf": [ { "type": "object", "properties": { "uri": { "type": "string", "description": "The linked page." }, "title": { "type": "string", "description": "Link card title." }, "description": { "type": "string", "description": "Link card description." }, "thumbnail": { "description": "Link card image URL; null if none.", "type": [ "string", "null" ] } }, "required": [ "uri", "title", "description", "thumbnail" ], "additionalProperties": false }, { "type": "null" } ], "description": "Link card; null if none." }, "quote": { "anyOf": [ { "type": "object", "properties": { "uri": { "type": "string", "description": "The quoted post's `at://` URI. Pass it as `url` to the post endpoint." }, "url": { "type": "string", "description": "The quoted post on bsky.app." }, "text": { "description": "Its text; null when it was deleted or its author blocks viewers.", "type": [ "string", "null" ] }, "createdAt": { "description": "When it was posted, ISO 8601; null when unavailable.", "type": [ "string", "null" ] }, "author": { "anyOf": [ { "type": "object", "properties": { "did": { "type": "string", "description": "The account's permanent id, e.g. `did:plc:z72i7hdynmk6r22z27h6tvur`." }, "handle": { "type": "string", "description": "Handle, e.g. `bsky.app`. It can change; the DID doesn't." }, "displayName": { "description": "Display name; null if not set.", "type": [ "string", "null" ] }, "avatar": { "description": "Avatar image URL; null if none.", "type": [ "string", "null" ] } }, "required": [ "did", "handle", "displayName", "avatar" ], "additionalProperties": false, "description": "Who posted it." }, { "type": "null" } ], "description": "Who posted it; null when unavailable." } }, "required": [ "uri", "url", "text", "createdAt", "author" ], "additionalProperties": false }, { "type": "null" } ], "description": "The post this one quotes; null if none or hidden from logged-out visitors. Embedded lists, feeds and starter packs aren't returned." }, "links": { "type": "array", "items": { "type": "string" }, "description": "Links in the text." }, "mentions": { "type": "array", "items": { "type": "string" }, "description": "Handles mentioned in the text, without @." }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Hashtags in the text, without #." }, "replyTo": { "description": "`at://` URI of the post this replies to; null for top-level posts.", "type": [ "string", "null" ] }, "repost": { "type": "boolean", "description": "A repost by this account; `author` is the original poster." }, "pinned": { "type": "boolean", "description": "The account's pinned post, shown first on the first page." } }, "required": [ "uri", "cid", "url", "text", "createdAt", "author", "replyCount", "repostCount", "likeCount", "quoteCount", "bookmarkCount", "langs", "images", "video", "external", "quote", "links", "mentions", "tags", "replyTo", "repost", "pinned" ], "additionalProperties": false }, "description": "One page of posts, newest first (the pinned post leads the first page)." }, "cursor": { "description": "Pass as `cursor` for the next page. null on the last page.", "type": [ "string", "null" ] } }, "required": [ "success", "credits_remaining", "credits_charged", "posts", "cursor" ], "additionalProperties": false } } } }, "403": { "description": "not_public: The platform confirmed this account or content isn't available to logged-out visitors. Use a publicly visible target.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "not_found: The endpoint, or the thing you asked for (ad, post, subreddit), doesn't exist. Charged when the platform was checked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error. Not charged, except the endpoint's own 4xx answers such as not_found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/bluesky/post": { "get": { "operationId": "bluesky_post", "tags": [ "Bluesky" ], "summary": "Post", "description": "A post with its replies (three levels deep) and the posts it replies to.\n\nUse it to read a conversation: the post, its replies nested under `replies`, and `parents` from the thread's first post down to the one this post answers. Replies go three levels deep; pass a reply's `uri` as `url` to read further down.\n\nDeleted posts and posts from accounts that block viewers are left out of `replies`; in `parents`, the chain stops below one.\n\nA requested post hidden from logged-out visitors returns 403 `not_public`. Hidden replies and their branches are omitted, hidden quotes are null, and the parent chain stops below a hidden author.\n\nUnknown and deleted posts return 404 `not_found`.\n\nCost: 1 credit.", "externalDocs": { "url": "https://lurkapi.com/docs/bluesky/post" }, "x-credits": 1, "parameters": [ { "name": "url", "in": "query", "required": true, "description": "The post's URL, e.g. `https://bsky.app/profile/bsky.app/post/3l6oveex3ii2l`, or its `at://` URI.", "schema": { "type": "string", "description": "The post's URL, e.g. `https://bsky.app/profile/bsky.app/post/3l6oveex3ii2l`, or its `at://` URI." }, "example": "https://bsky.app/profile/bsky.app/post/3mtykea5kds2d" } ], "responses": { "200": { "description": "A post with its replies (three levels deep) and the posts it replies to.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "const": true, "description": "Always true here; errors have `success: false`." }, "credits_remaining": { "type": "number", "description": "Your balance after this call. On anonymous playground calls: free tries left today." }, "credits_charged": { "type": "number", "description": "Credits this call cost; 0 on free endpoints. On anonymous playground calls: tries used (1)." }, "post": { "type": "object", "properties": { "uri": { "type": "string", "description": "The post's `at://` URI, its permanent id." }, "cid": { "type": "string", "description": "Content hash of this version of the post." }, "url": { "type": "string", "description": "The post on bsky.app." }, "text": { "type": "string", "description": "Post text. Empty for media-only posts." }, "createdAt": { "type": "string", "description": "When it was posted, ISO 8601." }, "author": { "type": "object", "properties": { "did": { "type": "string", "description": "The account's permanent id, e.g. `did:plc:z72i7hdynmk6r22z27h6tvur`." }, "handle": { "type": "string", "description": "Handle, e.g. `bsky.app`. It can change; the DID doesn't." }, "displayName": { "description": "Display name; null if not set.", "type": [ "string", "null" ] }, "avatar": { "description": "Avatar image URL; null if none.", "type": [ "string", "null" ] } }, "required": [ "did", "handle", "displayName", "avatar" ], "additionalProperties": false, "description": "Who posted it." }, "replyCount": { "type": "number", "description": "Replies." }, "repostCount": { "type": "number", "description": "Reposts." }, "likeCount": { "type": "number", "description": "Likes." }, "quoteCount": { "type": "number", "description": "Quote posts." }, "bookmarkCount": { "type": "number", "description": "Times saved to bookmarks." }, "langs": { "type": "array", "items": { "type": "string" }, "description": "Languages the author tagged, e.g. `en`." }, "images": { "type": "array", "items": { "type": "object", "properties": { "thumbnail": { "type": "string", "description": "Small image URL." }, "fullsize": { "type": "string", "description": "Full-size image URL." }, "alt": { "type": "string", "description": "Alt text; empty if none." } }, "required": [ "thumbnail", "fullsize", "alt" ], "additionalProperties": false }, "description": "Attached images, in order. Empty if none." }, "video": { "anyOf": [ { "type": "object", "properties": { "playlist": { "type": "string", "description": "HLS playlist (.m3u8) URL." }, "thumbnail": { "description": "Poster image URL; null if none.", "type": [ "string", "null" ] }, "alt": { "description": "Alt text; null if none.", "type": [ "string", "null" ] } }, "required": [ "playlist", "thumbnail", "alt" ], "additionalProperties": false }, { "type": "null" } ], "description": "Attached video; null if none." }, "external": { "anyOf": [ { "type": "object", "properties": { "uri": { "type": "string", "description": "The linked page." }, "title": { "type": "string", "description": "Link card title." }, "description": { "type": "string", "description": "Link card description." }, "thumbnail": { "description": "Link card image URL; null if none.", "type": [ "string", "null" ] } }, "required": [ "uri", "title", "description", "thumbnail" ], "additionalProperties": false }, { "type": "null" } ], "description": "Link card; null if none." }, "quote": { "anyOf": [ { "type": "object", "properties": { "uri": { "type": "string", "description": "The quoted post's `at://` URI. Pass it as `url` to the post endpoint." }, "url": { "type": "string", "description": "The quoted post on bsky.app." }, "text": { "description": "Its text; null when it was deleted or its author blocks viewers.", "type": [ "string", "null" ] }, "createdAt": { "description": "When it was posted, ISO 8601; null when unavailable.", "type": [ "string", "null" ] }, "author": { "anyOf": [ { "type": "object", "properties": { "did": { "type": "string", "description": "The account's permanent id, e.g. `did:plc:z72i7hdynmk6r22z27h6tvur`." }, "handle": { "type": "string", "description": "Handle, e.g. `bsky.app`. It can change; the DID doesn't." }, "displayName": { "description": "Display name; null if not set.", "type": [ "string", "null" ] }, "avatar": { "description": "Avatar image URL; null if none.", "type": [ "string", "null" ] } }, "required": [ "did", "handle", "displayName", "avatar" ], "additionalProperties": false, "description": "Who posted it." }, { "type": "null" } ], "description": "Who posted it; null when unavailable." } }, "required": [ "uri", "url", "text", "createdAt", "author" ], "additionalProperties": false }, { "type": "null" } ], "description": "The post this one quotes; null if none or hidden from logged-out visitors. Embedded lists, feeds and starter packs aren't returned." }, "links": { "type": "array", "items": { "type": "string" }, "description": "Links in the text." }, "mentions": { "type": "array", "items": { "type": "string" }, "description": "Handles mentioned in the text, without @." }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Hashtags in the text, without #." }, "replyTo": { "description": "`at://` URI of the post this replies to; null for top-level posts.", "type": [ "string", "null" ] } }, "required": [ "uri", "cid", "url", "text", "createdAt", "author", "replyCount", "repostCount", "likeCount", "quoteCount", "bookmarkCount", "langs", "images", "video", "external", "quote", "links", "mentions", "tags", "replyTo" ], "additionalProperties": false, "description": "The post." }, "replies": { "type": "array", "items": { "$ref": "#/components/schemas/BlueskyReply" }, "description": "Replies in Bluesky's order, each with its own replies." }, "parents": { "type": "array", "items": { "type": "object", "properties": { "uri": { "type": "string", "description": "The post's `at://` URI, its permanent id." }, "cid": { "type": "string", "description": "Content hash of this version of the post." }, "url": { "type": "string", "description": "The post on bsky.app." }, "text": { "type": "string", "description": "Post text. Empty for media-only posts." }, "createdAt": { "type": "string", "description": "When it was posted, ISO 8601." }, "author": { "type": "object", "properties": { "did": { "type": "string", "description": "The account's permanent id, e.g. `did:plc:z72i7hdynmk6r22z27h6tvur`." }, "handle": { "type": "string", "description": "Handle, e.g. `bsky.app`. It can change; the DID doesn't." }, "displayName": { "description": "Display name; null if not set.", "type": [ "string", "null" ] }, "avatar": { "description": "Avatar image URL; null if none.", "type": [ "string", "null" ] } }, "required": [ "did", "handle", "displayName", "avatar" ], "additionalProperties": false, "description": "Who posted it." }, "replyCount": { "type": "number", "description": "Replies." }, "repostCount": { "type": "number", "description": "Reposts." }, "likeCount": { "type": "number", "description": "Likes." }, "quoteCount": { "type": "number", "description": "Quote posts." }, "bookmarkCount": { "type": "number", "description": "Times saved to bookmarks." }, "langs": { "type": "array", "items": { "type": "string" }, "description": "Languages the author tagged, e.g. `en`." }, "images": { "type": "array", "items": { "type": "object", "properties": { "thumbnail": { "type": "string", "description": "Small image URL." }, "fullsize": { "type": "string", "description": "Full-size image URL." }, "alt": { "type": "string", "description": "Alt text; empty if none." } }, "required": [ "thumbnail", "fullsize", "alt" ], "additionalProperties": false }, "description": "Attached images, in order. Empty if none." }, "video": { "anyOf": [ { "type": "object", "properties": { "playlist": { "type": "string", "description": "HLS playlist (.m3u8) URL." }, "thumbnail": { "description": "Poster image URL; null if none.", "type": [ "string", "null" ] }, "alt": { "description": "Alt text; null if none.", "type": [ "string", "null" ] } }, "required": [ "playlist", "thumbnail", "alt" ], "additionalProperties": false }, { "type": "null" } ], "description": "Attached video; null if none." }, "external": { "anyOf": [ { "type": "object", "properties": { "uri": { "type": "string", "description": "The linked page." }, "title": { "type": "string", "description": "Link card title." }, "description": { "type": "string", "description": "Link card description." }, "thumbnail": { "description": "Link card image URL; null if none.", "type": [ "string", "null" ] } }, "required": [ "uri", "title", "description", "thumbnail" ], "additionalProperties": false }, { "type": "null" } ], "description": "Link card; null if none." }, "quote": { "anyOf": [ { "type": "object", "properties": { "uri": { "type": "string", "description": "The quoted post's `at://` URI. Pass it as `url` to the post endpoint." }, "url": { "type": "string", "description": "The quoted post on bsky.app." }, "text": { "description": "Its text; null when it was deleted or its author blocks viewers.", "type": [ "string", "null" ] }, "createdAt": { "description": "When it was posted, ISO 8601; null when unavailable.", "type": [ "string", "null" ] }, "author": { "anyOf": [ { "type": "object", "properties": { "did": { "type": "string", "description": "The account's permanent id, e.g. `did:plc:z72i7hdynmk6r22z27h6tvur`." }, "handle": { "type": "string", "description": "Handle, e.g. `bsky.app`. It can change; the DID doesn't." }, "displayName": { "description": "Display name; null if not set.", "type": [ "string", "null" ] }, "avatar": { "description": "Avatar image URL; null if none.", "type": [ "string", "null" ] } }, "required": [ "did", "handle", "displayName", "avatar" ], "additionalProperties": false, "description": "Who posted it." }, { "type": "null" } ], "description": "Who posted it; null when unavailable." } }, "required": [ "uri", "url", "text", "createdAt", "author" ], "additionalProperties": false }, { "type": "null" } ], "description": "The post this one quotes; null if none or hidden from logged-out visitors. Embedded lists, feeds and starter packs aren't returned." }, "links": { "type": "array", "items": { "type": "string" }, "description": "Links in the text." }, "mentions": { "type": "array", "items": { "type": "string" }, "description": "Handles mentioned in the text, without @." }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Hashtags in the text, without #." }, "replyTo": { "description": "`at://` URI of the post this replies to; null for top-level posts.", "type": [ "string", "null" ] } }, "required": [ "uri", "cid", "url", "text", "createdAt", "author", "replyCount", "repostCount", "likeCount", "quoteCount", "bookmarkCount", "langs", "images", "video", "external", "quote", "links", "mentions", "tags", "replyTo" ], "additionalProperties": false }, "description": "The posts above this one in the thread, first post first. Empty for top-level posts." } }, "required": [ "success", "credits_remaining", "credits_charged", "post", "replies", "parents" ], "additionalProperties": false } } } }, "403": { "description": "not_public: The platform confirmed this account or content isn't available to logged-out visitors. Use a publicly visible target.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "not_found: The endpoint, or the thing you asked for (ad, post, subreddit), doesn't exist. Charged when the platform was checked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error. Not charged, except the endpoint's own 4xx answers such as not_found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/snapchat/profile": { "get": { "operationId": "snapchat_profile", "tags": [ "Snapchat" ], "summary": "Profile and stories", "description": "A public profile with its live story, highlights and Spotlight videos, with direct media links.\n\nUse it to see what a creator or brand is posting on Snapchat right now, without an account. One call returns the profile, the live public story (`story`), saved highlights and up to ~25 recent Spotlight videos.\n\n**Only Public Profiles post to the web.** For a regular account you get the username, display name and Snapcode, `isPublic: false` and empty lists; that's not an error. Friends-only and private stories are never visible.\n\n**Media links** point straight at Snapchat's CDN and open without cookies. Story snaps are temporary (usually 24 hours; some creators keep theirs up for several days), so save what you need.\n\nUnknown usernames return 404 `not_found`.\n\nCost: 1 credit.", "externalDocs": { "url": "https://lurkapi.com/docs/snapchat/profile" }, "x-credits": 1, "parameters": [ { "name": "handle", "in": "query", "required": true, "description": "Snapchat username, with or without @ (e.g. `nba`), or the profile URL (`snapchat.com/add/nba`, `snapchat.com/@nba`).", "schema": { "description": "Snapchat username, with or without @ (e.g. `nba`), or the profile URL (`snapchat.com/add/nba`, `snapchat.com/@nba`).", "type": "string" }, "example": "nba" } ], "responses": { "200": { "description": "A public profile with its live story, highlights and Spotlight videos, with direct media links.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "const": true, "description": "Always true here; errors have `success: false`." }, "credits_remaining": { "type": "number", "description": "Your balance after this call. On anonymous playground calls: free tries left today." }, "credits_charged": { "type": "number", "description": "Credits this call cost; 0 on free endpoints. On anonymous playground calls: tries used (1)." }, "profile": { "type": "object", "properties": { "username": { "type": "string", "description": "Username, lowercase." }, "displayName": { "description": "Display name.", "type": [ "string", "null" ] }, "bio": { "description": "Bio; null if empty or not public.", "type": [ "string", "null" ] }, "subscriberCount": { "description": "Subscribers, rounded by Snapchat (to 100). null when the creator hides it or the account isn't public.", "type": [ "number", "null" ] }, "website": { "description": "Website link from the profile, with `https://` added when the creator left it out.", "type": [ "string", "null" ] }, "avatarUrl": { "description": "Profile picture.", "type": [ "string", "null" ] }, "snapcodeUrl": { "description": "The account's Snapcode (SVG), scannable to add them.", "type": [ "string", "null" ] }, "category": { "description": "Profile category, e.g. `people` or `business-group`.", "type": [ "string", "null" ] }, "subcategory": { "description": "Profile subcategory, e.g. `artist` or `sports-league`.", "type": [ "string", "null" ] }, "badge": { "anyOf": [ { "type": "string", "enum": [ "star", "tick", "snapchat_plus" ] }, { "type": "null" } ], "description": "Badge next to the name: `star` (Snap Star), `tick` (verified checkmark) or `snapchat_plus`; null without one." }, "verified": { "type": "boolean", "description": "Has a Snap Star or checkmark badge." }, "isPublic": { "type": "boolean", "description": "Has a Public Profile. Only public profiles show stories, highlights and Spotlight on the web; for other accounts the lists are empty." }, "hasStory": { "type": "boolean", "description": "A public story is live right now (`story` isn't empty)." }, "createdAt": { "description": "When the Public Profile was created; null if not public, ISO 8601.", "type": [ "string", "null" ] }, "url": { "type": "string", "description": "Profile on snapchat.com." } }, "required": [ "username", "displayName", "bio", "subscriberCount", "website", "avatarUrl", "snapcodeUrl", "category", "subcategory", "badge", "verified", "isPublic", "hasStory", "createdAt", "url" ], "additionalProperties": false, "description": "The account." }, "story": { "type": "array", "items": { "type": "object", "properties": { "id": { "description": "Snap id. null in highlights, where Snapchat serves snaps without one.", "type": [ "string", "null" ] }, "type": { "type": "string", "enum": [ "image", "video" ], "description": "`image` or `video`." }, "thumbnailUrl": { "description": "Small preview image on Snapchat's CDN.", "type": [ "string", "null" ] }, "mediaUrl": { "type": "string", "description": "The full image or video on Snapchat's CDN. Opens in a browser as is: no login, no cookies." }, "postedAt": { "description": "When it was posted, ISO 8601.", "type": [ "string", "null" ] } }, "required": [ "id", "type", "thumbnailUrl", "mediaUrl", "postedAt" ], "additionalProperties": false }, "description": "The public story that's live now, oldest snap first. Empty when there's none." }, "highlights": { "type": "array", "items": { "type": "object", "properties": { "id": { "description": "Highlight id.", "type": [ "string", "null" ] }, "title": { "description": "The highlight's title, as the creator named it.", "type": [ "string", "null" ] }, "thumbnailUrl": { "description": "Cover image.", "type": [ "string", "null" ] }, "snaps": { "type": "array", "items": { "type": "object", "properties": { "id": { "description": "Snap id. null in highlights, where Snapchat serves snaps without one.", "type": [ "string", "null" ] }, "type": { "type": "string", "enum": [ "image", "video" ], "description": "`image` or `video`." }, "thumbnailUrl": { "description": "Small preview image on Snapchat's CDN.", "type": [ "string", "null" ] }, "mediaUrl": { "type": "string", "description": "The full image or video on Snapchat's CDN. Opens in a browser as is: no login, no cookies." }, "postedAt": { "description": "When it was posted, ISO 8601.", "type": [ "string", "null" ] } }, "required": [ "id", "type", "thumbnailUrl", "mediaUrl", "postedAt" ], "additionalProperties": false }, "description": "The snaps saved in this highlight, in order." } }, "required": [ "id", "title", "thumbnailUrl", "snaps" ], "additionalProperties": false }, "description": "Saved story highlights, as ordered on the profile." }, "spotlight": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Spotlight id." }, "url": { "type": "string", "description": "The Spotlight's page on snapchat.com." }, "title": { "description": "The creator's title or on-screen caption. When there's none, Snapchat's own AI-generated title; null if neither exists.", "type": [ "string", "null" ] }, "description": { "description": "The creator's description, hashtags included; null if empty.", "type": [ "string", "null" ] }, "thumbnailUrl": { "description": "Cover image.", "type": [ "string", "null" ] }, "videoUrl": { "type": "string", "description": "The video on Snapchat's CDN. Opens in a browser as is." }, "durationMs": { "description": "Length in milliseconds.", "type": [ "number", "null" ] }, "views": { "description": "View count; null if hidden.", "type": [ "number", "null" ] }, "shares": { "description": "Share count; null if Snapchat didn't include it.", "type": [ "number", "null" ] }, "comments": { "description": "Comment count; null if Snapchat didn't include it.", "type": [ "number", "null" ] }, "postedAt": { "description": "When it was posted, ISO 8601.", "type": [ "string", "null" ] }, "hashtags": { "type": "array", "items": { "type": "string" }, "description": "Hashtags, as written, e.g. `#nba`." } }, "required": [ "id", "url", "title", "description", "thumbnailUrl", "videoUrl", "durationMs", "views", "shares", "comments", "postedAt", "hashtags" ], "additionalProperties": false }, "description": "Recent Spotlight videos (up to ~25), newest first." }, "relatedAccounts": { "type": "array", "items": { "type": "object", "properties": { "username": { "type": "string", "description": "Username." }, "displayName": { "description": "Display name.", "type": [ "string", "null" ] }, "avatarUrl": { "description": "Profile picture.", "type": [ "string", "null" ] }, "verified": { "type": "boolean", "description": "Has a Snap Star or checkmark badge." }, "url": { "type": "string", "description": "Profile on snapchat.com." } }, "required": [ "username", "displayName", "avatarUrl", "verified", "url" ], "additionalProperties": false }, "description": "Accounts Snapchat suggests alongside this one." } }, "required": [ "success", "credits_remaining", "credits_charged", "profile", "story", "highlights", "spotlight", "relatedAccounts" ], "additionalProperties": false } } } }, "404": { "description": "not_found: The endpoint, or the thing you asked for (ad, post, subreddit), doesn't exist. Charged when the platform was checked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error. Not charged, except the endpoint's own 4xx answers such as not_found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/truthsocial/profile": { "get": { "operationId": "truthsocial_profile", "tags": [ "Truth Social" ], "summary": "Profile", "description": "An account's bio, avatar, follower and post counts, and verification.\n\nUse it to size up an account: followers, following, post count, verification and the date of the latest post. `id` is what user posts takes as `user_id`.\n\nPass `handle` as a username, `@username` or a truthsocial.com profile URL.\n\nUnknown accounts return 404 `not_found`. Accounts explicitly hidden from logged-out visitors return 403 `not_public`. When the upstream cannot distinguish a hidden account from a missing one, the response is 404 `not_found`. Prominent accounts and most other public ones are visible.\n\nCost: 1 credit.", "externalDocs": { "url": "https://lurkapi.com/docs/truthsocial/profile" }, "x-credits": 1, "parameters": [ { "name": "handle", "in": "query", "required": true, "description": "Username, with or without @ (e.g. `realDonaldTrump`), or the profile URL.", "schema": { "description": "Username, with or without @ (e.g. `realDonaldTrump`), or the profile URL.", "type": "string" }, "example": "realDonaldTrump" } ], "responses": { "200": { "description": "An account's bio, avatar, follower and post counts, and verification.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "const": true, "description": "Always true here; errors have `success: false`." }, "credits_remaining": { "type": "number", "description": "Your balance after this call. On anonymous playground calls: free tries left today." }, "credits_charged": { "type": "number", "description": "Credits this call cost; 0 on free endpoints. On anonymous playground calls: tries used (1)." }, "id": { "type": "string", "description": "Account id, e.g. `107780257626128497`. Pass it as `user_id` to user posts." }, "username": { "type": "string", "description": "Username without @, e.g. `realDonaldTrump`." }, "acct": { "type": "string", "description": "Same as username: every Truth Social account is local." }, "display_name": { "type": "string", "description": "Display name." }, "note": { "type": "string", "description": "Bio as HTML." }, "note_text": { "type": "string", "description": "Bio as plain text." }, "url": { "type": "string", "description": "Profile on truthsocial.com." }, "avatar": { "description": "Profile picture URL; null if none.", "type": [ "string", "null" ] }, "header": { "description": "Banner image URL; null if none.", "type": [ "string", "null" ] }, "website": { "description": "Website from the profile, as typed (may lack https://); null if none.", "type": [ "string", "null" ] }, "location": { "description": "Location from the profile; null if none.", "type": [ "string", "null" ] }, "fields": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Label." }, "value": { "type": "string", "description": "Value as HTML." } }, "required": [ "name", "value" ], "additionalProperties": false }, "description": "Extra profile fields (label/value pairs)." }, "followers_count": { "type": "number", "description": "Followers." }, "following_count": { "type": "number", "description": "Accounts followed." }, "statuses_count": { "type": "number", "description": "Posts, replies and reposts." }, "last_status_at": { "description": "Day of the latest post, `YYYY-MM-DD`; null if never posted.", "type": [ "string", "null" ] }, "verified": { "type": "boolean", "description": "Has the verified badge." }, "premium": { "description": "Has Truth+ premium; null if not reported.", "type": [ "boolean", "null" ] }, "locked": { "type": "boolean", "description": "Approves followers manually." }, "bot": { "type": "boolean", "description": "Marked as an automated account." }, "created_at": { "type": "string", "description": "Account created at, ISO 8601." } }, "required": [ "success", "credits_remaining", "credits_charged", "id", "username", "acct", "display_name", "note", "note_text", "url", "avatar", "header", "website", "location", "fields", "followers_count", "following_count", "statuses_count", "last_status_at", "verified", "premium", "locked", "bot", "created_at" ], "additionalProperties": false } } } }, "403": { "description": "not_public: The platform confirmed this account or content isn't available to logged-out visitors. Use a publicly visible target.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "not_found: The endpoint, or the thing you asked for (ad, post, subreddit), doesn't exist. Charged when the platform was checked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error. Not charged, except the endpoint's own 4xx answers such as not_found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/truthsocial/user/posts": { "get": { "operationId": "truthsocial_user_posts", "tags": [ "Truth Social" ], "summary": "User posts", "description": "An account's latest posts and ReTruths, newest first, 20 per page.\n\nUse it to monitor an account: every post with text, media, link previews and reply, ReTruth and like counts. Replies are left out; ReTruths are included, with the original post in `reblog`.\n\nPass `handle` or `user_id` (from profile). `user_id` skips a lookup, but both cost 1 credit.\n\n**Pagination.** Pass the response's `next_max_id` back as `next_max_id` (with the same account) for older posts. It's null once a page comes back empty.\n\nUnknown accounts return 404 `not_found`. Accounts explicitly hidden from logged-out visitors return 403 `not_public`. When the upstream cannot distinguish a hidden account from a missing one, the response is 404 `not_found`. Prominent accounts and most other public ones are visible.\n\nCost: 1 credit.", "externalDocs": { "url": "https://lurkapi.com/docs/truthsocial/user-posts" }, "x-credits": 1, "parameters": [ { "name": "handle", "in": "query", "required": false, "description": "Username (e.g. `realDonaldTrump`), `@username` or profile URL. Required unless you pass `user_id`.", "schema": { "description": "Username (e.g. `realDonaldTrump`), `@username` or profile URL. Required unless you pass `user_id`.", "type": "string" }, "example": "realDonaldTrump" }, { "name": "user_id", "in": "query", "required": false, "description": "Numeric account id from profile, e.g. `107780257626128497`. Used instead of `handle` when both are given.", "schema": { "description": "Numeric account id from profile, e.g. `107780257626128497`. Used instead of `handle` when both are given.", "type": "string" } }, { "name": "next_max_id", "in": "query", "required": false, "description": "The `next_max_id` from the previous response, to get older posts.", "schema": { "description": "The `next_max_id` from the previous response, to get older posts.", "type": "string", "pattern": "^\\d{1,20}$" } }, { "name": "trim", "in": "query", "required": false, "description": "`true` omits each post's HTML `content` (plain `text` stays) for a smaller response.", "schema": { "description": "`true` omits each post's HTML `content` (plain `text` stays) for a smaller response.", "default": "false", "type": "string", "enum": [ "true", "false" ] } } ], "responses": { "200": { "description": "An account's latest posts and ReTruths, newest first, 20 per page.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "const": true, "description": "Always true here; errors have `success: false`." }, "credits_remaining": { "type": "number", "description": "Your balance after this call. On anonymous playground calls: free tries left today." }, "credits_charged": { "type": "number", "description": "Credits this call cost; 0 on free endpoints. On anonymous playground calls: tries used (1)." }, "posts": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Post id, e.g. `117351985093810875`." }, "created_at": { "type": "string", "description": "Posted at, ISO 8601." }, "url": { "type": "string", "description": "The post on truthsocial.com." }, "content": { "description": "Post text as HTML. Omitted with trim=true.", "type": "string" }, "text": { "type": "string", "description": "Post text, plain. Empty for media-only posts and plain reposts." }, "title": { "description": "Title, on group posts that have one; else null.", "type": [ "string", "null" ] }, "language": { "description": "Language code (e.g. `en`) when detected; often null.", "type": [ "string", "null" ] }, "visibility": { "type": "string", "description": "`public`, or `group` for posts in a group." }, "sensitive": { "type": "boolean", "description": "Marked sensitive (media hidden behind a warning)." }, "spoiler_text": { "type": "string", "description": "Content warning; empty if none." }, "in_reply_to_id": { "description": "The post this replies to; null if not a reply.", "type": [ "string", "null" ] }, "in_reply_to_account_id": { "description": "Author of the post this replies to.", "type": [ "string", "null" ] }, "quote_id": { "description": "The quoted post's id; null if not a quote.", "type": [ "string", "null" ] }, "replies_count": { "type": "number", "description": "Replies." }, "reblogs_count": { "type": "number", "description": "ReTruths (reposts)." }, "favourites_count": { "type": "number", "description": "Likes." }, "upvotes_count": { "description": "Upvotes (Truth Social's likes); null if not reported.", "type": [ "number", "null" ] }, "downvotes_count": { "description": "Downvotes; null if not reported.", "type": [ "number", "null" ] }, "edited_at": { "description": "Last edit, ISO 8601; null if never edited.", "type": [ "string", "null" ] }, "media_attachments": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Attachment id." }, "type": { "type": "string", "description": "`image`, `video`, `gifv`, `audio` or `unknown`." }, "url": { "description": "The file (full-size image or MP4).", "type": [ "string", "null" ] }, "preview_url": { "description": "A smaller image, or the video's thumbnail.", "type": [ "string", "null" ] }, "description": { "description": "Alt text; null if none.", "type": [ "string", "null" ] }, "meta": { "type": "object", "properties": { "original": { "anyOf": [ { "type": "object", "properties": { "width": { "description": "Width in pixels.", "type": [ "number", "null" ] }, "height": { "description": "Height in pixels.", "type": [ "number", "null" ] }, "aspect": { "description": "Width / height; null when not reported (videos).", "type": [ "number", "null" ] }, "duration": { "description": "Length in seconds, for video and audio; else null.", "type": [ "number", "null" ] } }, "required": [ "width", "height", "aspect", "duration" ], "additionalProperties": false }, { "type": "null" } ], "description": "Size of the file at `url`." }, "small": { "anyOf": [ { "type": "object", "properties": { "width": { "description": "Width in pixels.", "type": [ "number", "null" ] }, "height": { "description": "Height in pixels.", "type": [ "number", "null" ] }, "aspect": { "description": "Width / height; null when not reported (videos).", "type": [ "number", "null" ] }, "duration": { "description": "Length in seconds, for video and audio; else null.", "type": [ "number", "null" ] } }, "required": [ "width", "height", "aspect", "duration" ], "additionalProperties": false }, { "type": "null" } ], "description": "Size of the image at `preview_url`." } }, "required": [ "original", "small" ], "additionalProperties": false, "description": "Sizes, as Mastodon reports them." } }, "required": [ "id", "type", "url", "preview_url", "description", "meta" ], "additionalProperties": false }, "description": "Images and videos, in order." }, "card": { "anyOf": [ { "type": "object", "properties": { "url": { "type": "string", "description": "The linked page." }, "title": { "description": "Page title.", "type": [ "string", "null" ] }, "description": { "description": "Page description.", "type": [ "string", "null" ] }, "type": { "description": "`link`, `video`, `photo` or `rich`.", "type": [ "string", "null" ] }, "provider_name": { "description": "Site name, e.g. `x.com`.", "type": [ "string", "null" ] }, "image": { "description": "Preview image URL (hosted by Truth Social).", "type": [ "string", "null" ] } }, "required": [ "url", "title", "description", "type", "provider_name", "image" ], "additionalProperties": false }, { "type": "null" } ], "description": "Link preview for the first link in the post; null if none." }, "group": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "description": "Group id." }, "display_name": { "type": "string", "description": "Group name." }, "slug": { "description": "URL name, e.g. `republicans`.", "type": [ "string", "null" ] }, "url": { "description": "Group on truthsocial.com.", "type": [ "string", "null" ] }, "members_count": { "description": "Members.", "type": [ "number", "null" ] } }, "required": [ "id", "display_name", "slug", "url", "members_count" ], "additionalProperties": false }, { "type": "null" } ], "description": "The group it was posted in; null for ordinary posts." }, "mentions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Account id." }, "username": { "type": "string", "description": "Username without @." }, "acct": { "type": "string", "description": "Same as username." }, "url": { "type": "string", "description": "Profile on truthsocial.com." } }, "required": [ "id", "username", "acct", "url" ], "additionalProperties": false }, "description": "Accounts mentioned." }, "tags": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Hashtag without #." }, "url": { "type": "string", "description": "Hashtag page on truthsocial.com." } }, "required": [ "name", "url" ], "additionalProperties": false }, "description": "Hashtags used." }, "account": { "type": "object", "properties": { "id": { "type": "string", "description": "Account id." }, "username": { "type": "string", "description": "Username without @." }, "acct": { "type": "string", "description": "Same as username." }, "display_name": { "type": "string", "description": "Display name." }, "url": { "type": "string", "description": "Profile on truthsocial.com." }, "avatar": { "description": "Profile picture URL; null if none.", "type": [ "string", "null" ] }, "verified": { "type": "boolean", "description": "Has the verified badge." }, "followers_count": { "type": "number", "description": "Followers." } }, "required": [ "id", "username", "acct", "display_name", "url", "avatar", "verified", "followers_count" ], "additionalProperties": false, "description": "The author." }, "reblog": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "description": "Post id, e.g. `117351985093810875`." }, "created_at": { "type": "string", "description": "Posted at, ISO 8601." }, "url": { "type": "string", "description": "The post on truthsocial.com." }, "content": { "description": "Post text as HTML. Omitted with trim=true.", "type": "string" }, "text": { "type": "string", "description": "Post text, plain. Empty for media-only posts and plain reposts." }, "title": { "description": "Title, on group posts that have one; else null.", "type": [ "string", "null" ] }, "language": { "description": "Language code (e.g. `en`) when detected; often null.", "type": [ "string", "null" ] }, "visibility": { "type": "string", "description": "`public`, or `group` for posts in a group." }, "sensitive": { "type": "boolean", "description": "Marked sensitive (media hidden behind a warning)." }, "spoiler_text": { "type": "string", "description": "Content warning; empty if none." }, "in_reply_to_id": { "description": "The post this replies to; null if not a reply.", "type": [ "string", "null" ] }, "in_reply_to_account_id": { "description": "Author of the post this replies to.", "type": [ "string", "null" ] }, "quote_id": { "description": "The quoted post's id; null if not a quote.", "type": [ "string", "null" ] }, "replies_count": { "type": "number", "description": "Replies." }, "reblogs_count": { "type": "number", "description": "ReTruths (reposts)." }, "favourites_count": { "type": "number", "description": "Likes." }, "upvotes_count": { "description": "Upvotes (Truth Social's likes); null if not reported.", "type": [ "number", "null" ] }, "downvotes_count": { "description": "Downvotes; null if not reported.", "type": [ "number", "null" ] }, "edited_at": { "description": "Last edit, ISO 8601; null if never edited.", "type": [ "string", "null" ] }, "media_attachments": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Attachment id." }, "type": { "type": "string", "description": "`image`, `video`, `gifv`, `audio` or `unknown`." }, "url": { "description": "The file (full-size image or MP4).", "type": [ "string", "null" ] }, "preview_url": { "description": "A smaller image, or the video's thumbnail.", "type": [ "string", "null" ] }, "description": { "description": "Alt text; null if none.", "type": [ "string", "null" ] }, "meta": { "type": "object", "properties": { "original": { "anyOf": [ { "type": "object", "properties": { "width": { "description": "Width in pixels.", "type": [ "number", "null" ] }, "height": { "description": "Height in pixels.", "type": [ "number", "null" ] }, "aspect": { "description": "Width / height; null when not reported (videos).", "type": [ "number", "null" ] }, "duration": { "description": "Length in seconds, for video and audio; else null.", "type": [ "number", "null" ] } }, "required": [ "width", "height", "aspect", "duration" ], "additionalProperties": false }, { "type": "null" } ], "description": "Size of the file at `url`." }, "small": { "anyOf": [ { "type": "object", "properties": { "width": { "description": "Width in pixels.", "type": [ "number", "null" ] }, "height": { "description": "Height in pixels.", "type": [ "number", "null" ] }, "aspect": { "description": "Width / height; null when not reported (videos).", "type": [ "number", "null" ] }, "duration": { "description": "Length in seconds, for video and audio; else null.", "type": [ "number", "null" ] } }, "required": [ "width", "height", "aspect", "duration" ], "additionalProperties": false }, { "type": "null" } ], "description": "Size of the image at `preview_url`." } }, "required": [ "original", "small" ], "additionalProperties": false, "description": "Sizes, as Mastodon reports them." } }, "required": [ "id", "type", "url", "preview_url", "description", "meta" ], "additionalProperties": false }, "description": "Images and videos, in order." }, "card": { "anyOf": [ { "type": "object", "properties": { "url": { "type": "string", "description": "The linked page." }, "title": { "description": "Page title.", "type": [ "string", "null" ] }, "description": { "description": "Page description.", "type": [ "string", "null" ] }, "type": { "description": "`link`, `video`, `photo` or `rich`.", "type": [ "string", "null" ] }, "provider_name": { "description": "Site name, e.g. `x.com`.", "type": [ "string", "null" ] }, "image": { "description": "Preview image URL (hosted by Truth Social).", "type": [ "string", "null" ] } }, "required": [ "url", "title", "description", "type", "provider_name", "image" ], "additionalProperties": false }, { "type": "null" } ], "description": "Link preview for the first link in the post; null if none." }, "group": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "description": "Group id." }, "display_name": { "type": "string", "description": "Group name." }, "slug": { "description": "URL name, e.g. `republicans`.", "type": [ "string", "null" ] }, "url": { "description": "Group on truthsocial.com.", "type": [ "string", "null" ] }, "members_count": { "description": "Members.", "type": [ "number", "null" ] } }, "required": [ "id", "display_name", "slug", "url", "members_count" ], "additionalProperties": false }, { "type": "null" } ], "description": "The group it was posted in; null for ordinary posts." }, "mentions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Account id." }, "username": { "type": "string", "description": "Username without @." }, "acct": { "type": "string", "description": "Same as username." }, "url": { "type": "string", "description": "Profile on truthsocial.com." } }, "required": [ "id", "username", "acct", "url" ], "additionalProperties": false }, "description": "Accounts mentioned." }, "tags": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Hashtag without #." }, "url": { "type": "string", "description": "Hashtag page on truthsocial.com." } }, "required": [ "name", "url" ], "additionalProperties": false }, "description": "Hashtags used." }, "account": { "type": "object", "properties": { "id": { "type": "string", "description": "Account id." }, "username": { "type": "string", "description": "Username without @." }, "acct": { "type": "string", "description": "Same as username." }, "display_name": { "type": "string", "description": "Display name." }, "url": { "type": "string", "description": "Profile on truthsocial.com." }, "avatar": { "description": "Profile picture URL; null if none.", "type": [ "string", "null" ] }, "verified": { "type": "boolean", "description": "Has the verified badge." }, "followers_count": { "type": "number", "description": "Followers." } }, "required": [ "id", "username", "acct", "display_name", "url", "avatar", "verified", "followers_count" ], "additionalProperties": false, "description": "The author." } }, "required": [ "id", "created_at", "url", "text", "title", "language", "visibility", "sensitive", "spoiler_text", "in_reply_to_id", "in_reply_to_account_id", "quote_id", "replies_count", "reblogs_count", "favourites_count", "upvotes_count", "downvotes_count", "edited_at", "media_attachments", "card", "group", "mentions", "tags", "account" ], "additionalProperties": false }, { "type": "null" } ], "description": "On a ReTruth (repost): the original post. null otherwise." }, "quote": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "description": "Post id, e.g. `117351985093810875`." }, "created_at": { "type": "string", "description": "Posted at, ISO 8601." }, "url": { "type": "string", "description": "The post on truthsocial.com." }, "content": { "description": "Post text as HTML. Omitted with trim=true.", "type": "string" }, "text": { "type": "string", "description": "Post text, plain. Empty for media-only posts and plain reposts." }, "title": { "description": "Title, on group posts that have one; else null.", "type": [ "string", "null" ] }, "language": { "description": "Language code (e.g. `en`) when detected; often null.", "type": [ "string", "null" ] }, "visibility": { "type": "string", "description": "`public`, or `group` for posts in a group." }, "sensitive": { "type": "boolean", "description": "Marked sensitive (media hidden behind a warning)." }, "spoiler_text": { "type": "string", "description": "Content warning; empty if none." }, "in_reply_to_id": { "description": "The post this replies to; null if not a reply.", "type": [ "string", "null" ] }, "in_reply_to_account_id": { "description": "Author of the post this replies to.", "type": [ "string", "null" ] }, "quote_id": { "description": "The quoted post's id; null if not a quote.", "type": [ "string", "null" ] }, "replies_count": { "type": "number", "description": "Replies." }, "reblogs_count": { "type": "number", "description": "ReTruths (reposts)." }, "favourites_count": { "type": "number", "description": "Likes." }, "upvotes_count": { "description": "Upvotes (Truth Social's likes); null if not reported.", "type": [ "number", "null" ] }, "downvotes_count": { "description": "Downvotes; null if not reported.", "type": [ "number", "null" ] }, "edited_at": { "description": "Last edit, ISO 8601; null if never edited.", "type": [ "string", "null" ] }, "media_attachments": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Attachment id." }, "type": { "type": "string", "description": "`image`, `video`, `gifv`, `audio` or `unknown`." }, "url": { "description": "The file (full-size image or MP4).", "type": [ "string", "null" ] }, "preview_url": { "description": "A smaller image, or the video's thumbnail.", "type": [ "string", "null" ] }, "description": { "description": "Alt text; null if none.", "type": [ "string", "null" ] }, "meta": { "type": "object", "properties": { "original": { "anyOf": [ { "type": "object", "properties": { "width": { "description": "Width in pixels.", "type": [ "number", "null" ] }, "height": { "description": "Height in pixels.", "type": [ "number", "null" ] }, "aspect": { "description": "Width / height; null when not reported (videos).", "type": [ "number", "null" ] }, "duration": { "description": "Length in seconds, for video and audio; else null.", "type": [ "number", "null" ] } }, "required": [ "width", "height", "aspect", "duration" ], "additionalProperties": false }, { "type": "null" } ], "description": "Size of the file at `url`." }, "small": { "anyOf": [ { "type": "object", "properties": { "width": { "description": "Width in pixels.", "type": [ "number", "null" ] }, "height": { "description": "Height in pixels.", "type": [ "number", "null" ] }, "aspect": { "description": "Width / height; null when not reported (videos).", "type": [ "number", "null" ] }, "duration": { "description": "Length in seconds, for video and audio; else null.", "type": [ "number", "null" ] } }, "required": [ "width", "height", "aspect", "duration" ], "additionalProperties": false }, { "type": "null" } ], "description": "Size of the image at `preview_url`." } }, "required": [ "original", "small" ], "additionalProperties": false, "description": "Sizes, as Mastodon reports them." } }, "required": [ "id", "type", "url", "preview_url", "description", "meta" ], "additionalProperties": false }, "description": "Images and videos, in order." }, "card": { "anyOf": [ { "type": "object", "properties": { "url": { "type": "string", "description": "The linked page." }, "title": { "description": "Page title.", "type": [ "string", "null" ] }, "description": { "description": "Page description.", "type": [ "string", "null" ] }, "type": { "description": "`link`, `video`, `photo` or `rich`.", "type": [ "string", "null" ] }, "provider_name": { "description": "Site name, e.g. `x.com`.", "type": [ "string", "null" ] }, "image": { "description": "Preview image URL (hosted by Truth Social).", "type": [ "string", "null" ] } }, "required": [ "url", "title", "description", "type", "provider_name", "image" ], "additionalProperties": false }, { "type": "null" } ], "description": "Link preview for the first link in the post; null if none." }, "group": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "description": "Group id." }, "display_name": { "type": "string", "description": "Group name." }, "slug": { "description": "URL name, e.g. `republicans`.", "type": [ "string", "null" ] }, "url": { "description": "Group on truthsocial.com.", "type": [ "string", "null" ] }, "members_count": { "description": "Members.", "type": [ "number", "null" ] } }, "required": [ "id", "display_name", "slug", "url", "members_count" ], "additionalProperties": false }, { "type": "null" } ], "description": "The group it was posted in; null for ordinary posts." }, "mentions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Account id." }, "username": { "type": "string", "description": "Username without @." }, "acct": { "type": "string", "description": "Same as username." }, "url": { "type": "string", "description": "Profile on truthsocial.com." } }, "required": [ "id", "username", "acct", "url" ], "additionalProperties": false }, "description": "Accounts mentioned." }, "tags": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Hashtag without #." }, "url": { "type": "string", "description": "Hashtag page on truthsocial.com." } }, "required": [ "name", "url" ], "additionalProperties": false }, "description": "Hashtags used." }, "account": { "type": "object", "properties": { "id": { "type": "string", "description": "Account id." }, "username": { "type": "string", "description": "Username without @." }, "acct": { "type": "string", "description": "Same as username." }, "display_name": { "type": "string", "description": "Display name." }, "url": { "type": "string", "description": "Profile on truthsocial.com." }, "avatar": { "description": "Profile picture URL; null if none.", "type": [ "string", "null" ] }, "verified": { "type": "boolean", "description": "Has the verified badge." }, "followers_count": { "type": "number", "description": "Followers." } }, "required": [ "id", "username", "acct", "display_name", "url", "avatar", "verified", "followers_count" ], "additionalProperties": false, "description": "The author." } }, "required": [ "id", "created_at", "url", "text", "title", "language", "visibility", "sensitive", "spoiler_text", "in_reply_to_id", "in_reply_to_account_id", "quote_id", "replies_count", "reblogs_count", "favourites_count", "upvotes_count", "downvotes_count", "edited_at", "media_attachments", "card", "group", "mentions", "tags", "account" ], "additionalProperties": false }, { "type": "null" } ], "description": "On a quote post: the quoted post. null otherwise." } }, "required": [ "id", "created_at", "url", "text", "title", "language", "visibility", "sensitive", "spoiler_text", "in_reply_to_id", "in_reply_to_account_id", "quote_id", "replies_count", "reblogs_count", "favourites_count", "upvotes_count", "downvotes_count", "edited_at", "media_attachments", "card", "group", "mentions", "tags", "account", "reblog", "quote" ], "additionalProperties": false }, "description": "Posts and ReTruths, newest first." }, "next_max_id": { "description": "Pass as `next_max_id` for older posts. null when this page is empty.", "type": [ "string", "null" ] } }, "required": [ "success", "credits_remaining", "credits_charged", "posts", "next_max_id" ], "additionalProperties": false } } } }, "403": { "description": "not_public: The platform confirmed this account or content isn't available to logged-out visitors. Use a publicly visible target.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "not_found: The endpoint, or the thing you asked for (ad, post, subreddit), doesn't exist. Charged when the platform was checked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error. Not charged, except the endpoint's own 4xx answers such as not_found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/truthsocial/post": { "get": { "operationId": "truthsocial_post", "tags": [ "Truth Social" ], "summary": "Post", "description": "One post with its text, media, link preview and engagement counts.\n\nUse it to read or track a single post: text (HTML and plain), images and videos, link preview, and reply, ReTruth, like and upvote counts. ReTruths carry the original in `reblog`, quote posts the quoted post in `quote`.\n\nPass the post's URL (`https://truthsocial.com/@/posts/`, `/@/` or a group post URL) or its numeric id.\n\nUnknown and deleted posts return 404 `not_found`.\n\nCost: 1 credit.", "externalDocs": { "url": "https://lurkapi.com/docs/truthsocial/post" }, "x-credits": 1, "parameters": [ { "name": "url", "in": "query", "required": true, "description": "The post's URL, e.g. `https://truthsocial.com/@realDonaldTrump/posts/117351985093810875`, or its id.", "schema": { "type": "string", "description": "The post's URL, e.g. `https://truthsocial.com/@realDonaldTrump/posts/117351985093810875`, or its id." }, "example": "https://truthsocial.com/@realDonaldTrump/posts/117351985093810875" } ], "responses": { "200": { "description": "One post with its text, media, link preview and engagement counts.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "const": true, "description": "Always true here; errors have `success: false`." }, "credits_remaining": { "type": "number", "description": "Your balance after this call. On anonymous playground calls: free tries left today." }, "credits_charged": { "type": "number", "description": "Credits this call cost; 0 on free endpoints. On anonymous playground calls: tries used (1)." }, "id": { "type": "string", "description": "Post id, e.g. `117351985093810875`." }, "created_at": { "type": "string", "description": "Posted at, ISO 8601." }, "url": { "type": "string", "description": "The post on truthsocial.com." }, "content": { "description": "Post text as HTML. Omitted with trim=true.", "type": "string" }, "text": { "type": "string", "description": "Post text, plain. Empty for media-only posts and plain reposts." }, "title": { "description": "Title, on group posts that have one; else null.", "type": [ "string", "null" ] }, "language": { "description": "Language code (e.g. `en`) when detected; often null.", "type": [ "string", "null" ] }, "visibility": { "type": "string", "description": "`public`, or `group` for posts in a group." }, "sensitive": { "type": "boolean", "description": "Marked sensitive (media hidden behind a warning)." }, "spoiler_text": { "type": "string", "description": "Content warning; empty if none." }, "in_reply_to_id": { "description": "The post this replies to; null if not a reply.", "type": [ "string", "null" ] }, "in_reply_to_account_id": { "description": "Author of the post this replies to.", "type": [ "string", "null" ] }, "quote_id": { "description": "The quoted post's id; null if not a quote.", "type": [ "string", "null" ] }, "replies_count": { "type": "number", "description": "Replies." }, "reblogs_count": { "type": "number", "description": "ReTruths (reposts)." }, "favourites_count": { "type": "number", "description": "Likes." }, "upvotes_count": { "description": "Upvotes (Truth Social's likes); null if not reported.", "type": [ "number", "null" ] }, "downvotes_count": { "description": "Downvotes; null if not reported.", "type": [ "number", "null" ] }, "edited_at": { "description": "Last edit, ISO 8601; null if never edited.", "type": [ "string", "null" ] }, "media_attachments": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Attachment id." }, "type": { "type": "string", "description": "`image`, `video`, `gifv`, `audio` or `unknown`." }, "url": { "description": "The file (full-size image or MP4).", "type": [ "string", "null" ] }, "preview_url": { "description": "A smaller image, or the video's thumbnail.", "type": [ "string", "null" ] }, "description": { "description": "Alt text; null if none.", "type": [ "string", "null" ] }, "meta": { "type": "object", "properties": { "original": { "anyOf": [ { "type": "object", "properties": { "width": { "description": "Width in pixels.", "type": [ "number", "null" ] }, "height": { "description": "Height in pixels.", "type": [ "number", "null" ] }, "aspect": { "description": "Width / height; null when not reported (videos).", "type": [ "number", "null" ] }, "duration": { "description": "Length in seconds, for video and audio; else null.", "type": [ "number", "null" ] } }, "required": [ "width", "height", "aspect", "duration" ], "additionalProperties": false }, { "type": "null" } ], "description": "Size of the file at `url`." }, "small": { "anyOf": [ { "type": "object", "properties": { "width": { "description": "Width in pixels.", "type": [ "number", "null" ] }, "height": { "description": "Height in pixels.", "type": [ "number", "null" ] }, "aspect": { "description": "Width / height; null when not reported (videos).", "type": [ "number", "null" ] }, "duration": { "description": "Length in seconds, for video and audio; else null.", "type": [ "number", "null" ] } }, "required": [ "width", "height", "aspect", "duration" ], "additionalProperties": false }, { "type": "null" } ], "description": "Size of the image at `preview_url`." } }, "required": [ "original", "small" ], "additionalProperties": false, "description": "Sizes, as Mastodon reports them." } }, "required": [ "id", "type", "url", "preview_url", "description", "meta" ], "additionalProperties": false }, "description": "Images and videos, in order." }, "card": { "anyOf": [ { "type": "object", "properties": { "url": { "type": "string", "description": "The linked page." }, "title": { "description": "Page title.", "type": [ "string", "null" ] }, "description": { "description": "Page description.", "type": [ "string", "null" ] }, "type": { "description": "`link`, `video`, `photo` or `rich`.", "type": [ "string", "null" ] }, "provider_name": { "description": "Site name, e.g. `x.com`.", "type": [ "string", "null" ] }, "image": { "description": "Preview image URL (hosted by Truth Social).", "type": [ "string", "null" ] } }, "required": [ "url", "title", "description", "type", "provider_name", "image" ], "additionalProperties": false }, { "type": "null" } ], "description": "Link preview for the first link in the post; null if none." }, "group": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "description": "Group id." }, "display_name": { "type": "string", "description": "Group name." }, "slug": { "description": "URL name, e.g. `republicans`.", "type": [ "string", "null" ] }, "url": { "description": "Group on truthsocial.com.", "type": [ "string", "null" ] }, "members_count": { "description": "Members.", "type": [ "number", "null" ] } }, "required": [ "id", "display_name", "slug", "url", "members_count" ], "additionalProperties": false }, { "type": "null" } ], "description": "The group it was posted in; null for ordinary posts." }, "mentions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Account id." }, "username": { "type": "string", "description": "Username without @." }, "acct": { "type": "string", "description": "Same as username." }, "url": { "type": "string", "description": "Profile on truthsocial.com." } }, "required": [ "id", "username", "acct", "url" ], "additionalProperties": false }, "description": "Accounts mentioned." }, "tags": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Hashtag without #." }, "url": { "type": "string", "description": "Hashtag page on truthsocial.com." } }, "required": [ "name", "url" ], "additionalProperties": false }, "description": "Hashtags used." }, "account": { "type": "object", "properties": { "id": { "type": "string", "description": "Account id." }, "username": { "type": "string", "description": "Username without @." }, "acct": { "type": "string", "description": "Same as username." }, "display_name": { "type": "string", "description": "Display name." }, "url": { "type": "string", "description": "Profile on truthsocial.com." }, "avatar": { "description": "Profile picture URL; null if none.", "type": [ "string", "null" ] }, "verified": { "type": "boolean", "description": "Has the verified badge." }, "followers_count": { "type": "number", "description": "Followers." } }, "required": [ "id", "username", "acct", "display_name", "url", "avatar", "verified", "followers_count" ], "additionalProperties": false, "description": "The author." }, "reblog": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "description": "Post id, e.g. `117351985093810875`." }, "created_at": { "type": "string", "description": "Posted at, ISO 8601." }, "url": { "type": "string", "description": "The post on truthsocial.com." }, "content": { "description": "Post text as HTML. Omitted with trim=true.", "type": "string" }, "text": { "type": "string", "description": "Post text, plain. Empty for media-only posts and plain reposts." }, "title": { "description": "Title, on group posts that have one; else null.", "type": [ "string", "null" ] }, "language": { "description": "Language code (e.g. `en`) when detected; often null.", "type": [ "string", "null" ] }, "visibility": { "type": "string", "description": "`public`, or `group` for posts in a group." }, "sensitive": { "type": "boolean", "description": "Marked sensitive (media hidden behind a warning)." }, "spoiler_text": { "type": "string", "description": "Content warning; empty if none." }, "in_reply_to_id": { "description": "The post this replies to; null if not a reply.", "type": [ "string", "null" ] }, "in_reply_to_account_id": { "description": "Author of the post this replies to.", "type": [ "string", "null" ] }, "quote_id": { "description": "The quoted post's id; null if not a quote.", "type": [ "string", "null" ] }, "replies_count": { "type": "number", "description": "Replies." }, "reblogs_count": { "type": "number", "description": "ReTruths (reposts)." }, "favourites_count": { "type": "number", "description": "Likes." }, "upvotes_count": { "description": "Upvotes (Truth Social's likes); null if not reported.", "type": [ "number", "null" ] }, "downvotes_count": { "description": "Downvotes; null if not reported.", "type": [ "number", "null" ] }, "edited_at": { "description": "Last edit, ISO 8601; null if never edited.", "type": [ "string", "null" ] }, "media_attachments": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Attachment id." }, "type": { "type": "string", "description": "`image`, `video`, `gifv`, `audio` or `unknown`." }, "url": { "description": "The file (full-size image or MP4).", "type": [ "string", "null" ] }, "preview_url": { "description": "A smaller image, or the video's thumbnail.", "type": [ "string", "null" ] }, "description": { "description": "Alt text; null if none.", "type": [ "string", "null" ] }, "meta": { "type": "object", "properties": { "original": { "anyOf": [ { "type": "object", "properties": { "width": { "description": "Width in pixels.", "type": [ "number", "null" ] }, "height": { "description": "Height in pixels.", "type": [ "number", "null" ] }, "aspect": { "description": "Width / height; null when not reported (videos).", "type": [ "number", "null" ] }, "duration": { "description": "Length in seconds, for video and audio; else null.", "type": [ "number", "null" ] } }, "required": [ "width", "height", "aspect", "duration" ], "additionalProperties": false }, { "type": "null" } ], "description": "Size of the file at `url`." }, "small": { "anyOf": [ { "type": "object", "properties": { "width": { "description": "Width in pixels.", "type": [ "number", "null" ] }, "height": { "description": "Height in pixels.", "type": [ "number", "null" ] }, "aspect": { "description": "Width / height; null when not reported (videos).", "type": [ "number", "null" ] }, "duration": { "description": "Length in seconds, for video and audio; else null.", "type": [ "number", "null" ] } }, "required": [ "width", "height", "aspect", "duration" ], "additionalProperties": false }, { "type": "null" } ], "description": "Size of the image at `preview_url`." } }, "required": [ "original", "small" ], "additionalProperties": false, "description": "Sizes, as Mastodon reports them." } }, "required": [ "id", "type", "url", "preview_url", "description", "meta" ], "additionalProperties": false }, "description": "Images and videos, in order." }, "card": { "anyOf": [ { "type": "object", "properties": { "url": { "type": "string", "description": "The linked page." }, "title": { "description": "Page title.", "type": [ "string", "null" ] }, "description": { "description": "Page description.", "type": [ "string", "null" ] }, "type": { "description": "`link`, `video`, `photo` or `rich`.", "type": [ "string", "null" ] }, "provider_name": { "description": "Site name, e.g. `x.com`.", "type": [ "string", "null" ] }, "image": { "description": "Preview image URL (hosted by Truth Social).", "type": [ "string", "null" ] } }, "required": [ "url", "title", "description", "type", "provider_name", "image" ], "additionalProperties": false }, { "type": "null" } ], "description": "Link preview for the first link in the post; null if none." }, "group": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "description": "Group id." }, "display_name": { "type": "string", "description": "Group name." }, "slug": { "description": "URL name, e.g. `republicans`.", "type": [ "string", "null" ] }, "url": { "description": "Group on truthsocial.com.", "type": [ "string", "null" ] }, "members_count": { "description": "Members.", "type": [ "number", "null" ] } }, "required": [ "id", "display_name", "slug", "url", "members_count" ], "additionalProperties": false }, { "type": "null" } ], "description": "The group it was posted in; null for ordinary posts." }, "mentions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Account id." }, "username": { "type": "string", "description": "Username without @." }, "acct": { "type": "string", "description": "Same as username." }, "url": { "type": "string", "description": "Profile on truthsocial.com." } }, "required": [ "id", "username", "acct", "url" ], "additionalProperties": false }, "description": "Accounts mentioned." }, "tags": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Hashtag without #." }, "url": { "type": "string", "description": "Hashtag page on truthsocial.com." } }, "required": [ "name", "url" ], "additionalProperties": false }, "description": "Hashtags used." }, "account": { "type": "object", "properties": { "id": { "type": "string", "description": "Account id." }, "username": { "type": "string", "description": "Username without @." }, "acct": { "type": "string", "description": "Same as username." }, "display_name": { "type": "string", "description": "Display name." }, "url": { "type": "string", "description": "Profile on truthsocial.com." }, "avatar": { "description": "Profile picture URL; null if none.", "type": [ "string", "null" ] }, "verified": { "type": "boolean", "description": "Has the verified badge." }, "followers_count": { "type": "number", "description": "Followers." } }, "required": [ "id", "username", "acct", "display_name", "url", "avatar", "verified", "followers_count" ], "additionalProperties": false, "description": "The author." } }, "required": [ "id", "created_at", "url", "text", "title", "language", "visibility", "sensitive", "spoiler_text", "in_reply_to_id", "in_reply_to_account_id", "quote_id", "replies_count", "reblogs_count", "favourites_count", "upvotes_count", "downvotes_count", "edited_at", "media_attachments", "card", "group", "mentions", "tags", "account" ], "additionalProperties": false }, { "type": "null" } ], "description": "On a ReTruth (repost): the original post. null otherwise." }, "quote": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "description": "Post id, e.g. `117351985093810875`." }, "created_at": { "type": "string", "description": "Posted at, ISO 8601." }, "url": { "type": "string", "description": "The post on truthsocial.com." }, "content": { "description": "Post text as HTML. Omitted with trim=true.", "type": "string" }, "text": { "type": "string", "description": "Post text, plain. Empty for media-only posts and plain reposts." }, "title": { "description": "Title, on group posts that have one; else null.", "type": [ "string", "null" ] }, "language": { "description": "Language code (e.g. `en`) when detected; often null.", "type": [ "string", "null" ] }, "visibility": { "type": "string", "description": "`public`, or `group` for posts in a group." }, "sensitive": { "type": "boolean", "description": "Marked sensitive (media hidden behind a warning)." }, "spoiler_text": { "type": "string", "description": "Content warning; empty if none." }, "in_reply_to_id": { "description": "The post this replies to; null if not a reply.", "type": [ "string", "null" ] }, "in_reply_to_account_id": { "description": "Author of the post this replies to.", "type": [ "string", "null" ] }, "quote_id": { "description": "The quoted post's id; null if not a quote.", "type": [ "string", "null" ] }, "replies_count": { "type": "number", "description": "Replies." }, "reblogs_count": { "type": "number", "description": "ReTruths (reposts)." }, "favourites_count": { "type": "number", "description": "Likes." }, "upvotes_count": { "description": "Upvotes (Truth Social's likes); null if not reported.", "type": [ "number", "null" ] }, "downvotes_count": { "description": "Downvotes; null if not reported.", "type": [ "number", "null" ] }, "edited_at": { "description": "Last edit, ISO 8601; null if never edited.", "type": [ "string", "null" ] }, "media_attachments": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Attachment id." }, "type": { "type": "string", "description": "`image`, `video`, `gifv`, `audio` or `unknown`." }, "url": { "description": "The file (full-size image or MP4).", "type": [ "string", "null" ] }, "preview_url": { "description": "A smaller image, or the video's thumbnail.", "type": [ "string", "null" ] }, "description": { "description": "Alt text; null if none.", "type": [ "string", "null" ] }, "meta": { "type": "object", "properties": { "original": { "anyOf": [ { "type": "object", "properties": { "width": { "description": "Width in pixels.", "type": [ "number", "null" ] }, "height": { "description": "Height in pixels.", "type": [ "number", "null" ] }, "aspect": { "description": "Width / height; null when not reported (videos).", "type": [ "number", "null" ] }, "duration": { "description": "Length in seconds, for video and audio; else null.", "type": [ "number", "null" ] } }, "required": [ "width", "height", "aspect", "duration" ], "additionalProperties": false }, { "type": "null" } ], "description": "Size of the file at `url`." }, "small": { "anyOf": [ { "type": "object", "properties": { "width": { "description": "Width in pixels.", "type": [ "number", "null" ] }, "height": { "description": "Height in pixels.", "type": [ "number", "null" ] }, "aspect": { "description": "Width / height; null when not reported (videos).", "type": [ "number", "null" ] }, "duration": { "description": "Length in seconds, for video and audio; else null.", "type": [ "number", "null" ] } }, "required": [ "width", "height", "aspect", "duration" ], "additionalProperties": false }, { "type": "null" } ], "description": "Size of the image at `preview_url`." } }, "required": [ "original", "small" ], "additionalProperties": false, "description": "Sizes, as Mastodon reports them." } }, "required": [ "id", "type", "url", "preview_url", "description", "meta" ], "additionalProperties": false }, "description": "Images and videos, in order." }, "card": { "anyOf": [ { "type": "object", "properties": { "url": { "type": "string", "description": "The linked page." }, "title": { "description": "Page title.", "type": [ "string", "null" ] }, "description": { "description": "Page description.", "type": [ "string", "null" ] }, "type": { "description": "`link`, `video`, `photo` or `rich`.", "type": [ "string", "null" ] }, "provider_name": { "description": "Site name, e.g. `x.com`.", "type": [ "string", "null" ] }, "image": { "description": "Preview image URL (hosted by Truth Social).", "type": [ "string", "null" ] } }, "required": [ "url", "title", "description", "type", "provider_name", "image" ], "additionalProperties": false }, { "type": "null" } ], "description": "Link preview for the first link in the post; null if none." }, "group": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "description": "Group id." }, "display_name": { "type": "string", "description": "Group name." }, "slug": { "description": "URL name, e.g. `republicans`.", "type": [ "string", "null" ] }, "url": { "description": "Group on truthsocial.com.", "type": [ "string", "null" ] }, "members_count": { "description": "Members.", "type": [ "number", "null" ] } }, "required": [ "id", "display_name", "slug", "url", "members_count" ], "additionalProperties": false }, { "type": "null" } ], "description": "The group it was posted in; null for ordinary posts." }, "mentions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Account id." }, "username": { "type": "string", "description": "Username without @." }, "acct": { "type": "string", "description": "Same as username." }, "url": { "type": "string", "description": "Profile on truthsocial.com." } }, "required": [ "id", "username", "acct", "url" ], "additionalProperties": false }, "description": "Accounts mentioned." }, "tags": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Hashtag without #." }, "url": { "type": "string", "description": "Hashtag page on truthsocial.com." } }, "required": [ "name", "url" ], "additionalProperties": false }, "description": "Hashtags used." }, "account": { "type": "object", "properties": { "id": { "type": "string", "description": "Account id." }, "username": { "type": "string", "description": "Username without @." }, "acct": { "type": "string", "description": "Same as username." }, "display_name": { "type": "string", "description": "Display name." }, "url": { "type": "string", "description": "Profile on truthsocial.com." }, "avatar": { "description": "Profile picture URL; null if none.", "type": [ "string", "null" ] }, "verified": { "type": "boolean", "description": "Has the verified badge." }, "followers_count": { "type": "number", "description": "Followers." } }, "required": [ "id", "username", "acct", "display_name", "url", "avatar", "verified", "followers_count" ], "additionalProperties": false, "description": "The author." } }, "required": [ "id", "created_at", "url", "text", "title", "language", "visibility", "sensitive", "spoiler_text", "in_reply_to_id", "in_reply_to_account_id", "quote_id", "replies_count", "reblogs_count", "favourites_count", "upvotes_count", "downvotes_count", "edited_at", "media_attachments", "card", "group", "mentions", "tags", "account" ], "additionalProperties": false }, { "type": "null" } ], "description": "On a quote post: the quoted post. null otherwise." } }, "required": [ "success", "credits_remaining", "credits_charged", "id", "created_at", "url", "text", "title", "language", "visibility", "sensitive", "spoiler_text", "in_reply_to_id", "in_reply_to_account_id", "quote_id", "replies_count", "reblogs_count", "favourites_count", "upvotes_count", "downvotes_count", "edited_at", "media_attachments", "card", "group", "mentions", "tags", "account", "reblog", "quote" ], "additionalProperties": false } } } }, "403": { "description": "not_public: The platform confirmed this account or content isn't available to logged-out visitors. Use a publicly visible target.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "not_found: The endpoint, or the thing you asked for (ad, post, subreddit), doesn't exist. Charged when the platform was checked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error. Not charged, except the endpoint's own 4xx answers such as not_found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/telegram/channel": { "get": { "operationId": "telegram_channel", "tags": [ "Telegram" ], "summary": "Channel", "description": "A public channel's name, bio, photo, exact subscriber count and media counts.\n\nUse it to size up or track a channel: `subscribers` is exact, straight from the channel's t.me page. `counters` (photos, videos, files, links) are rounded by Telegram.\n\nChannels that turned their web preview off still return their name, bio and subscribers, with `previewEnabled: false` and `counters: null`; their posts can't be read.\n\nUnknown usernames, and usernames that belong to a person, bot or group, return 404 `not_found`.\n\nCost: 1 credit.", "externalDocs": { "url": "https://lurkapi.com/docs/telegram/channel" }, "x-credits": 1, "parameters": [ { "name": "handle", "in": "query", "required": true, "description": "The channel's username, with or without @ (e.g. `telegram`), or its t.me link.", "schema": { "description": "The channel's username, with or without @ (e.g. `telegram`), or its t.me link.", "type": "string" }, "example": "telegram" } ], "responses": { "200": { "description": "A public channel's name, bio, photo, exact subscriber count and media counts.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "const": true, "description": "Always true here; errors have `success: false`." }, "credits_remaining": { "type": "number", "description": "Your balance after this call. On anonymous playground calls: free tries left today." }, "credits_charged": { "type": "number", "description": "Credits this call cost; 0 on free endpoints. On anonymous playground calls: tries used (1)." }, "username": { "type": "string", "description": "Username without @, as the channel writes it, e.g. `telegram`." }, "title": { "type": "string", "description": "Channel name, e.g. \"Telegram News\"." }, "description": { "description": "The channel's bio, plain text; null if empty.", "type": [ "string", "null" ] }, "photoUrl": { "description": "Channel photo URL, temporary; null if none.", "type": [ "string", "null" ] }, "verified": { "type": "boolean", "description": "Has Telegram's verified badge." }, "subscribers": { "description": "Exact subscriber count; null if Telegram doesn't show it.", "type": [ "number", "null" ] }, "counters": { "anyOf": [ { "type": "object", "properties": { "photos": { "description": "Photos posted, as a number. Telegram rounds it (\"1.2K\" → 1200); null if not shown.", "type": [ "number", "null" ] }, "videos": { "description": "Videos posted, as a number. Telegram rounds it (\"1.2K\" → 1200); null if not shown.", "type": [ "number", "null" ] }, "files": { "description": "Files posted, as a number. Telegram rounds it (\"1.2K\" → 1200); null if not shown.", "type": [ "number", "null" ] }, "links": { "description": "Links posted, as a number. Telegram rounds it (\"1.2K\" → 1200); null if not shown.", "type": [ "number", "null" ] } }, "required": [ "photos", "videos", "files", "links" ], "additionalProperties": false }, { "type": "null" } ], "description": "Media counts from the channel's web preview; null when the preview is off." }, "previewEnabled": { "type": "boolean", "description": "The channel's web preview is on, so channel posts and post can read it." }, "url": { "type": "string", "description": "The channel on t.me." } }, "required": [ "success", "credits_remaining", "credits_charged", "username", "title", "description", "photoUrl", "verified", "subscribers", "counters", "previewEnabled", "url" ], "additionalProperties": false } } } }, "404": { "description": "not_found: The endpoint, or the thing you asked for (ad, post, subreddit), doesn't exist. Charged when the platform was checked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error. Not charged, except the endpoint's own 4xx answers such as not_found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/telegram/channel/posts": { "get": { "operationId": "telegram_channel_posts", "tags": [ "Telegram" ], "summary": "Channel posts", "description": "A public channel's latest posts, newest first, with text, views, media, links and reactions.\n\nUse it to monitor what a channel publishes and how far each post reaches. About 20 posts per page, newest first.\n\n**Pagination.** Pass the response's `cursor` back as `cursor` for older posts; it's null at the channel's first post.\n\nUnknown channels return 404 `not_found`. Channels with their web preview off return 403 `not_public`.\n\nCost: 1 credit.", "externalDocs": { "url": "https://lurkapi.com/docs/telegram/channel-posts" }, "x-credits": 1, "parameters": [ { "name": "handle", "in": "query", "required": true, "description": "The channel's username, with or without @ (e.g. `telegram`), or its t.me link.", "schema": { "description": "The channel's username, with or without @ (e.g. `telegram`), or its t.me link.", "type": "string" }, "example": "telegram" }, { "name": "cursor", "in": "query", "required": false, "description": "The `cursor` from the previous response, to get older posts.", "schema": { "description": "The `cursor` from the previous response, to get older posts.", "type": "string", "pattern": "^\\d{1,10}$" } } ], "responses": { "200": { "description": "A public channel's latest posts, newest first, with text, views, media, links and reactions.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "const": true, "description": "Always true here; errors have `success: false`." }, "credits_remaining": { "type": "number", "description": "Your balance after this call. On anonymous playground calls: free tries left today." }, "credits_charged": { "type": "number", "description": "Credits this call cost; 0 on free endpoints. On anonymous playground calls: tries used (1)." }, "posts": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "number", "description": "Post id, unique within the channel. Posts are numbered in order." }, "url": { "type": "string", "description": "The post on t.me, e.g. `https://t.me/telegram/441`." }, "channel": { "type": "string", "description": "The channel's username, e.g. `telegram`." }, "date": { "description": "Posted at, ISO 8601 (UTC).", "type": [ "string", "null" ] }, "text": { "type": "string", "description": "Post text (or media caption), plain, with line breaks. Empty if the post has none." }, "html": { "description": "Post text as HTML: bold, italics, links, quotes. null if the post has no text.", "type": [ "string", "null" ] }, "views": { "description": "View count, as a number. Telegram rounds it (\"1.2K\" → 1200); null if not shown.", "type": [ "number", "null" ] }, "viewsText": { "description": "View count as Telegram shows it, e.g. \"1.56M\"; null if not shown.", "type": [ "string", "null" ] }, "author": { "description": "Author signature, on channels that sign posts; null otherwise.", "type": [ "string", "null" ] }, "edited": { "type": "boolean", "description": "The post was edited after it was published." }, "service": { "type": "boolean", "description": "A service message (\"Channel created\", \"Channel photo updated\"), not a real post." }, "forwardedFrom": { "anyOf": [ { "type": "object", "properties": { "name": { "type": "string", "description": "Name of the channel or person it was forwarded from." }, "url": { "description": "Link to the original post or channel; null for hidden accounts.", "type": [ "string", "null" ] } }, "required": [ "name", "url" ], "additionalProperties": false }, { "type": "null" } ], "description": "Where the post was forwarded from; null if it's original." }, "replyTo": { "anyOf": [ { "type": "object", "properties": { "id": { "description": "Id of the post it replies to; null if the link isn't a post link.", "type": [ "number", "null" ] }, "url": { "type": "string", "description": "Link to the post it replies to." }, "author": { "description": "Name shown on the quoted post.", "type": [ "string", "null" ] }, "text": { "description": "The quoted post's text, shortened by Telegram; null if it has none.", "type": [ "string", "null" ] } }, "required": [ "id", "url", "author", "text" ], "additionalProperties": false }, { "type": "null" } ], "description": "The post this one replies to; null if it isn't a reply." }, "thumbnailUrl": { "description": "A preview image for the post: the first media's thumbnail, else the link preview's image; null if none.", "type": [ "string", "null" ] }, "media": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "photo", "video", "document", "audio", "sticker" ], "description": "`photo`, `video`, `document` (a file), `audio` (a music or podcast file) or `sticker`." }, "url": { "description": "Direct file URL on Telegram's CDN, temporary. null for documents, audio, and videos too big for the web preview (open the post instead).", "type": [ "string", "null" ] }, "thumbnailUrl": { "description": "Preview image URL (the photo itself for photos), temporary; null if none.", "type": [ "string", "null" ] }, "durationS": { "description": "Video length in seconds; null for other media.", "type": [ "number", "null" ] }, "title": { "description": "File name or audio title, for documents and audio; null otherwise.", "type": [ "string", "null" ] } }, "required": [ "type", "url", "thumbnailUrl", "durationS", "title" ], "additionalProperties": false }, "description": "Photos, videos, files and stickers attached to the post, in order. Empty for text posts." }, "linkPreview": { "anyOf": [ { "type": "object", "properties": { "url": { "type": "string", "description": "The linked page." }, "siteName": { "description": "Site name, e.g. \"YouTube\".", "type": [ "string", "null" ] }, "title": { "description": "Page title.", "type": [ "string", "null" ] }, "description": { "description": "Page description.", "type": [ "string", "null" ] }, "imageUrl": { "description": "Preview image URL, temporary; null if none.", "type": [ "string", "null" ] } }, "required": [ "url", "siteName", "title", "description", "imageUrl" ], "additionalProperties": false }, { "type": "null" } ], "description": "The link preview card under the text; null if none." }, "reactions": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "emoji", "custom_emoji", "paid" ], "description": "`emoji`, `custom_emoji` (a Premium emoji) or `paid` (Telegram Stars)." }, "emoji": { "description": "The emoji, e.g. \"👍\"; null for paid reactions and custom emoji without a standard look-alike.", "type": [ "string", "null" ] }, "count": { "type": "number", "description": "How many, as a number. Telegram rounds large counts (\"14.3K\" → 14300)." } }, "required": [ "type", "emoji", "count" ], "additionalProperties": false }, "description": "Reactions in Telegram's order (paid first, then most frequent). Empty if there are none." } }, "required": [ "id", "url", "channel", "date", "text", "html", "views", "viewsText", "author", "edited", "service", "forwardedFrom", "replyTo", "thumbnailUrl", "media", "linkPreview", "reactions" ], "additionalProperties": false }, "description": "One page of posts, newest first." }, "cursor": { "description": "Pass as `cursor` for older posts. null on the last page.", "type": [ "string", "null" ] } }, "required": [ "success", "credits_remaining", "credits_charged", "posts", "cursor" ], "additionalProperties": false } } } }, "403": { "description": "not_public: The platform confirmed this account or content isn't available to logged-out visitors. Use a publicly visible target.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "not_found: The endpoint, or the thing you asked for (ad, post, subreddit), doesn't exist. Charged when the platform was checked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error. Not charged, except the endpoint's own 4xx answers such as not_found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/telegram/post": { "get": { "operationId": "telegram_post", "tags": [ "Telegram" ], "summary": "Post", "description": "One public channel post by link, with text, views, media, links and reactions.\n\nUse it to check one post's reach, or to read a post someone shared. Pass the post's t.me link.\n\nDeleted posts, unknown channels and posts from channels that don't allow embedding return 404 `not_found`.\n\nCost: 1 credit.", "externalDocs": { "url": "https://lurkapi.com/docs/telegram/post" }, "x-credits": 1, "parameters": [ { "name": "url", "in": "query", "required": true, "description": "The post's link, e.g. `https://t.me/telegram/441` (t.me/s/… links work too).", "schema": { "description": "The post's link, e.g. `https://t.me/telegram/441` (t.me/s/… links work too).", "type": "string" }, "example": "https://t.me/telegram/441" } ], "responses": { "200": { "description": "One public channel post by link, with text, views, media, links and reactions.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "const": true, "description": "Always true here; errors have `success: false`." }, "credits_remaining": { "type": "number", "description": "Your balance after this call. On anonymous playground calls: free tries left today." }, "credits_charged": { "type": "number", "description": "Credits this call cost; 0 on free endpoints. On anonymous playground calls: tries used (1)." }, "id": { "type": "number", "description": "Post id, unique within the channel. Posts are numbered in order." }, "url": { "type": "string", "description": "The post on t.me, e.g. `https://t.me/telegram/441`." }, "channel": { "type": "string", "description": "The channel's username, e.g. `telegram`." }, "date": { "description": "Posted at, ISO 8601 (UTC).", "type": [ "string", "null" ] }, "text": { "type": "string", "description": "Post text (or media caption), plain, with line breaks. Empty if the post has none." }, "html": { "description": "Post text as HTML: bold, italics, links, quotes. null if the post has no text.", "type": [ "string", "null" ] }, "views": { "description": "View count, as a number. Telegram rounds it (\"1.2K\" → 1200); null if not shown.", "type": [ "number", "null" ] }, "viewsText": { "description": "View count as Telegram shows it, e.g. \"1.56M\"; null if not shown.", "type": [ "string", "null" ] }, "author": { "description": "Author signature, on channels that sign posts; null otherwise.", "type": [ "string", "null" ] }, "edited": { "type": "boolean", "description": "The post was edited after it was published." }, "service": { "type": "boolean", "description": "A service message (\"Channel created\", \"Channel photo updated\"), not a real post." }, "forwardedFrom": { "anyOf": [ { "type": "object", "properties": { "name": { "type": "string", "description": "Name of the channel or person it was forwarded from." }, "url": { "description": "Link to the original post or channel; null for hidden accounts.", "type": [ "string", "null" ] } }, "required": [ "name", "url" ], "additionalProperties": false }, { "type": "null" } ], "description": "Where the post was forwarded from; null if it's original." }, "replyTo": { "anyOf": [ { "type": "object", "properties": { "id": { "description": "Id of the post it replies to; null if the link isn't a post link.", "type": [ "number", "null" ] }, "url": { "type": "string", "description": "Link to the post it replies to." }, "author": { "description": "Name shown on the quoted post.", "type": [ "string", "null" ] }, "text": { "description": "The quoted post's text, shortened by Telegram; null if it has none.", "type": [ "string", "null" ] } }, "required": [ "id", "url", "author", "text" ], "additionalProperties": false }, { "type": "null" } ], "description": "The post this one replies to; null if it isn't a reply." }, "thumbnailUrl": { "description": "A preview image for the post: the first media's thumbnail, else the link preview's image; null if none.", "type": [ "string", "null" ] }, "media": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "photo", "video", "document", "audio", "sticker" ], "description": "`photo`, `video`, `document` (a file), `audio` (a music or podcast file) or `sticker`." }, "url": { "description": "Direct file URL on Telegram's CDN, temporary. null for documents, audio, and videos too big for the web preview (open the post instead).", "type": [ "string", "null" ] }, "thumbnailUrl": { "description": "Preview image URL (the photo itself for photos), temporary; null if none.", "type": [ "string", "null" ] }, "durationS": { "description": "Video length in seconds; null for other media.", "type": [ "number", "null" ] }, "title": { "description": "File name or audio title, for documents and audio; null otherwise.", "type": [ "string", "null" ] } }, "required": [ "type", "url", "thumbnailUrl", "durationS", "title" ], "additionalProperties": false }, "description": "Photos, videos, files and stickers attached to the post, in order. Empty for text posts." }, "linkPreview": { "anyOf": [ { "type": "object", "properties": { "url": { "type": "string", "description": "The linked page." }, "siteName": { "description": "Site name, e.g. \"YouTube\".", "type": [ "string", "null" ] }, "title": { "description": "Page title.", "type": [ "string", "null" ] }, "description": { "description": "Page description.", "type": [ "string", "null" ] }, "imageUrl": { "description": "Preview image URL, temporary; null if none.", "type": [ "string", "null" ] } }, "required": [ "url", "siteName", "title", "description", "imageUrl" ], "additionalProperties": false }, { "type": "null" } ], "description": "The link preview card under the text; null if none." }, "reactions": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "emoji", "custom_emoji", "paid" ], "description": "`emoji`, `custom_emoji` (a Premium emoji) or `paid` (Telegram Stars)." }, "emoji": { "description": "The emoji, e.g. \"👍\"; null for paid reactions and custom emoji without a standard look-alike.", "type": [ "string", "null" ] }, "count": { "type": "number", "description": "How many, as a number. Telegram rounds large counts (\"14.3K\" → 14300)." } }, "required": [ "type", "emoji", "count" ], "additionalProperties": false }, "description": "Reactions in Telegram's order (paid first, then most frequent). Empty if there are none." } }, "required": [ "success", "credits_remaining", "credits_charged", "id", "url", "channel", "date", "text", "html", "views", "viewsText", "author", "edited", "service", "forwardedFrom", "replyTo", "thumbnailUrl", "media", "linkPreview", "reactions" ], "additionalProperties": false } } } }, "404": { "description": "not_found: The endpoint, or the thing you asked for (ad, post, subreddit), doesn't exist. Charged when the platform was checked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error. Not charged, except the endpoint's own 4xx answers such as not_found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/twitter/tweet": { "get": { "operationId": "twitter_tweet", "tags": [ "X (Twitter)" ], "summary": "Tweet", "description": "One tweet: text, author, likes, replies, reposts, quotes, bookmarks, views, media and the tweet it quotes.\n\nUse it to check how a post performed or to pull its text and media. Pass the tweet's URL (x.com or twitter.com) or its id. Videos come with playable MP4 files in `media[].variants`, best quality first.\n\n`text` is what x.com shows: long posts in full and t.co links expanded. For a retweet, `retweeted_tweet` holds the original; for a quote, `quoted_tweet` holds the quoted tweet. `views` is null on tweets from before 2023.\n\nWhen X's main source is busy we answer from its embed data instead: then `retweets`, `quotes`, `bookmarks`, `views` and `author.followers` are null, and long posts are cut to 280 characters.\n\nDeleted tweets, tweets from protected accounts and age-restricted tweets return 404 `not_found`.\n\nCost: 1 credit.", "externalDocs": { "url": "https://lurkapi.com/docs/twitter/tweet" }, "x-credits": 1, "parameters": [ { "name": "url", "in": "query", "required": true, "description": "The tweet's URL, e.g. `https://x.com/NASA/status/2104593672624886205` (twitter.com links work too), or its numeric id.", "schema": { "description": "The tweet's URL, e.g. `https://x.com/NASA/status/2104593672624886205` (twitter.com links work too), or its numeric id.", "type": "string" }, "example": "https://x.com/NASA/status/2104593672624886205" } ], "responses": { "200": { "description": "One tweet: text, author, likes, replies, reposts, quotes, bookmarks, views, media and the tweet it quotes.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "const": true, "description": "Always true here; errors have `success: false`." }, "credits_remaining": { "type": "number", "description": "Your balance after this call. On anonymous playground calls: free tries left today." }, "credits_charged": { "type": "number", "description": "Credits this call cost; 0 on free endpoints. On anonymous playground calls: tries used (1)." }, "id": { "type": "string", "description": "Tweet id, e.g. `2104593672624886205`." }, "url": { "type": "string", "description": "The tweet on x.com." }, "text": { "type": "string", "description": "The text as x.com shows it: long posts in full, t.co links expanded, without a reply's leading @mentions or the trailing media link. Empty for media-only tweets." }, "created_at": { "type": "string", "description": "When it was posted, ISO 8601." }, "lang": { "description": "Language as X detects it, e.g. `en` (`und` when it can't tell); null if unknown.", "type": [ "string", "null" ] }, "source": { "description": "The app it was posted from, e.g. `Twitter for iPhone`; null if X doesn't say.", "type": [ "string", "null" ] }, "author": { "type": "object", "properties": { "id": { "type": "string", "description": "Numeric user id. It stays the same when the handle changes." }, "handle": { "type": "string", "description": "Username (handle), without @." }, "name": { "type": "string", "description": "Display name." }, "avatar": { "description": "Profile picture URL, 400×400; null if none.", "type": [ "string", "null" ] }, "verified": { "type": "boolean", "description": "Has the blue check (X Premium)." }, "verified_type": { "description": "`Business` (gold check, a verified organization) or `Government` (grey check); null otherwise.", "type": [ "string", "null" ] }, "followers": { "description": "Followers when fetched; null when X's main source was busy and the tweet came from its embed data.", "type": [ "number", "null" ] } }, "required": [ "id", "handle", "name", "avatar", "verified", "verified_type", "followers" ], "additionalProperties": false, "description": "Who posted it." }, "counts": { "type": "object", "properties": { "likes": { "type": "number", "description": "Likes." }, "replies": { "type": "number", "description": "Replies." }, "retweets": { "description": "Reposts (retweets); null when X's main source was busy and the tweet came from its embed data.", "type": [ "number", "null" ] }, "quotes": { "description": "Quote posts; null when X's main source was busy and the tweet came from its embed data.", "type": [ "number", "null" ] }, "bookmarks": { "description": "Bookmarks; null when X's main source was busy and the tweet came from its embed data.", "type": [ "number", "null" ] }, "views": { "description": "Views; null on tweets from before 2023 (X didn't count them then), and null when X's main source was busy and the tweet came from its embed data.", "type": [ "number", "null" ] } }, "required": [ "likes", "replies", "retweets", "quotes", "bookmarks", "views" ], "additionalProperties": false, "description": "Engagement when fetched. Exact numbers, not rounded." }, "media": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "photo", "video", "gif" ], "description": "`photo`, `video` or `gif` (X plays GIFs as silent looping MP4s)." }, "url": { "type": "string", "description": "The image; for videos and GIFs, the poster (thumbnail) image." }, "width": { "type": "number", "description": "Original width in pixels." }, "height": { "type": "number", "description": "Original height in pixels." }, "duration_ms": { "description": "Video length in milliseconds; null for photos and GIFs.", "type": [ "number", "null" ] }, "variants": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string", "description": "File URL on video.twimg.com." }, "content_type": { "type": "string", "description": "`video/mp4`, or `application/x-mpegURL` for the HLS playlist." }, "bitrate": { "description": "Bits per second; null for the HLS playlist.", "type": [ "number", "null" ] } }, "required": [ "url", "content_type", "bitrate" ], "additionalProperties": false }, "description": "Playable files for videos and GIFs: MP4s from highest to lowest bitrate, then the HLS playlist. Empty for photos." } }, "required": [ "type", "url", "width", "height", "duration_ms", "variants" ], "additionalProperties": false }, "description": "Attached photos, videos and GIFs, in order. Empty if none." }, "hashtags": { "type": "array", "items": { "type": "string", "description": "Hashtag without #." }, "description": "Hashtags in the text, without #." }, "mentions": { "type": "array", "items": { "type": "string", "description": "Username without @." }, "description": "Usernames @mentioned, including the ones a reply is addressed to." }, "links": { "type": "array", "items": { "type": "string", "description": "Full URL." }, "description": "Links in the text, expanded (not t.co). The tweet's own photos and videos aren't included." }, "reply_to_id": { "description": "Id of the tweet this replies to; null if it isn't a reply.", "type": [ "string", "null" ] }, "reply_to_handle": { "description": "Username of the account this replies to; null if it isn't a reply.", "type": [ "string", "null" ] }, "conversation_id": { "description": "Id of the thread's first tweet (its own id if it starts one); null if X doesn't say.", "type": [ "string", "null" ] }, "quoted_id": { "description": "Id of the tweet this one quotes; null if it isn't a quote.", "type": [ "string", "null" ] }, "possibly_sensitive": { "type": "boolean", "description": "X marks the media as possibly sensitive." }, "quoted_tweet": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "description": "Tweet id, e.g. `2104593672624886205`." }, "url": { "type": "string", "description": "The tweet on x.com." }, "text": { "type": "string", "description": "The text as x.com shows it: long posts in full, t.co links expanded, without a reply's leading @mentions or the trailing media link. Empty for media-only tweets." }, "created_at": { "type": "string", "description": "When it was posted, ISO 8601." }, "lang": { "description": "Language as X detects it, e.g. `en` (`und` when it can't tell); null if unknown.", "type": [ "string", "null" ] }, "source": { "description": "The app it was posted from, e.g. `Twitter for iPhone`; null if X doesn't say.", "type": [ "string", "null" ] }, "author": { "type": "object", "properties": { "id": { "type": "string", "description": "Numeric user id. It stays the same when the handle changes." }, "handle": { "type": "string", "description": "Username (handle), without @." }, "name": { "type": "string", "description": "Display name." }, "avatar": { "description": "Profile picture URL, 400×400; null if none.", "type": [ "string", "null" ] }, "verified": { "type": "boolean", "description": "Has the blue check (X Premium)." }, "verified_type": { "description": "`Business` (gold check, a verified organization) or `Government` (grey check); null otherwise.", "type": [ "string", "null" ] }, "followers": { "description": "Followers when fetched; null when X's main source was busy and the tweet came from its embed data.", "type": [ "number", "null" ] } }, "required": [ "id", "handle", "name", "avatar", "verified", "verified_type", "followers" ], "additionalProperties": false, "description": "Who posted it." }, "counts": { "type": "object", "properties": { "likes": { "type": "number", "description": "Likes." }, "replies": { "type": "number", "description": "Replies." }, "retweets": { "description": "Reposts (retweets); null when X's main source was busy and the tweet came from its embed data.", "type": [ "number", "null" ] }, "quotes": { "description": "Quote posts; null when X's main source was busy and the tweet came from its embed data.", "type": [ "number", "null" ] }, "bookmarks": { "description": "Bookmarks; null when X's main source was busy and the tweet came from its embed data.", "type": [ "number", "null" ] }, "views": { "description": "Views; null on tweets from before 2023 (X didn't count them then), and null when X's main source was busy and the tweet came from its embed data.", "type": [ "number", "null" ] } }, "required": [ "likes", "replies", "retweets", "quotes", "bookmarks", "views" ], "additionalProperties": false, "description": "Engagement when fetched. Exact numbers, not rounded." }, "media": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "photo", "video", "gif" ], "description": "`photo`, `video` or `gif` (X plays GIFs as silent looping MP4s)." }, "url": { "type": "string", "description": "The image; for videos and GIFs, the poster (thumbnail) image." }, "width": { "type": "number", "description": "Original width in pixels." }, "height": { "type": "number", "description": "Original height in pixels." }, "duration_ms": { "description": "Video length in milliseconds; null for photos and GIFs.", "type": [ "number", "null" ] }, "variants": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string", "description": "File URL on video.twimg.com." }, "content_type": { "type": "string", "description": "`video/mp4`, or `application/x-mpegURL` for the HLS playlist." }, "bitrate": { "description": "Bits per second; null for the HLS playlist.", "type": [ "number", "null" ] } }, "required": [ "url", "content_type", "bitrate" ], "additionalProperties": false }, "description": "Playable files for videos and GIFs: MP4s from highest to lowest bitrate, then the HLS playlist. Empty for photos." } }, "required": [ "type", "url", "width", "height", "duration_ms", "variants" ], "additionalProperties": false }, "description": "Attached photos, videos and GIFs, in order. Empty if none." }, "hashtags": { "type": "array", "items": { "type": "string", "description": "Hashtag without #." }, "description": "Hashtags in the text, without #." }, "mentions": { "type": "array", "items": { "type": "string", "description": "Username without @." }, "description": "Usernames @mentioned, including the ones a reply is addressed to." }, "links": { "type": "array", "items": { "type": "string", "description": "Full URL." }, "description": "Links in the text, expanded (not t.co). The tweet's own photos and videos aren't included." }, "reply_to_id": { "description": "Id of the tweet this replies to; null if it isn't a reply.", "type": [ "string", "null" ] }, "reply_to_handle": { "description": "Username of the account this replies to; null if it isn't a reply.", "type": [ "string", "null" ] }, "conversation_id": { "description": "Id of the thread's first tweet (its own id if it starts one); null if X doesn't say.", "type": [ "string", "null" ] }, "quoted_id": { "description": "Id of the tweet this one quotes; null if it isn't a quote.", "type": [ "string", "null" ] }, "possibly_sensitive": { "type": "boolean", "description": "X marks the media as possibly sensitive." } }, "required": [ "id", "url", "text", "created_at", "lang", "source", "author", "counts", "media", "hashtags", "mentions", "links", "reply_to_id", "reply_to_handle", "conversation_id", "quoted_id", "possibly_sensitive" ], "additionalProperties": false }, { "type": "null" } ], "description": "The tweet this one quotes (without its own quoted or retweeted tweet); null if none or it's no longer available." }, "retweeted_tweet": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "description": "Tweet id, e.g. `2104593672624886205`." }, "url": { "type": "string", "description": "The tweet on x.com." }, "text": { "type": "string", "description": "The text as x.com shows it: long posts in full, t.co links expanded, without a reply's leading @mentions or the trailing media link. Empty for media-only tweets." }, "created_at": { "type": "string", "description": "When it was posted, ISO 8601." }, "lang": { "description": "Language as X detects it, e.g. `en` (`und` when it can't tell); null if unknown.", "type": [ "string", "null" ] }, "source": { "description": "The app it was posted from, e.g. `Twitter for iPhone`; null if X doesn't say.", "type": [ "string", "null" ] }, "author": { "type": "object", "properties": { "id": { "type": "string", "description": "Numeric user id. It stays the same when the handle changes." }, "handle": { "type": "string", "description": "Username (handle), without @." }, "name": { "type": "string", "description": "Display name." }, "avatar": { "description": "Profile picture URL, 400×400; null if none.", "type": [ "string", "null" ] }, "verified": { "type": "boolean", "description": "Has the blue check (X Premium)." }, "verified_type": { "description": "`Business` (gold check, a verified organization) or `Government` (grey check); null otherwise.", "type": [ "string", "null" ] }, "followers": { "description": "Followers when fetched; null when X's main source was busy and the tweet came from its embed data.", "type": [ "number", "null" ] } }, "required": [ "id", "handle", "name", "avatar", "verified", "verified_type", "followers" ], "additionalProperties": false, "description": "Who posted it." }, "counts": { "type": "object", "properties": { "likes": { "type": "number", "description": "Likes." }, "replies": { "type": "number", "description": "Replies." }, "retweets": { "description": "Reposts (retweets); null when X's main source was busy and the tweet came from its embed data.", "type": [ "number", "null" ] }, "quotes": { "description": "Quote posts; null when X's main source was busy and the tweet came from its embed data.", "type": [ "number", "null" ] }, "bookmarks": { "description": "Bookmarks; null when X's main source was busy and the tweet came from its embed data.", "type": [ "number", "null" ] }, "views": { "description": "Views; null on tweets from before 2023 (X didn't count them then), and null when X's main source was busy and the tweet came from its embed data.", "type": [ "number", "null" ] } }, "required": [ "likes", "replies", "retweets", "quotes", "bookmarks", "views" ], "additionalProperties": false, "description": "Engagement when fetched. Exact numbers, not rounded." }, "media": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "photo", "video", "gif" ], "description": "`photo`, `video` or `gif` (X plays GIFs as silent looping MP4s)." }, "url": { "type": "string", "description": "The image; for videos and GIFs, the poster (thumbnail) image." }, "width": { "type": "number", "description": "Original width in pixels." }, "height": { "type": "number", "description": "Original height in pixels." }, "duration_ms": { "description": "Video length in milliseconds; null for photos and GIFs.", "type": [ "number", "null" ] }, "variants": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string", "description": "File URL on video.twimg.com." }, "content_type": { "type": "string", "description": "`video/mp4`, or `application/x-mpegURL` for the HLS playlist." }, "bitrate": { "description": "Bits per second; null for the HLS playlist.", "type": [ "number", "null" ] } }, "required": [ "url", "content_type", "bitrate" ], "additionalProperties": false }, "description": "Playable files for videos and GIFs: MP4s from highest to lowest bitrate, then the HLS playlist. Empty for photos." } }, "required": [ "type", "url", "width", "height", "duration_ms", "variants" ], "additionalProperties": false }, "description": "Attached photos, videos and GIFs, in order. Empty if none." }, "hashtags": { "type": "array", "items": { "type": "string", "description": "Hashtag without #." }, "description": "Hashtags in the text, without #." }, "mentions": { "type": "array", "items": { "type": "string", "description": "Username without @." }, "description": "Usernames @mentioned, including the ones a reply is addressed to." }, "links": { "type": "array", "items": { "type": "string", "description": "Full URL." }, "description": "Links in the text, expanded (not t.co). The tweet's own photos and videos aren't included." }, "reply_to_id": { "description": "Id of the tweet this replies to; null if it isn't a reply.", "type": [ "string", "null" ] }, "reply_to_handle": { "description": "Username of the account this replies to; null if it isn't a reply.", "type": [ "string", "null" ] }, "conversation_id": { "description": "Id of the thread's first tweet (its own id if it starts one); null if X doesn't say.", "type": [ "string", "null" ] }, "quoted_id": { "description": "Id of the tweet this one quotes; null if it isn't a quote.", "type": [ "string", "null" ] }, "possibly_sensitive": { "type": "boolean", "description": "X marks the media as possibly sensitive." } }, "required": [ "id", "url", "text", "created_at", "lang", "source", "author", "counts", "media", "hashtags", "mentions", "links", "reply_to_id", "reply_to_handle", "conversation_id", "quoted_id", "possibly_sensitive" ], "additionalProperties": false }, { "type": "null" } ], "description": "For retweets: the original tweet, with its own text and counts. null for everything else." } }, "required": [ "success", "credits_remaining", "credits_charged", "id", "url", "text", "created_at", "lang", "source", "author", "counts", "media", "hashtags", "mentions", "links", "reply_to_id", "reply_to_handle", "conversation_id", "quoted_id", "possibly_sensitive", "quoted_tweet", "retweeted_tweet" ], "additionalProperties": false } } } }, "404": { "description": "not_found: The endpoint, or the thing you asked for (ad, post, subreddit), doesn't exist. Charged when the platform was checked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error. Not charged, except the endpoint's own 4xx answers such as not_found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/twitter/profile": { "get": { "operationId": "twitter_profile", "tags": [ "X (Twitter)" ], "summary": "Profile", "description": "An account's bio, avatar, verification and exact follower, following, tweet and like counts.\n\nUse it to size up an account: followers, following, tweets and likes as exact numbers, plus bio, website, location, join date and verification. `verified` is the blue check; `verified_type` shows gold (`Business`) and grey (`Government`) checks. Pass a `pinned_tweet_ids` entry to the tweet endpoint for the pinned tweet.\n\nProtected accounts return their profile with `protected: true`. Unknown and suspended accounts return 404 `not_found`.\n\nCost: 1 credit.", "externalDocs": { "url": "https://lurkapi.com/docs/twitter/profile" }, "x-credits": 1, "parameters": [ { "name": "handle", "in": "query", "required": true, "description": "X username, with or without @ (e.g. `NASA`), or the profile URL.", "schema": { "description": "X username, with or without @ (e.g. `NASA`), or the profile URL.", "type": "string" }, "example": "NASA" } ], "responses": { "200": { "description": "An account's bio, avatar, verification and exact follower, following, tweet and like counts.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "const": true, "description": "Always true here; errors have `success: false`." }, "credits_remaining": { "type": "number", "description": "Your balance after this call. On anonymous playground calls: free tries left today." }, "credits_charged": { "type": "number", "description": "Credits this call cost; 0 on free endpoints. On anonymous playground calls: tries used (1)." }, "id": { "type": "string", "description": "Numeric user id. It stays the same when the handle changes." }, "handle": { "type": "string", "description": "Username (handle), without @, with X's capitalization." }, "name": { "type": "string", "description": "Display name." }, "bio": { "type": "string", "description": "Bio text, t.co links expanded. Empty if none." }, "location": { "description": "Location as the account wrote it (free text); null if none.", "type": [ "string", "null" ] }, "website": { "description": "The website link on the profile, expanded; null if none.", "type": [ "string", "null" ] }, "avatar": { "description": "Profile picture URL, 400×400; null if none.", "type": [ "string", "null" ] }, "banner": { "description": "Header image URL; null if none.", "type": [ "string", "null" ] }, "verified": { "type": "boolean", "description": "Has the blue check (X Premium)." }, "verified_type": { "description": "`Business` (gold check, a verified organization) or `Government` (grey check); null otherwise.", "type": [ "string", "null" ] }, "created_at": { "type": "string", "description": "When the account was created, ISO 8601." }, "followers": { "type": "number", "description": "Followers, exact." }, "following": { "type": "number", "description": "Accounts they follow." }, "tweets": { "type": "number", "description": "Tweets posted, replies and retweets included." }, "media_count": { "type": "number", "description": "Tweets with photos or videos." }, "likes": { "type": "number", "description": "Tweets they liked." }, "pinned_tweet_ids": { "type": "array", "items": { "type": "string", "description": "Tweet id." }, "description": "Ids of the pinned tweet(s); pass one to the tweet endpoint. Empty if none." }, "protected": { "type": "boolean", "description": "A protected (private) account: only approved followers see its tweets." }, "professional_type": { "description": "`Creator` or `Business` for professional accounts; null for personal ones.", "type": [ "string", "null" ] } }, "required": [ "success", "credits_remaining", "credits_charged", "id", "handle", "name", "bio", "location", "website", "avatar", "banner", "verified", "verified_type", "created_at", "followers", "following", "tweets", "media_count", "likes", "pinned_tweet_ids", "protected", "professional_type" ], "additionalProperties": false } } } }, "404": { "description": "not_found: The endpoint, or the thing you asked for (ad, post, subreddit), doesn't exist. Charged when the platform was checked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error. Not charged, except the endpoint's own 4xx answers such as not_found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/twitter/user-tweets": { "get": { "operationId": "twitter_user_tweets", "tags": [ "X (Twitter)" ], "summary": "User tweets", "description": "An account's tweets and retweets, about 20 per page, with text, media and engagement counts.\n\nUse it to audit what an account posts and how each post does. Retweets are included (the original is in `retweeted_tweet`); replies aren't, except the account's own threads. On the first page the pinned tweet comes first, with `pinned: true`.\n\n**Ordering.** Check `ordering`. For most accounts it's `chronological`: newest first, with more pages. For some very large accounts X shows logged-out visitors only a `ranked` sample instead: about 100 popular tweets from all years, in X's order, with no next page.\n\n**Pagination.** Pass the response's `cursor` back as `cursor` (with the same `handle`) for older tweets; it's null at the end.\n\nUnknown and suspended accounts return 404 `not_found`, and so do protected accounts, whose tweets need a login.\n\nCost: 1 credit.", "externalDocs": { "url": "https://lurkapi.com/docs/twitter/user-tweets" }, "x-credits": 1, "parameters": [ { "name": "handle", "in": "query", "required": true, "description": "X username, with or without @ (e.g. `NASA`), or the profile URL.", "schema": { "description": "X username, with or without @ (e.g. `NASA`), or the profile URL.", "type": "string" }, "example": "NASA" }, { "name": "cursor", "in": "query", "required": false, "description": "The `cursor` from the previous response, to get older tweets.", "schema": { "description": "The `cursor` from the previous response, to get older tweets.", "type": "string", "minLength": 1 } } ], "responses": { "200": { "description": "An account's tweets and retweets, about 20 per page, with text, media and engagement counts.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "const": true, "description": "Always true here; errors have `success: false`." }, "credits_remaining": { "type": "number", "description": "Your balance after this call. On anonymous playground calls: free tries left today." }, "credits_charged": { "type": "number", "description": "Credits this call cost; 0 on free endpoints. On anonymous playground calls: tries used (1)." }, "tweets": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Tweet id, e.g. `2104593672624886205`." }, "url": { "type": "string", "description": "The tweet on x.com." }, "text": { "type": "string", "description": "The text as x.com shows it: long posts in full, t.co links expanded, without a reply's leading @mentions or the trailing media link. Empty for media-only tweets." }, "created_at": { "type": "string", "description": "When it was posted, ISO 8601." }, "lang": { "description": "Language as X detects it, e.g. `en` (`und` when it can't tell); null if unknown.", "type": [ "string", "null" ] }, "source": { "description": "The app it was posted from, e.g. `Twitter for iPhone`; null if X doesn't say.", "type": [ "string", "null" ] }, "author": { "type": "object", "properties": { "id": { "type": "string", "description": "Numeric user id. It stays the same when the handle changes." }, "handle": { "type": "string", "description": "Username (handle), without @." }, "name": { "type": "string", "description": "Display name." }, "avatar": { "description": "Profile picture URL, 400×400; null if none.", "type": [ "string", "null" ] }, "verified": { "type": "boolean", "description": "Has the blue check (X Premium)." }, "verified_type": { "description": "`Business` (gold check, a verified organization) or `Government` (grey check); null otherwise.", "type": [ "string", "null" ] }, "followers": { "description": "Followers when fetched; null when X's main source was busy and the tweet came from its embed data.", "type": [ "number", "null" ] } }, "required": [ "id", "handle", "name", "avatar", "verified", "verified_type", "followers" ], "additionalProperties": false, "description": "Who posted it." }, "counts": { "type": "object", "properties": { "likes": { "type": "number", "description": "Likes." }, "replies": { "type": "number", "description": "Replies." }, "retweets": { "description": "Reposts (retweets); null when X's main source was busy and the tweet came from its embed data.", "type": [ "number", "null" ] }, "quotes": { "description": "Quote posts; null when X's main source was busy and the tweet came from its embed data.", "type": [ "number", "null" ] }, "bookmarks": { "description": "Bookmarks; null when X's main source was busy and the tweet came from its embed data.", "type": [ "number", "null" ] }, "views": { "description": "Views; null on tweets from before 2023 (X didn't count them then), and null when X's main source was busy and the tweet came from its embed data.", "type": [ "number", "null" ] } }, "required": [ "likes", "replies", "retweets", "quotes", "bookmarks", "views" ], "additionalProperties": false, "description": "Engagement when fetched. Exact numbers, not rounded." }, "media": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "photo", "video", "gif" ], "description": "`photo`, `video` or `gif` (X plays GIFs as silent looping MP4s)." }, "url": { "type": "string", "description": "The image; for videos and GIFs, the poster (thumbnail) image." }, "width": { "type": "number", "description": "Original width in pixels." }, "height": { "type": "number", "description": "Original height in pixels." }, "duration_ms": { "description": "Video length in milliseconds; null for photos and GIFs.", "type": [ "number", "null" ] }, "variants": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string", "description": "File URL on video.twimg.com." }, "content_type": { "type": "string", "description": "`video/mp4`, or `application/x-mpegURL` for the HLS playlist." }, "bitrate": { "description": "Bits per second; null for the HLS playlist.", "type": [ "number", "null" ] } }, "required": [ "url", "content_type", "bitrate" ], "additionalProperties": false }, "description": "Playable files for videos and GIFs: MP4s from highest to lowest bitrate, then the HLS playlist. Empty for photos." } }, "required": [ "type", "url", "width", "height", "duration_ms", "variants" ], "additionalProperties": false }, "description": "Attached photos, videos and GIFs, in order. Empty if none." }, "hashtags": { "type": "array", "items": { "type": "string", "description": "Hashtag without #." }, "description": "Hashtags in the text, without #." }, "mentions": { "type": "array", "items": { "type": "string", "description": "Username without @." }, "description": "Usernames @mentioned, including the ones a reply is addressed to." }, "links": { "type": "array", "items": { "type": "string", "description": "Full URL." }, "description": "Links in the text, expanded (not t.co). The tweet's own photos and videos aren't included." }, "reply_to_id": { "description": "Id of the tweet this replies to; null if it isn't a reply.", "type": [ "string", "null" ] }, "reply_to_handle": { "description": "Username of the account this replies to; null if it isn't a reply.", "type": [ "string", "null" ] }, "conversation_id": { "description": "Id of the thread's first tweet (its own id if it starts one); null if X doesn't say.", "type": [ "string", "null" ] }, "quoted_id": { "description": "Id of the tweet this one quotes; null if it isn't a quote.", "type": [ "string", "null" ] }, "possibly_sensitive": { "type": "boolean", "description": "X marks the media as possibly sensitive." }, "quoted_tweet": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "description": "Tweet id, e.g. `2104593672624886205`." }, "url": { "type": "string", "description": "The tweet on x.com." }, "text": { "type": "string", "description": "The text as x.com shows it: long posts in full, t.co links expanded, without a reply's leading @mentions or the trailing media link. Empty for media-only tweets." }, "created_at": { "type": "string", "description": "When it was posted, ISO 8601." }, "lang": { "description": "Language as X detects it, e.g. `en` (`und` when it can't tell); null if unknown.", "type": [ "string", "null" ] }, "source": { "description": "The app it was posted from, e.g. `Twitter for iPhone`; null if X doesn't say.", "type": [ "string", "null" ] }, "author": { "type": "object", "properties": { "id": { "type": "string", "description": "Numeric user id. It stays the same when the handle changes." }, "handle": { "type": "string", "description": "Username (handle), without @." }, "name": { "type": "string", "description": "Display name." }, "avatar": { "description": "Profile picture URL, 400×400; null if none.", "type": [ "string", "null" ] }, "verified": { "type": "boolean", "description": "Has the blue check (X Premium)." }, "verified_type": { "description": "`Business` (gold check, a verified organization) or `Government` (grey check); null otherwise.", "type": [ "string", "null" ] }, "followers": { "description": "Followers when fetched; null when X's main source was busy and the tweet came from its embed data.", "type": [ "number", "null" ] } }, "required": [ "id", "handle", "name", "avatar", "verified", "verified_type", "followers" ], "additionalProperties": false, "description": "Who posted it." }, "counts": { "type": "object", "properties": { "likes": { "type": "number", "description": "Likes." }, "replies": { "type": "number", "description": "Replies." }, "retweets": { "description": "Reposts (retweets); null when X's main source was busy and the tweet came from its embed data.", "type": [ "number", "null" ] }, "quotes": { "description": "Quote posts; null when X's main source was busy and the tweet came from its embed data.", "type": [ "number", "null" ] }, "bookmarks": { "description": "Bookmarks; null when X's main source was busy and the tweet came from its embed data.", "type": [ "number", "null" ] }, "views": { "description": "Views; null on tweets from before 2023 (X didn't count them then), and null when X's main source was busy and the tweet came from its embed data.", "type": [ "number", "null" ] } }, "required": [ "likes", "replies", "retweets", "quotes", "bookmarks", "views" ], "additionalProperties": false, "description": "Engagement when fetched. Exact numbers, not rounded." }, "media": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "photo", "video", "gif" ], "description": "`photo`, `video` or `gif` (X plays GIFs as silent looping MP4s)." }, "url": { "type": "string", "description": "The image; for videos and GIFs, the poster (thumbnail) image." }, "width": { "type": "number", "description": "Original width in pixels." }, "height": { "type": "number", "description": "Original height in pixels." }, "duration_ms": { "description": "Video length in milliseconds; null for photos and GIFs.", "type": [ "number", "null" ] }, "variants": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string", "description": "File URL on video.twimg.com." }, "content_type": { "type": "string", "description": "`video/mp4`, or `application/x-mpegURL` for the HLS playlist." }, "bitrate": { "description": "Bits per second; null for the HLS playlist.", "type": [ "number", "null" ] } }, "required": [ "url", "content_type", "bitrate" ], "additionalProperties": false }, "description": "Playable files for videos and GIFs: MP4s from highest to lowest bitrate, then the HLS playlist. Empty for photos." } }, "required": [ "type", "url", "width", "height", "duration_ms", "variants" ], "additionalProperties": false }, "description": "Attached photos, videos and GIFs, in order. Empty if none." }, "hashtags": { "type": "array", "items": { "type": "string", "description": "Hashtag without #." }, "description": "Hashtags in the text, without #." }, "mentions": { "type": "array", "items": { "type": "string", "description": "Username without @." }, "description": "Usernames @mentioned, including the ones a reply is addressed to." }, "links": { "type": "array", "items": { "type": "string", "description": "Full URL." }, "description": "Links in the text, expanded (not t.co). The tweet's own photos and videos aren't included." }, "reply_to_id": { "description": "Id of the tweet this replies to; null if it isn't a reply.", "type": [ "string", "null" ] }, "reply_to_handle": { "description": "Username of the account this replies to; null if it isn't a reply.", "type": [ "string", "null" ] }, "conversation_id": { "description": "Id of the thread's first tweet (its own id if it starts one); null if X doesn't say.", "type": [ "string", "null" ] }, "quoted_id": { "description": "Id of the tweet this one quotes; null if it isn't a quote.", "type": [ "string", "null" ] }, "possibly_sensitive": { "type": "boolean", "description": "X marks the media as possibly sensitive." } }, "required": [ "id", "url", "text", "created_at", "lang", "source", "author", "counts", "media", "hashtags", "mentions", "links", "reply_to_id", "reply_to_handle", "conversation_id", "quoted_id", "possibly_sensitive" ], "additionalProperties": false }, { "type": "null" } ], "description": "The tweet this one quotes (without its own quoted or retweeted tweet); null if none or it's no longer available." }, "retweeted_tweet": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "description": "Tweet id, e.g. `2104593672624886205`." }, "url": { "type": "string", "description": "The tweet on x.com." }, "text": { "type": "string", "description": "The text as x.com shows it: long posts in full, t.co links expanded, without a reply's leading @mentions or the trailing media link. Empty for media-only tweets." }, "created_at": { "type": "string", "description": "When it was posted, ISO 8601." }, "lang": { "description": "Language as X detects it, e.g. `en` (`und` when it can't tell); null if unknown.", "type": [ "string", "null" ] }, "source": { "description": "The app it was posted from, e.g. `Twitter for iPhone`; null if X doesn't say.", "type": [ "string", "null" ] }, "author": { "type": "object", "properties": { "id": { "type": "string", "description": "Numeric user id. It stays the same when the handle changes." }, "handle": { "type": "string", "description": "Username (handle), without @." }, "name": { "type": "string", "description": "Display name." }, "avatar": { "description": "Profile picture URL, 400×400; null if none.", "type": [ "string", "null" ] }, "verified": { "type": "boolean", "description": "Has the blue check (X Premium)." }, "verified_type": { "description": "`Business` (gold check, a verified organization) or `Government` (grey check); null otherwise.", "type": [ "string", "null" ] }, "followers": { "description": "Followers when fetched; null when X's main source was busy and the tweet came from its embed data.", "type": [ "number", "null" ] } }, "required": [ "id", "handle", "name", "avatar", "verified", "verified_type", "followers" ], "additionalProperties": false, "description": "Who posted it." }, "counts": { "type": "object", "properties": { "likes": { "type": "number", "description": "Likes." }, "replies": { "type": "number", "description": "Replies." }, "retweets": { "description": "Reposts (retweets); null when X's main source was busy and the tweet came from its embed data.", "type": [ "number", "null" ] }, "quotes": { "description": "Quote posts; null when X's main source was busy and the tweet came from its embed data.", "type": [ "number", "null" ] }, "bookmarks": { "description": "Bookmarks; null when X's main source was busy and the tweet came from its embed data.", "type": [ "number", "null" ] }, "views": { "description": "Views; null on tweets from before 2023 (X didn't count them then), and null when X's main source was busy and the tweet came from its embed data.", "type": [ "number", "null" ] } }, "required": [ "likes", "replies", "retweets", "quotes", "bookmarks", "views" ], "additionalProperties": false, "description": "Engagement when fetched. Exact numbers, not rounded." }, "media": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "photo", "video", "gif" ], "description": "`photo`, `video` or `gif` (X plays GIFs as silent looping MP4s)." }, "url": { "type": "string", "description": "The image; for videos and GIFs, the poster (thumbnail) image." }, "width": { "type": "number", "description": "Original width in pixels." }, "height": { "type": "number", "description": "Original height in pixels." }, "duration_ms": { "description": "Video length in milliseconds; null for photos and GIFs.", "type": [ "number", "null" ] }, "variants": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string", "description": "File URL on video.twimg.com." }, "content_type": { "type": "string", "description": "`video/mp4`, or `application/x-mpegURL` for the HLS playlist." }, "bitrate": { "description": "Bits per second; null for the HLS playlist.", "type": [ "number", "null" ] } }, "required": [ "url", "content_type", "bitrate" ], "additionalProperties": false }, "description": "Playable files for videos and GIFs: MP4s from highest to lowest bitrate, then the HLS playlist. Empty for photos." } }, "required": [ "type", "url", "width", "height", "duration_ms", "variants" ], "additionalProperties": false }, "description": "Attached photos, videos and GIFs, in order. Empty if none." }, "hashtags": { "type": "array", "items": { "type": "string", "description": "Hashtag without #." }, "description": "Hashtags in the text, without #." }, "mentions": { "type": "array", "items": { "type": "string", "description": "Username without @." }, "description": "Usernames @mentioned, including the ones a reply is addressed to." }, "links": { "type": "array", "items": { "type": "string", "description": "Full URL." }, "description": "Links in the text, expanded (not t.co). The tweet's own photos and videos aren't included." }, "reply_to_id": { "description": "Id of the tweet this replies to; null if it isn't a reply.", "type": [ "string", "null" ] }, "reply_to_handle": { "description": "Username of the account this replies to; null if it isn't a reply.", "type": [ "string", "null" ] }, "conversation_id": { "description": "Id of the thread's first tweet (its own id if it starts one); null if X doesn't say.", "type": [ "string", "null" ] }, "quoted_id": { "description": "Id of the tweet this one quotes; null if it isn't a quote.", "type": [ "string", "null" ] }, "possibly_sensitive": { "type": "boolean", "description": "X marks the media as possibly sensitive." } }, "required": [ "id", "url", "text", "created_at", "lang", "source", "author", "counts", "media", "hashtags", "mentions", "links", "reply_to_id", "reply_to_handle", "conversation_id", "quoted_id", "possibly_sensitive" ], "additionalProperties": false }, { "type": "null" } ], "description": "For retweets: the original tweet, with its own text and counts. null for everything else." }, "pinned": { "type": "boolean", "description": "The account's pinned tweet, shown first." } }, "required": [ "id", "url", "text", "created_at", "lang", "source", "author", "counts", "media", "hashtags", "mentions", "links", "reply_to_id", "reply_to_handle", "conversation_id", "quoted_id", "possibly_sensitive", "quoted_tweet", "retweeted_tweet", "pinned" ], "additionalProperties": false }, "description": "One page of tweets and retweets, in `ordering` order." }, "cursor": { "description": "Pass as `cursor` for the next page; null on the last page and for `ranked` results.", "type": [ "string", "null" ] }, "ordering": { "type": "string", "enum": [ "chronological", "ranked" ], "description": "`chronological`: newest first, with more pages. `ranked`: X shows logged-out visitors of this very large account only about 100 popular tweets from all years, with no next page." } }, "required": [ "success", "credits_remaining", "credits_charged", "tweets", "cursor", "ordering" ], "additionalProperties": false } } } }, "404": { "description": "not_found: The endpoint, or the thing you asked for (ad, post, subreddit), doesn't exist. Charged when the platform was checked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error. Not charged, except the endpoint's own 4xx answers such as not_found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/threads/profile": { "get": { "operationId": "threads_profile", "tags": [ "Threads" ], "summary": "Threads profile", "description": "Public profile biography, links, follower count and account metadata.\n\nGet the public metadata of a Threads account. A private account can still expose profile metadata: check `is_private` before requesting posts. A login wall or incomplete upstream page produces an upstream error rather than a false not-found response.\n\nCost: 1 credit.", "externalDocs": { "url": "https://lurkapi.com/docs/threads/profile" }, "x-credits": 1, "parameters": [ { "name": "handle", "in": "query", "required": true, "description": "Threads username, with or without @, or its threads.com / threads.net profile URL.", "schema": { "description": "Threads username, with or without @, or its threads.com / threads.net profile URL.", "type": "string" }, "example": "zuck" } ], "responses": { "200": { "description": "Public profile biography, links, follower count and account metadata.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "const": true, "description": "Always true here; errors have `success: false`." }, "credits_remaining": { "type": "number", "description": "Your balance after this call. On anonymous playground calls: free tries left today." }, "credits_charged": { "type": "number", "description": "Credits this call cost; 0 on free endpoints. On anonymous playground calls: tries used (1)." }, "id": { "type": "string", "description": "Numeric Threads account id, returned as a string." }, "username": { "type": "string", "description": "Account username without @." }, "name": { "description": "Public display name; null when unknown.", "type": [ "string", "null" ] }, "biography": { "description": "Public profile biography; null when omitted.", "type": [ "string", "null" ] }, "followers_count": { "description": "Public follower count when fetched; null when omitted.", "type": [ "number", "null" ] }, "is_verified": { "description": "Whether the profile has a verified badge; null when unknown.", "type": [ "boolean", "null" ] }, "is_private": { "description": "Whether Threads explicitly marks the profile private; null when it does not say.", "type": [ "boolean", "null" ] }, "profile_pic_url": { "description": "Largest public profile picture URL; null when omitted.", "type": [ "string", "null" ] }, "bio_links": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string", "description": "Public destination URL linked in the biography." }, "title": { "description": "Link title supplied by Threads; null when omitted.", "type": [ "string", "null" ] } }, "required": [ "url", "title" ], "additionalProperties": false }, "description": "Public links in the biography, in source order." }, "url": { "type": "string", "description": "Canonical Threads profile URL." } }, "required": [ "success", "credits_remaining", "credits_charged", "id", "username", "name", "biography", "followers_count", "is_verified", "is_private", "profile_pic_url", "bio_links", "url" ], "additionalProperties": false } } } }, "404": { "description": "not_found: The endpoint, or the thing you asked for (ad, post, subreddit), doesn't exist. Charged when the platform was checked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error. Not charged, except the endpoint's own 4xx answers such as not_found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/threads/user/posts": { "get": { "operationId": "threads_user_posts", "tags": [ "Threads" ], "summary": "Threads account posts", "description": "One page of a public account's Threads posts, with text, media and engagement.\n\nRead the account's public posts in the feed order returned by Threads, including linked self replies. `count` counts feed groups, so the number of individual posts can be larger. Pinned posts may appear ahead of newer posts. Pass `next_cursor` back as `cursor` with the same handle to continue; null means the end. Private accounts return 403 `not_public`. Login walls and incomplete responses are upstream errors, never empty success pages.\n\nCost: 1 credit.", "externalDocs": { "url": "https://lurkapi.com/docs/threads/user-posts" }, "x-credits": 1, "parameters": [ { "name": "handle", "in": "query", "required": true, "description": "Threads username, with or without @, or its threads.com / threads.net profile URL.", "schema": { "description": "Threads username, with or without @, or its threads.com / threads.net profile URL.", "type": "string" }, "example": "zuck" }, { "name": "cursor", "in": "query", "required": false, "description": "Opaque `next_cursor` from the previous response. Keep the same handle when continuing.", "schema": { "description": "Opaque `next_cursor` from the previous response. Keep the same handle when continuing.", "type": "string", "minLength": 1, "maxLength": 2048 } }, { "name": "count", "in": "query", "required": false, "description": "Number of feed groups to request, from 1 to 20; default 10. A linked thread can contain multiple posts.", "schema": { "default": 10, "description": "Number of feed groups to request, from 1 to 20; default 10. A linked thread can contain multiple posts.", "type": "integer", "minimum": 1, "maximum": 20 } } ], "responses": { "200": { "description": "One page of a public account's Threads posts, with text, media and engagement.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "const": true, "description": "Always true here; errors have `success: false`." }, "credits_remaining": { "type": "number", "description": "Your balance after this call. On anonymous playground calls: free tries left today." }, "credits_charged": { "type": "number", "description": "Credits this call cost; 0 on free endpoints. On anonymous playground calls: tries used (1)." }, "posts": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Numeric Threads post id, returned as a string." }, "code": { "type": "string", "description": "Post shortcode used in its public URL." }, "url": { "type": "string", "description": "Canonical public post URL on threads.com." }, "text": { "type": "string", "description": "Post text; empty for posts that contain only media." }, "created_at": { "description": "Publication time in ISO 8601; null when unknown.", "type": [ "string", "null" ] }, "like_count": { "description": "Likes when fetched; null when Threads omits the count.", "type": [ "number", "null" ] }, "reply_count": { "description": "Direct replies when fetched; null when unknown.", "type": [ "number", "null" ] }, "repost_count": { "description": "Reposts when fetched; null when unknown.", "type": [ "number", "null" ] }, "quote_count": { "description": "Quote posts when fetched; null when unknown.", "type": [ "number", "null" ] }, "author": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "description": "Numeric Threads account id, returned as a string." }, "username": { "type": "string", "description": "Account username without @." }, "name": { "description": "Display name; null when the public post omits it.", "type": [ "string", "null" ] }, "is_verified": { "description": "Whether the author has a verified badge; null when unknown.", "type": [ "boolean", "null" ] }, "profile_pic_url": { "description": "Profile picture URL; null when the public post omits it.", "type": [ "string", "null" ] } }, "required": [ "id", "username", "name", "is_verified", "profile_pic_url" ], "additionalProperties": false, "description": "Public author metadata; null when no usable author identity is included." }, { "type": "null" } ] }, "media": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "image", "video" ], "description": "Whether the URL is an image or a playable video file." }, "url": { "type": "string", "description": "Largest public image or video file URL supplied by Threads; these CDN links can expire." }, "width": { "description": "Media width in pixels; null when unknown.", "type": [ "number", "null" ] }, "height": { "description": "Media height in pixels; null when unknown.", "type": [ "number", "null" ] } }, "required": [ "type", "url", "width", "height" ], "additionalProperties": false }, "description": "Attached media in source order; empty for text-only posts." }, "is_reply": { "description": "Whether this is a reply to another post; null when unknown.", "type": [ "boolean", "null" ] }, "is_pinned": { "description": "Whether Threads marks the post as pinned; null when unknown.", "type": [ "boolean", "null" ] } }, "required": [ "id", "code", "url", "text", "created_at", "like_count", "reply_count", "repost_count", "quote_count", "author", "media", "is_reply", "is_pinned" ], "additionalProperties": false }, "description": "Public posts in feed order, including linked self replies; post ids are unique within this page." }, "next_cursor": { "description": "Pass as `cursor` for the next page; null at the end.", "type": [ "string", "null" ] }, "has_more": { "type": "boolean", "description": "Whether Threads reports another page. False when next_cursor is null." } }, "required": [ "success", "credits_remaining", "credits_charged", "posts", "next_cursor", "has_more" ], "additionalProperties": false } } } }, "403": { "description": "not_public: The platform confirmed this account or content isn't available to logged-out visitors. Use a publicly visible target.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "not_found: The endpoint, or the thing you asked for (ad, post, subreddit), doesn't exist. Charged when the platform was checked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error. Not charged, except the endpoint's own 4xx answers such as not_found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/threads/post": { "get": { "operationId": "threads_post", "tags": [ "Threads" ], "summary": "Threads post", "description": "The text, author, media and engagement of one public Threads post.\n\nPass a public threads.com or threads.net post URL. Returns the target post rather than suggested posts or its reply thread. Unknown or deleted posts return 404 only when Threads explicitly reports them unavailable. Login walls and incomplete pages return an upstream error.\n\nCost: 1 credit.", "externalDocs": { "url": "https://lurkapi.com/docs/threads/post" }, "x-credits": 1, "parameters": [ { "name": "url", "in": "query", "required": true, "description": "Public post URL on threads.com or threads.net, containing /@/post/.", "schema": { "description": "Public post URL on threads.com or threads.net, containing /@/post/.", "type": "string" }, "example": "https://www.threads.com/@zuck/post/Dd1MqfcG0aH" } ], "responses": { "200": { "description": "The text, author, media and engagement of one public Threads post.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "const": true, "description": "Always true here; errors have `success: false`." }, "credits_remaining": { "type": "number", "description": "Your balance after this call. On anonymous playground calls: free tries left today." }, "credits_charged": { "type": "number", "description": "Credits this call cost; 0 on free endpoints. On anonymous playground calls: tries used (1)." }, "id": { "type": "string", "description": "Numeric Threads post id, returned as a string." }, "code": { "type": "string", "description": "Post shortcode used in its public URL." }, "url": { "type": "string", "description": "Canonical public post URL on threads.com." }, "text": { "type": "string", "description": "Post text; empty for posts that contain only media." }, "created_at": { "description": "Publication time in ISO 8601; null when unknown.", "type": [ "string", "null" ] }, "like_count": { "description": "Likes when fetched; null when Threads omits the count.", "type": [ "number", "null" ] }, "reply_count": { "description": "Direct replies when fetched; null when unknown.", "type": [ "number", "null" ] }, "repost_count": { "description": "Reposts when fetched; null when unknown.", "type": [ "number", "null" ] }, "quote_count": { "description": "Quote posts when fetched; null when unknown.", "type": [ "number", "null" ] }, "author": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "description": "Numeric Threads account id, returned as a string." }, "username": { "type": "string", "description": "Account username without @." }, "name": { "description": "Display name; null when the public post omits it.", "type": [ "string", "null" ] }, "is_verified": { "description": "Whether the author has a verified badge; null when unknown.", "type": [ "boolean", "null" ] }, "profile_pic_url": { "description": "Profile picture URL; null when the public post omits it.", "type": [ "string", "null" ] } }, "required": [ "id", "username", "name", "is_verified", "profile_pic_url" ], "additionalProperties": false, "description": "Public author metadata; null when no usable author identity is included." }, { "type": "null" } ] }, "media": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "image", "video" ], "description": "Whether the URL is an image or a playable video file." }, "url": { "type": "string", "description": "Largest public image or video file URL supplied by Threads; these CDN links can expire." }, "width": { "description": "Media width in pixels; null when unknown.", "type": [ "number", "null" ] }, "height": { "description": "Media height in pixels; null when unknown.", "type": [ "number", "null" ] } }, "required": [ "type", "url", "width", "height" ], "additionalProperties": false }, "description": "Attached media in source order; empty for text-only posts." }, "is_reply": { "description": "Whether this is a reply to another post; null when unknown.", "type": [ "boolean", "null" ] }, "is_pinned": { "description": "Whether Threads marks the post as pinned; null when unknown.", "type": [ "boolean", "null" ] } }, "required": [ "success", "credits_remaining", "credits_charged", "id", "code", "url", "text", "created_at", "like_count", "reply_count", "repost_count", "quote_count", "author", "media", "is_reply", "is_pinned" ], "additionalProperties": false } } } }, "403": { "description": "not_public: The platform confirmed this account or content isn't available to logged-out visitors. Use a publicly visible target.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "not_found: The endpoint, or the thing you asked for (ad, post, subreddit), doesn't exist. Charged when the platform was checked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error. Not charged, except the endpoint's own 4xx answers such as not_found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/instagram/profile": { "get": { "operationId": "instagram_profile", "tags": [ "Instagram" ], "summary": "Profile", "description": "A public profile's biography, links and follower counts.\n\nPass a username or profile URL. Follower and following counts come from public profile data. Post count and higher resolution images depend on what Instagram returns; missing fields are null.\n\nCost: 1 credit.", "externalDocs": { "url": "https://lurkapi.com/docs/instagram/profile" }, "x-credits": 1, "parameters": [ { "name": "username", "in": "query", "required": false, "description": "Instagram username, with or without @, or a profile URL. Required unless url is given.", "schema": { "description": "Instagram username, with or without @, or a profile URL. Required unless url is given.", "type": "string", "maxLength": 2048 }, "example": "nike" }, { "name": "url", "in": "query", "required": false, "description": "An instagram.com profile URL. Required unless username is given.", "schema": { "description": "An instagram.com profile URL. Required unless username is given.", "type": "string", "maxLength": 2048 } } ], "responses": { "200": { "description": "A public profile's biography, links and follower counts.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "const": true, "description": "Always true here; errors have `success: false`." }, "credits_remaining": { "type": "number", "description": "Your balance after this call. On anonymous playground calls: free tries left today." }, "credits_charged": { "type": "number", "description": "Credits this call cost; 0 on free endpoints. On anonymous playground calls: tries used (1)." }, "data": { "type": "object", "properties": { "pk": { "type": "string", "description": "Numeric Instagram user id, represented as a string." }, "id": { "description": "Instagram's separate GraphQL profile id; null when not returned.", "type": [ "string", "null" ] }, "username": { "type": "string", "description": "Instagram username, without @." }, "url": { "type": "string", "description": "Canonical Instagram profile URL." }, "full_name": { "description": "Display name; null when not returned.", "type": [ "string", "null" ] }, "biography": { "description": "Biography, preserving line breaks; null when not returned.", "type": [ "string", "null" ] }, "profile_pic_url": { "description": "Profile image URL; CDN links can expire; null when not returned.", "type": [ "string", "null" ] }, "profile_pic_url_hd": { "description": "Higher resolution profile image URL, when available; null when not returned.", "type": [ "string", "null" ] }, "is_private": { "description": "Whether the account is private; null when not returned.", "type": [ "boolean", "null" ] }, "is_verified": { "description": "Whether Instagram shows a verified badge; null when not returned.", "type": [ "boolean", "null" ] }, "follower_count": { "description": "Follower count; null when not shown or returned. A null count is not zero.", "type": [ "number", "null" ] }, "following_count": { "description": "Number of accounts followed; null when not shown or returned. A null count is not zero.", "type": [ "number", "null" ] }, "media_count": { "description": "Number of posts; public GraphQL frequently omits this count; null when not shown or returned. A null count is not zero.", "type": [ "number", "null" ] }, "external_url": { "description": "Main website link in the profile; null when not returned.", "type": [ "string", "null" ] }, "bio_links": { "anyOf": [ { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string", "description": "The link's destination URL." }, "title": { "description": "Link title; an empty title means none was set; null when not returned.", "type": [ "string", "null" ] } }, "required": [ "url", "title" ], "additionalProperties": false } }, { "type": "null" } ], "description": "Links listed in the bio, in Instagram's order; null when not returned." }, "pronouns": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ], "description": "Pronouns the user set; null when not returned, empty when none are set." }, "account_type": { "description": "Instagram's account type code, e.g. 2; null when not shown or returned. A null count is not zero.", "type": [ "number", "null" ] }, "category": { "description": "Category label; an empty string means Instagram returned no label; null when not returned.", "type": [ "string", "null" ] }, "total_clips_count": { "description": "Reel count returned by Instagram; it may differ from the number visible in the reels tab; null when not shown or returned. A null count is not zero.", "type": [ "number", "null" ] } }, "required": [ "pk", "id", "username", "url", "full_name", "biography", "profile_pic_url", "profile_pic_url_hd", "is_private", "is_verified", "follower_count", "following_count", "media_count", "external_url", "bio_links", "pronouns", "account_type", "category", "total_clips_count" ], "additionalProperties": false, "description": "Profile details." } }, "required": [ "success", "credits_remaining", "credits_charged", "data" ], "additionalProperties": false } } } }, "404": { "description": "not_found: The endpoint, or the thing you asked for (ad, post, subreddit), doesn't exist. Charged when the platform was checked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error. Not charged, except the endpoint's own 4xx answers such as not_found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v2/instagram/user/posts": { "get": { "operationId": "instagram_user_posts", "tags": [ "Instagram" ], "summary": "User posts", "description": "A page of public posts with captions, media and engagement counts.\n\nPass a username or profile URL. Up to 50 posts can be requested; Instagram may return fewer. Preserve end_cursor exactly and pass it as after to continue. Private posts are unavailable. Cached pages cost the same as fresh pages.\n\nCost: 1 credit.", "externalDocs": { "url": "https://lurkapi.com/docs/instagram/user-posts" }, "x-credits": 1, "parameters": [ { "name": "username", "in": "query", "required": false, "description": "Instagram username, with or without @, or a profile URL. Required unless url is given.", "schema": { "description": "Instagram username, with or without @, or a profile URL. Required unless url is given.", "type": "string", "maxLength": 2048 }, "example": "nike" }, { "name": "url", "in": "query", "required": false, "description": "An instagram.com profile URL. Required unless username is given.", "schema": { "description": "An instagram.com profile URL. Required unless username is given.", "type": "string", "maxLength": 2048 } }, { "name": "first", "in": "query", "required": false, "description": "Requested page size, 1–50; default 12. Instagram may return fewer items.", "schema": { "default": 12, "description": "Requested page size, 1–50; default 12. Instagram may return fewer items.", "type": "integer", "minimum": 1, "maximum": 50 }, "example": 12 }, { "name": "after", "in": "query", "required": false, "description": "Pass end_cursor from the previous page unchanged; omit for the first page.", "schema": { "description": "Pass end_cursor from the previous page unchanged; omit for the first page.", "type": "string", "minLength": 1, "maxLength": 8192 } } ], "responses": { "200": { "description": "A page of public posts with captions, media and engagement counts.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "const": true, "description": "Always true here; errors have `success: false`." }, "credits_remaining": { "type": "number", "description": "Your balance after this call. On anonymous playground calls: free tries left today." }, "credits_charged": { "type": "number", "description": "Credits this call cost; 0 on free endpoints. On anonymous playground calls: tries used (1)." }, "posts": { "type": "array", "items": { "type": "object", "properties": { "pk": { "type": "string", "description": "Numeric media id, represented as a string." }, "media_type": { "type": "number", "description": "Instagram media type: 1 photo, 2 video, 8 carousel." }, "display_url": { "description": "Preview image URL; CDN links can expire; null when not returned.", "type": [ "string", "null" ] }, "images": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string", "description": "Direct image URL; CDN links can expire." }, "width": { "description": "Image width in pixels; null when not shown or returned. A null count is not zero.", "type": [ "number", "null" ] }, "height": { "description": "Image height in pixels; null when not shown or returned. A null count is not zero.", "type": [ "number", "null" ] } }, "required": [ "url", "width", "height" ], "additionalProperties": false, "description": "One available image size." }, "description": "Available image sizes; empty when none are returned." }, "videos": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string", "description": "Direct MP4 URL; CDN links can expire." }, "width": { "description": "Video width in pixels; null when not shown or returned. A null count is not zero.", "type": [ "number", "null" ] }, "height": { "description": "Video height in pixels; null when not shown or returned. A null count is not zero.", "type": [ "number", "null" ] } }, "required": [ "url", "width", "height" ], "additionalProperties": false, "description": "One available video size." }, "description": "Available MP4 versions; empty for photos or when video URLs are unavailable." }, "code": { "type": "string", "description": "The post's case-sensitive shortcode." }, "url": { "type": "string", "description": "Canonical Instagram post URL." }, "product_type": { "description": "Instagram product type, e.g. clips for a reel or feed for a feed post; null when not returned.", "type": [ "string", "null" ] }, "caption": { "description": "Post caption as plain text, preserving line breaks; an empty string is an explicitly empty caption; null when not returned.", "type": [ "string", "null" ] }, "taken_at": { "description": "Published at, Unix seconds; null when not shown or returned. A null count is not zero.", "type": [ "number", "null" ] }, "like_count": { "description": "Like count; null when not shown or returned. A null count is not zero.", "type": [ "number", "null" ] }, "comment_count": { "description": "Comment count; null when not shown or returned. A null count is not zero.", "type": [ "number", "null" ] }, "play_count": { "description": "Play count; usually omitted on logged-out post and timeline queries; null when not shown or returned. A null count is not zero.", "type": [ "number", "null" ] }, "view_count": { "description": "View count; usually omitted on logged-out post and timeline queries; null when not shown or returned. A null count is not zero.", "type": [ "number", "null" ] }, "accessibility_caption": { "description": "Instagram's accessibility description; null when not returned.", "type": [ "string", "null" ] }, "user": { "type": "object", "properties": { "pk": { "type": "string", "description": "The account's numeric Instagram id, represented as a string." }, "username": { "type": "string", "description": "Instagram username, without @." }, "full_name": { "description": "Display name; null when not returned.", "type": [ "string", "null" ] }, "profile_pic_url": { "description": "Profile image URL; CDN links can expire; null when not returned.", "type": [ "string", "null" ] }, "is_verified": { "description": "Whether Instagram shows a verified badge; null when not returned.", "type": [ "boolean", "null" ] } }, "required": [ "pk", "username", "full_name", "profile_pic_url", "is_verified" ], "additionalProperties": false, "description": "Post author." }, "coauthor_producers": { "type": "array", "items": { "type": "object", "properties": { "pk": { "type": "string", "description": "The account's numeric Instagram id, represented as a string." }, "username": { "type": "string", "description": "Instagram username, without @." }, "full_name": { "description": "Display name; null when not returned.", "type": [ "string", "null" ] }, "profile_pic_url": { "description": "Profile image URL; CDN links can expire; null when not returned.", "type": [ "string", "null" ] }, "is_verified": { "description": "Whether Instagram shows a verified badge; null when not returned.", "type": [ "boolean", "null" ] } }, "required": [ "pk", "username", "full_name", "profile_pic_url", "is_verified" ], "additionalProperties": false, "description": "The account that published this item." }, "description": "Coauthors returned by Instagram; empty when none are returned." }, "is_paid_partnership": { "description": "Whether Instagram marks the post as a paid partnership; null when not returned.", "type": [ "boolean", "null" ] }, "location": { "anyOf": [ { "type": "object", "properties": { "pk": { "description": "Numeric location id; null when not returned.", "type": [ "string", "null" ] }, "name": { "description": "Location name; null when not returned.", "type": [ "string", "null" ] } }, "required": [ "pk", "name" ], "additionalProperties": false }, { "type": "null" } ], "description": "Tagged location; null when none is returned." }, "carousel_media": { "type": "array", "items": { "type": "object", "properties": { "pk": { "type": "string", "description": "Numeric media id, represented as a string." }, "media_type": { "type": "number", "description": "Instagram media type: 1 photo, 2 video, 8 carousel." }, "display_url": { "description": "Preview image URL; CDN links can expire; null when not returned.", "type": [ "string", "null" ] }, "images": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string", "description": "Direct image URL; CDN links can expire." }, "width": { "description": "Image width in pixels; null when not shown or returned. A null count is not zero.", "type": [ "number", "null" ] }, "height": { "description": "Image height in pixels; null when not shown or returned. A null count is not zero.", "type": [ "number", "null" ] } }, "required": [ "url", "width", "height" ], "additionalProperties": false, "description": "One available image size." }, "description": "Available image sizes; empty when none are returned." }, "videos": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string", "description": "Direct MP4 URL; CDN links can expire." }, "width": { "description": "Video width in pixels; null when not shown or returned. A null count is not zero.", "type": [ "number", "null" ] }, "height": { "description": "Video height in pixels; null when not shown or returned. A null count is not zero.", "type": [ "number", "null" ] } }, "required": [ "url", "width", "height" ], "additionalProperties": false, "description": "One available video size." }, "description": "Available MP4 versions; empty for photos or when video URLs are unavailable." } }, "required": [ "pk", "media_type", "display_url", "images", "videos" ], "additionalProperties": false, "description": "One carousel item." }, "description": "Carousel items in order; empty for single-media posts." } }, "required": [ "pk", "media_type", "display_url", "images", "videos", "code", "url", "product_type", "caption", "taken_at", "like_count", "comment_count", "play_count", "view_count", "accessibility_caption", "user", "coauthor_producers", "is_paid_partnership", "location", "carousel_media" ], "additionalProperties": false, "description": "A public post or reel, including media and engagement. Missing counts remain null." }, "description": "Posts in Instagram's timeline order, which can include pinned posts." }, "end_cursor": { "description": "Opaque pagination cursor; pass it as after for the next page; null when not returned.", "type": [ "string", "null" ] }, "has_next_page": { "type": "boolean", "description": "Whether Instagram reports another page. A false value ends pagination." } }, "required": [ "success", "credits_remaining", "credits_charged", "posts", "end_cursor", "has_next_page" ], "additionalProperties": false } } } }, "403": { "description": "not_public: The platform confirmed this account or content isn't available to logged-out visitors. Use a publicly visible target.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "not_found: The endpoint, or the thing you asked for (ad, post, subreddit), doesn't exist. Charged when the platform was checked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error. Not charged, except the endpoint's own 4xx answers such as not_found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/instagram/post": { "get": { "operationId": "instagram_post", "tags": [ "Instagram" ], "summary": "Post", "description": "A public photo, carousel, video or reel with its caption and counts.\n\nPass a post URL or shortcode. Return media URLs, caption, author and the counts visible to logged-out visitors. Missing and private posts are unavailable. CDN media URLs can expire.\n\nCost: 1 credit.", "externalDocs": { "url": "https://lurkapi.com/docs/instagram/post" }, "x-credits": 1, "parameters": [ { "name": "code", "in": "query", "required": false, "description": "The post's shortcode, e.g. Ddl5eH-u4le. Required unless url is given.", "schema": { "description": "The post's shortcode, e.g. Ddl5eH-u4le. Required unless url is given.", "type": "string", "maxLength": 2048 } }, { "name": "url", "in": "query", "required": false, "description": "An instagram.com/p/, /reel/ or /tv/ URL, or the shortcode. Required unless code is given.", "schema": { "description": "An instagram.com/p/, /reel/ or /tv/ URL, or the shortcode. Required unless code is given.", "type": "string", "maxLength": 2048 }, "example": "https://www.instagram.com/reel/Ddl5eH-u4le/" } ], "responses": { "200": { "description": "A public photo, carousel, video or reel with its caption and counts.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "const": true, "description": "Always true here; errors have `success: false`." }, "credits_remaining": { "type": "number", "description": "Your balance after this call. On anonymous playground calls: free tries left today." }, "credits_charged": { "type": "number", "description": "Credits this call cost; 0 on free endpoints. On anonymous playground calls: tries used (1)." }, "data": { "type": "object", "properties": { "pk": { "type": "string", "description": "Numeric media id, represented as a string." }, "media_type": { "type": "number", "description": "Instagram media type: 1 photo, 2 video, 8 carousel." }, "display_url": { "description": "Preview image URL; CDN links can expire; null when not returned.", "type": [ "string", "null" ] }, "images": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string", "description": "Direct image URL; CDN links can expire." }, "width": { "description": "Image width in pixels; null when not shown or returned. A null count is not zero.", "type": [ "number", "null" ] }, "height": { "description": "Image height in pixels; null when not shown or returned. A null count is not zero.", "type": [ "number", "null" ] } }, "required": [ "url", "width", "height" ], "additionalProperties": false, "description": "One available image size." }, "description": "Available image sizes; empty when none are returned." }, "videos": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string", "description": "Direct MP4 URL; CDN links can expire." }, "width": { "description": "Video width in pixels; null when not shown or returned. A null count is not zero.", "type": [ "number", "null" ] }, "height": { "description": "Video height in pixels; null when not shown or returned. A null count is not zero.", "type": [ "number", "null" ] } }, "required": [ "url", "width", "height" ], "additionalProperties": false, "description": "One available video size." }, "description": "Available MP4 versions; empty for photos or when video URLs are unavailable." }, "code": { "type": "string", "description": "The post's case-sensitive shortcode." }, "url": { "type": "string", "description": "Canonical Instagram post URL." }, "product_type": { "description": "Instagram product type, e.g. clips for a reel or feed for a feed post; null when not returned.", "type": [ "string", "null" ] }, "caption": { "description": "Post caption as plain text, preserving line breaks; an empty string is an explicitly empty caption; null when not returned.", "type": [ "string", "null" ] }, "taken_at": { "description": "Published at, Unix seconds; null when not shown or returned. A null count is not zero.", "type": [ "number", "null" ] }, "like_count": { "description": "Like count; null when not shown or returned. A null count is not zero.", "type": [ "number", "null" ] }, "comment_count": { "description": "Comment count; null when not shown or returned. A null count is not zero.", "type": [ "number", "null" ] }, "play_count": { "description": "Play count; usually omitted on logged-out post and timeline queries; null when not shown or returned. A null count is not zero.", "type": [ "number", "null" ] }, "view_count": { "description": "View count; usually omitted on logged-out post and timeline queries; null when not shown or returned. A null count is not zero.", "type": [ "number", "null" ] }, "accessibility_caption": { "description": "Instagram's accessibility description; null when not returned.", "type": [ "string", "null" ] }, "user": { "type": "object", "properties": { "pk": { "type": "string", "description": "The account's numeric Instagram id, represented as a string." }, "username": { "type": "string", "description": "Instagram username, without @." }, "full_name": { "description": "Display name; null when not returned.", "type": [ "string", "null" ] }, "profile_pic_url": { "description": "Profile image URL; CDN links can expire; null when not returned.", "type": [ "string", "null" ] }, "is_verified": { "description": "Whether Instagram shows a verified badge; null when not returned.", "type": [ "boolean", "null" ] } }, "required": [ "pk", "username", "full_name", "profile_pic_url", "is_verified" ], "additionalProperties": false, "description": "Post author." }, "coauthor_producers": { "type": "array", "items": { "type": "object", "properties": { "pk": { "type": "string", "description": "The account's numeric Instagram id, represented as a string." }, "username": { "type": "string", "description": "Instagram username, without @." }, "full_name": { "description": "Display name; null when not returned.", "type": [ "string", "null" ] }, "profile_pic_url": { "description": "Profile image URL; CDN links can expire; null when not returned.", "type": [ "string", "null" ] }, "is_verified": { "description": "Whether Instagram shows a verified badge; null when not returned.", "type": [ "boolean", "null" ] } }, "required": [ "pk", "username", "full_name", "profile_pic_url", "is_verified" ], "additionalProperties": false, "description": "The account that published this item." }, "description": "Coauthors returned by Instagram; empty when none are returned." }, "is_paid_partnership": { "description": "Whether Instagram marks the post as a paid partnership; null when not returned.", "type": [ "boolean", "null" ] }, "location": { "anyOf": [ { "type": "object", "properties": { "pk": { "description": "Numeric location id; null when not returned.", "type": [ "string", "null" ] }, "name": { "description": "Location name; null when not returned.", "type": [ "string", "null" ] } }, "required": [ "pk", "name" ], "additionalProperties": false }, { "type": "null" } ], "description": "Tagged location; null when none is returned." }, "carousel_media": { "type": "array", "items": { "type": "object", "properties": { "pk": { "type": "string", "description": "Numeric media id, represented as a string." }, "media_type": { "type": "number", "description": "Instagram media type: 1 photo, 2 video, 8 carousel." }, "display_url": { "description": "Preview image URL; CDN links can expire; null when not returned.", "type": [ "string", "null" ] }, "images": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string", "description": "Direct image URL; CDN links can expire." }, "width": { "description": "Image width in pixels; null when not shown or returned. A null count is not zero.", "type": [ "number", "null" ] }, "height": { "description": "Image height in pixels; null when not shown or returned. A null count is not zero.", "type": [ "number", "null" ] } }, "required": [ "url", "width", "height" ], "additionalProperties": false, "description": "One available image size." }, "description": "Available image sizes; empty when none are returned." }, "videos": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string", "description": "Direct MP4 URL; CDN links can expire." }, "width": { "description": "Video width in pixels; null when not shown or returned. A null count is not zero.", "type": [ "number", "null" ] }, "height": { "description": "Video height in pixels; null when not shown or returned. A null count is not zero.", "type": [ "number", "null" ] } }, "required": [ "url", "width", "height" ], "additionalProperties": false, "description": "One available video size." }, "description": "Available MP4 versions; empty for photos or when video URLs are unavailable." } }, "required": [ "pk", "media_type", "display_url", "images", "videos" ], "additionalProperties": false, "description": "One carousel item." }, "description": "Carousel items in order; empty for single-media posts." } }, "required": [ "pk", "media_type", "display_url", "images", "videos", "code", "url", "product_type", "caption", "taken_at", "like_count", "comment_count", "play_count", "view_count", "accessibility_caption", "user", "coauthor_producers", "is_paid_partnership", "location", "carousel_media" ], "additionalProperties": false, "description": "The requested post." } }, "required": [ "success", "credits_remaining", "credits_charged", "data" ], "additionalProperties": false } } } }, "403": { "description": "not_public: The platform confirmed this account or content isn't available to logged-out visitors. Use a publicly visible target.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "not_found: The endpoint, or the thing you asked for (ad, post, subreddit), doesn't exist. Charged when the platform was checked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error. Not charged, except the endpoint's own 4xx answers such as not_found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v2/instagram/post/comments": { "get": { "operationId": "instagram_post_comments", "tags": [ "Instagram" ], "summary": "Post comments", "description": "A page of public comments with authors, timestamps and likes.\n\nPass a post URL or shortcode. Comments are in Instagram's public order, which can differ from chronological order. Pass end_cursor as after for the next page. This endpoint returns comments rather than fetching all replies; a missing reply count stays null.\n\nCost: 1 credit.", "externalDocs": { "url": "https://lurkapi.com/docs/instagram/post-comments" }, "x-credits": 1, "parameters": [ { "name": "code", "in": "query", "required": false, "description": "The post's shortcode, e.g. Ddl5eH-u4le. Required unless url is given.", "schema": { "description": "The post's shortcode, e.g. Ddl5eH-u4le. Required unless url is given.", "type": "string", "maxLength": 2048 } }, { "name": "url", "in": "query", "required": false, "description": "An instagram.com/p/, /reel/ or /tv/ URL, or the shortcode. Required unless code is given.", "schema": { "description": "An instagram.com/p/, /reel/ or /tv/ URL, or the shortcode. Required unless code is given.", "type": "string", "maxLength": 2048 }, "example": "https://www.instagram.com/p/aye83DjauH/" }, { "name": "first", "in": "query", "required": false, "description": "Requested page size, 1–50; default 12. Instagram may return fewer items.", "schema": { "default": 12, "description": "Requested page size, 1–50; default 12. Instagram may return fewer items.", "type": "integer", "minimum": 1, "maximum": 50 }, "example": 15 }, { "name": "after", "in": "query", "required": false, "description": "Pass end_cursor from the previous page unchanged; omit for the first page.", "schema": { "description": "Pass end_cursor from the previous page unchanged; omit for the first page.", "type": "string", "minLength": 1, "maxLength": 8192 } } ], "responses": { "200": { "description": "A page of public comments with authors, timestamps and likes.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "const": true, "description": "Always true here; errors have `success: false`." }, "credits_remaining": { "type": "number", "description": "Your balance after this call. On anonymous playground calls: free tries left today." }, "credits_charged": { "type": "number", "description": "Credits this call cost; 0 on free endpoints. On anonymous playground calls: tries used (1)." }, "comments": { "type": "array", "items": { "type": "object", "properties": { "pk": { "type": "string", "description": "Comment id, represented as a string." }, "text": { "type": "string", "description": "Comment text, preserving line breaks." }, "created_at": { "description": "Published at, Unix seconds; null when not shown or returned. A null count is not zero.", "type": [ "number", "null" ] }, "comment_like_count": { "description": "Number of likes on the comment; null when not shown or returned. A null count is not zero.", "type": [ "number", "null" ] }, "child_comment_count": { "description": "Reply count; frequently omitted in the public view; null when not shown or returned. A null count is not zero.", "type": [ "number", "null" ] }, "parent_comment_id": { "description": "Parent comment id; null for top-level comments or when unavailable; null when not returned.", "type": [ "string", "null" ] }, "user": { "type": "object", "properties": { "pk": { "type": "string", "description": "The account's numeric Instagram id, represented as a string." }, "username": { "type": "string", "description": "Instagram username, without @." }, "full_name": { "description": "Display name; null when not returned.", "type": [ "string", "null" ] }, "profile_pic_url": { "description": "Profile image URL; CDN links can expire; null when not returned.", "type": [ "string", "null" ] }, "is_verified": { "description": "Whether Instagram shows a verified badge; null when not returned.", "type": [ "boolean", "null" ] } }, "required": [ "pk", "username", "full_name", "profile_pic_url", "is_verified" ], "additionalProperties": false, "description": "Comment author." } }, "required": [ "pk", "text", "created_at", "comment_like_count", "child_comment_count", "parent_comment_id", "user" ], "additionalProperties": false }, "description": "The comments Instagram returned for this page." }, "end_cursor": { "description": "Opaque pagination cursor; pass it as after for the next page; null when not returned.", "type": [ "string", "null" ] }, "has_next_page": { "type": "boolean", "description": "Whether Instagram reports another page. A false value ends pagination." } }, "required": [ "success", "credits_remaining", "credits_charged", "comments", "end_cursor", "has_next_page" ], "additionalProperties": false } } } }, "403": { "description": "not_public: The platform confirmed this account or content isn't available to logged-out visitors. Use a publicly visible target.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "not_found: The endpoint, or the thing you asked for (ad, post, subreddit), doesn't exist. Charged when the platform was checked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error. Not charged, except the endpoint's own 4xx answers such as not_found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/instagram/user/reels": { "get": { "operationId": "instagram_user_reels", "tags": [ "Instagram" ], "summary": "User reels", "description": "A page of public reel previews with play, like and comment counts.\n\nThe public reels tab returns previews and engagement counts. Captions, timestamps and video URLs are absent; call the Post endpoint with a reel's code for those fields. Pass end_cursor as after for the next page. Private reels are unavailable.\n\nCost: 1 credit.", "externalDocs": { "url": "https://lurkapi.com/docs/instagram/user-reels" }, "x-credits": 1, "parameters": [ { "name": "username", "in": "query", "required": false, "description": "Instagram username, with or without @, or a profile URL. Required unless url is given.", "schema": { "description": "Instagram username, with or without @, or a profile URL. Required unless url is given.", "type": "string", "maxLength": 2048 }, "example": "nike" }, { "name": "url", "in": "query", "required": false, "description": "An instagram.com profile URL. Required unless username is given.", "schema": { "description": "An instagram.com profile URL. Required unless username is given.", "type": "string", "maxLength": 2048 } }, { "name": "first", "in": "query", "required": false, "description": "Requested page size, 1–50; default 12. Instagram may return fewer items.", "schema": { "default": 12, "description": "Requested page size, 1–50; default 12. Instagram may return fewer items.", "type": "integer", "minimum": 1, "maximum": 50 }, "example": 12 }, { "name": "after", "in": "query", "required": false, "description": "Pass end_cursor from the previous page unchanged; omit for the first page.", "schema": { "description": "Pass end_cursor from the previous page unchanged; omit for the first page.", "type": "string", "minLength": 1, "maxLength": 8192 } } ], "responses": { "200": { "description": "A page of public reel previews with play, like and comment counts.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "const": true, "description": "Always true here; errors have `success: false`." }, "credits_remaining": { "type": "number", "description": "Your balance after this call. On anonymous playground calls: free tries left today." }, "credits_charged": { "type": "number", "description": "Credits this call cost; 0 on free endpoints. On anonymous playground calls: tries used (1)." }, "reels": { "type": "array", "items": { "type": "object", "properties": { "pk": { "type": "string", "description": "Numeric reel media id, represented as a string." }, "code": { "type": "string", "description": "The reel's case-sensitive shortcode; pass it to the Post endpoint." }, "url": { "type": "string", "description": "Canonical Instagram reel URL." }, "display_url": { "description": "Reel preview image URL; CDN links can expire; null when not returned.", "type": [ "string", "null" ] }, "like_count": { "description": "Like count; null when not shown or returned. A null count is not zero.", "type": [ "number", "null" ] }, "comment_count": { "description": "Comment count; null when not shown or returned. A null count is not zero.", "type": [ "number", "null" ] }, "play_count": { "description": "Play count; null when not shown or returned. A null count is not zero.", "type": [ "number", "null" ] }, "clips_tab_pinned_user_ids": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ], "description": "User ids that pinned this reel in their reels tab; null when not returned." } }, "required": [ "pk", "code", "url", "display_url", "like_count", "comment_count", "play_count", "clips_tab_pinned_user_ids" ], "additionalProperties": false }, "description": "Reel previews in Instagram's reels-tab order." }, "end_cursor": { "description": "Opaque pagination cursor; pass it as after for the next page; null when not returned.", "type": [ "string", "null" ] }, "has_next_page": { "type": "boolean", "description": "Whether Instagram reports another page. A false value ends pagination." } }, "required": [ "success", "credits_remaining", "credits_charged", "reels", "end_cursor", "has_next_page" ], "additionalProperties": false } } } }, "403": { "description": "not_public: The platform confirmed this account or content isn't available to logged-out visitors. Use a publicly visible target.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "not_found: The endpoint, or the thing you asked for (ad, post, subreddit), doesn't exist. Charged when the platform was checked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error. Not charged, except the endpoint's own 4xx answers such as not_found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v2/instagram/media/transcript": { "get": { "operationId": "instagram_media_transcript", "tags": [ "Instagram" ], "summary": "Media transcript", "description": "Transcribe speech from a public Instagram video or reel.\n\nPass a public reel or video URL with a known duration of at most 120 seconds. Speech-to-text costs 5 credits when it succeeds; a cached transcript costs 1 credit because speech-to-text does not run again. Photos, videos without a known duration, longer videos, unavailable audio and private media cannot be transcribed. Transcription is machine-generated and can contain errors.\n\nCost: 1 credit; 5 if speech-to-text runs.", "externalDocs": { "url": "https://lurkapi.com/docs/instagram/media-transcript" }, "x-credits": 1, "x-extra-credits": { "asr": 4 }, "parameters": [ { "name": "code", "in": "query", "required": false, "description": "The post's shortcode, e.g. Ddl5eH-u4le. Required unless url is given.", "schema": { "description": "The post's shortcode, e.g. Ddl5eH-u4le. Required unless url is given.", "type": "string", "maxLength": 2048 } }, { "name": "url", "in": "query", "required": false, "description": "An instagram.com/p/, /reel/ or /tv/ URL, or the shortcode. Required unless code is given.", "schema": { "description": "An instagram.com/p/, /reel/ or /tv/ URL, or the shortcode. Required unless code is given.", "type": "string", "maxLength": 2048 }, "example": "https://www.instagram.com/reel/Ddl5eH-u4le/" } ], "responses": { "200": { "description": "Transcribe speech from a public Instagram video or reel.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "const": true, "description": "Always true here; errors have `success: false`." }, "credits_remaining": { "type": "number", "description": "Your balance after this call. On anonymous playground calls: free tries left today." }, "credits_charged": { "type": "number", "description": "Credits this call cost; 0 on free endpoints. On anonymous playground calls: tries used (1)." }, "code": { "type": "string", "description": "The video's Instagram shortcode." }, "url": { "type": "string", "description": "Canonical Instagram post URL." }, "transcript": { "type": "string", "description": "Recognized speech as plain text; machine transcription may contain mistakes." }, "language": { "description": "Detected spoken language, ISO 639-1; null when not returned.", "type": [ "string", "null" ] }, "duration_s": { "description": "Audio duration in seconds; null when not shown or returned. A null count is not zero.", "type": [ "number", "null" ] }, "segments": { "type": "array", "items": { "type": "object", "properties": { "start": { "type": "number", "description": "Segment start offset in seconds." }, "end": { "type": "number", "description": "Segment end offset in seconds." }, "text": { "type": "string", "description": "Recognized speech in this segment." } }, "required": [ "start", "end", "text" ], "additionalProperties": false }, "description": "Timed transcript segments returned by speech-to-text; empty when unavailable." }, "source": { "type": "string", "const": "speech_to_text", "description": "How the transcript was produced: speech_to_text." } }, "required": [ "success", "credits_remaining", "credits_charged", "code", "url", "transcript", "language", "duration_s", "segments", "source" ], "additionalProperties": false } } } }, "400": { "description": "invalid_params: A parameter is missing or invalid. `issues` names each one.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "not_public: The platform confirmed this account or content isn't available to logged-out visitors. Use a publicly visible target.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "not_found: The endpoint, or the thing you asked for (ad, post, subreddit), doesn't exist. Charged when the platform was checked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error. Not charged, except the endpoint's own 4xx answers such as not_found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/linkedin/company": { "get": { "operationId": "linkedin_company", "tags": [ "LinkedIn" ], "summary": "LinkedIn company page", "description": "A company's public overview and latest updates.\n\nPublic company overview from LinkedIn's guest page. Includes the latest updates that LinkedIn makes available without a login. Missing public fields are null. Employee profiles, funding details and the full About tab are outside this response. An authentication wall or challenge is an upstream error, never a successful empty company.\n\nCost: 1 credit.", "externalDocs": { "url": "https://lurkapi.com/docs/linkedin/company" }, "x-credits": 1, "parameters": [ { "name": "url", "in": "query", "required": true, "description": "Public LinkedIn company page URL, e.g. https://www.linkedin.com/company/hubspot/. Use the base company page.", "schema": { "description": "Public LinkedIn company page URL, e.g. https://www.linkedin.com/company/hubspot/. Use the base company page.", "type": "string" }, "example": "https://www.linkedin.com/company/hubspot/" } ], "responses": { "200": { "description": "A company's public overview and latest updates.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "const": true, "description": "Always true here; errors have `success: false`." }, "credits_remaining": { "type": "number", "description": "Your balance after this call. On anonymous playground calls: free tries left today." }, "credits_charged": { "type": "number", "description": "Credits this call cost; 0 on free endpoints. On anonymous playground calls: tries used (1)." }, "id": { "description": "LinkedIn organization id, when exposed on the public page.", "type": [ "string", "null" ] }, "url": { "type": "string", "description": "Canonical public LinkedIn company page URL." }, "name": { "type": "string", "description": "Company name." }, "tagline": { "description": "Company's short tagline.", "type": [ "string", "null" ] }, "description": { "description": "Public About us text.", "type": [ "string", "null" ] }, "website": { "description": "External website published by the company.", "type": [ "string", "null" ] }, "logo": { "description": "Company logo URL; may expire.", "type": [ "string", "null" ] }, "industry": { "description": "Industry category shown by LinkedIn.", "type": [ "string", "null" ] }, "size": { "description": "Company headcount range as LinkedIn displays it, e.g. 5,001–10,000 employees.", "type": [ "string", "null" ] }, "employeeCount": { "description": "LinkedIn members affiliated with the company; this can differ from its declared size range.", "type": [ "number", "null" ] }, "followers": { "description": "Followers of the company page, when published.", "type": [ "number", "null" ] }, "founded": { "description": "Founding year published by the company.", "type": [ "number", "null" ] }, "headquarters": { "description": "Headquarters location as displayed by LinkedIn.", "type": [ "string", "null" ] }, "type": { "description": "Organization type, e.g. Public Company.", "type": [ "string", "null" ] }, "specialties": { "type": "array", "items": { "type": "string" }, "description": "Company specialties listed on the public page." }, "posts": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Activity id of this update, kept as a string to preserve all digits." }, "url": { "type": "string", "description": "Public post URL or activity permalink." }, "text": { "type": "string", "description": "The update's public text. Empty when the card only contains media." }, "datePublished": { "description": "Publication time in UTC. For repost cards with no published timestamp, estimated from the activity id; see dateSource.", "type": [ "string", "null" ] }, "dateSource": { "anyOf": [ { "type": "string", "enum": [ "published", "activity_id" ] }, { "type": "null" } ], "description": "published comes from LinkedIn JSON-LD; activity_id is reconstructed from the activity id and may describe the repost time. Null when unavailable." }, "likeCount": { "description": "Total reactions LinkedIn shows, including reaction types other than likes; null when hidden.", "type": [ "number", "null" ] }, "commentCount": { "description": "Number of comments shown on the public card; null when hidden.", "type": [ "number", "null" ] }, "images": { "type": "array", "items": { "type": "string" }, "description": "Public images in the update, in source order. Expiring URLs; empty for video-only or document-only cards." }, "video": { "description": "A publicly playable video URL from the card, or null. URLs may expire.", "type": [ "string", "null" ] }, "reposted": { "type": "boolean", "description": "True when LinkedIn explicitly marks this update as a repost." } }, "required": [ "id", "url", "text", "datePublished", "dateSource", "likeCount", "commentCount", "images", "video", "reposted" ], "additionalProperties": false }, "description": "Latest public update cards, including reposts, in LinkedIn's order. Typically up to 12; not a complete history." } }, "required": [ "success", "credits_remaining", "credits_charged", "id", "url", "name", "tagline", "description", "website", "logo", "industry", "size", "employeeCount", "followers", "founded", "headquarters", "type", "specialties", "posts" ], "additionalProperties": false } } } }, "404": { "description": "not_found: The endpoint, or the thing you asked for (ad, post, subreddit), doesn't exist. Charged when the platform was checked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error. Not charged, except the endpoint's own 4xx answers such as not_found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/linkedin/company/posts": { "get": { "operationId": "linkedin_company_posts", "tags": [ "LinkedIn" ], "summary": "LinkedIn company posts", "description": "Latest public updates from a company page, with text, engagement and media.\n\nReturns only the updates on the public company guest page, typically up to 12, including reposts. There is no reliable public pagination: LinkedIn's guest feed can repeat the first page. page must be 1. This does not mean the company has no older posts. Empty posts is a valid answer only after a genuine company page was parsed. Shares, documents and complete comment threads are not expanded.\n\nCost: 1 credit.", "externalDocs": { "url": "https://lurkapi.com/docs/linkedin/company-posts" }, "x-credits": 1, "parameters": [ { "name": "url", "in": "query", "required": true, "description": "Public LinkedIn company page URL, e.g. https://www.linkedin.com/company/hubspot/. Use the base company page.", "schema": { "description": "Public LinkedIn company page URL, e.g. https://www.linkedin.com/company/hubspot/. Use the base company page.", "type": "string" }, "example": "https://www.linkedin.com/company/hubspot/" }, { "name": "page", "in": "query", "required": false, "description": "Only page 1 is supported: the company's latest publicly visible updates.", "schema": { "default": 1, "description": "Only page 1 is supported: the company's latest publicly visible updates.", "type": "integer", "minimum": 1, "maximum": 1 } } ], "responses": { "200": { "description": "Latest public updates from a company page, with text, engagement and media.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "const": true, "description": "Always true here; errors have `success: false`." }, "credits_remaining": { "type": "number", "description": "Your balance after this call. On anonymous playground calls: free tries left today." }, "credits_charged": { "type": "number", "description": "Credits this call cost; 0 on free endpoints. On anonymous playground calls: tries used (1)." }, "company": { "type": "object", "properties": { "id": { "description": "Organization id, when exposed.", "type": [ "string", "null" ] }, "name": { "type": "string", "description": "Company name." }, "url": { "type": "string", "description": "Canonical company page URL." } }, "required": [ "id", "name", "url" ], "additionalProperties": false, "description": "Company whose latest updates are listed." }, "posts": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Activity id of this update, kept as a string to preserve all digits." }, "url": { "type": "string", "description": "Public post URL or activity permalink." }, "text": { "type": "string", "description": "The update's public text. Empty when the card only contains media." }, "datePublished": { "description": "Publication time in UTC. For repost cards with no published timestamp, estimated from the activity id; see dateSource.", "type": [ "string", "null" ] }, "dateSource": { "anyOf": [ { "type": "string", "enum": [ "published", "activity_id" ] }, { "type": "null" } ], "description": "published comes from LinkedIn JSON-LD; activity_id is reconstructed from the activity id and may describe the repost time. Null when unavailable." }, "likeCount": { "description": "Total reactions LinkedIn shows, including reaction types other than likes; null when hidden.", "type": [ "number", "null" ] }, "commentCount": { "description": "Number of comments shown on the public card; null when hidden.", "type": [ "number", "null" ] }, "images": { "type": "array", "items": { "type": "string" }, "description": "Public images in the update, in source order. Expiring URLs; empty for video-only or document-only cards." }, "video": { "description": "A publicly playable video URL from the card, or null. URLs may expire.", "type": [ "string", "null" ] }, "reposted": { "type": "boolean", "description": "True when LinkedIn explicitly marks this update as a repost." } }, "required": [ "id", "url", "text", "datePublished", "dateSource", "likeCount", "commentCount", "images", "video", "reposted" ], "additionalProperties": false }, "description": "Latest public company update cards in LinkedIn's order." }, "paginationAvailable": { "type": "boolean", "const": false, "description": "Always false: no reliable public pagination is available." } }, "required": [ "success", "credits_remaining", "credits_charged", "company", "posts", "paginationAvailable" ], "additionalProperties": false } } } }, "404": { "description": "not_found: The endpoint, or the thing you asked for (ad, post, subreddit), doesn't exist. Charged when the platform was checked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error. Not charged, except the endpoint's own 4xx answers such as not_found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/linkedin/ads/search": { "get": { "operationId": "linkedin_search_ads", "tags": [ "LinkedIn" ], "summary": "Search LinkedIn ads", "description": "Search LinkedIn's public Ad Library by advertiser or keyword.\n\nOne page of Ad Library previews, up to about 24 ads. Pass company (advertiser name), keyword, or both. Search previews may truncate ad text; use ad details to inspect one creative and its disclosures. Each page costs one credit and does not fetch the individual ad detail pages. Pass paginationToken with the same filters for the next page. Country codes are comma-separated and run dates use YYYY-MM-DD. LinkedIn covers roughly the last year; delivery and targeting disclosures depend on the ad and region. A missing total on pagination pages is null. Block pages and malformed pagination metadata are upstream failures.\n\nCost: 1 credit.", "externalDocs": { "url": "https://lurkapi.com/docs/linkedin/search-ads" }, "x-credits": 1, "parameters": [ { "name": "company", "in": "query", "required": false, "description": "Advertiser name to search, e.g. HubSpot.", "schema": { "description": "Advertiser name to search, e.g. HubSpot.", "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "keyword", "in": "query", "required": false, "description": "Words in the ad copy.", "schema": { "description": "Words in the ad copy.", "type": "string", "minLength": 1, "maxLength": 200 }, "example": "hubspot" }, { "name": "countries", "in": "query", "required": false, "description": "Only ads delivered in these countries, as comma-separated two-letter codes such as DE,FR. EU is not supported as a country filter.", "schema": { "description": "Only ads delivered in these countries, as comma-separated two-letter codes such as DE,FR. EU is not supported as a country filter.", "type": "string", "pattern": "^[A-Z]{2}(,[A-Z]{2}){0,9}$" } }, { "name": "startDate", "in": "query", "required": false, "description": "First date of the custom date range, YYYY-MM-DD. Supply endDate too; LinkedIn covers roughly the past year.", "schema": { "description": "First date of the custom date range, YYYY-MM-DD. Supply endDate too; LinkedIn covers roughly the past year.", "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, { "name": "endDate", "in": "query", "required": false, "description": "Last date of the custom date range, YYYY-MM-DD. Supply startDate too.", "schema": { "description": "Last date of the custom date range, YYYY-MM-DD. Supply startDate too.", "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, { "name": "paginationToken", "in": "query", "required": false, "description": "Token from the previous page. Keep company, keyword, countries and dates the same.", "schema": { "description": "Token from the previous page. Keep company, keyword, countries and dates the same.", "type": "string", "minLength": 1, "maxLength": 2000 } } ], "responses": { "200": { "description": "Search LinkedIn's public Ad Library by advertiser or keyword.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "const": true, "description": "Always true here; errors have `success: false`." }, "credits_remaining": { "type": "number", "description": "Your balance after this call. On anonymous playground calls: free tries left today." }, "credits_charged": { "type": "number", "description": "Credits this call cost; 0 on free endpoints. On anonymous playground calls: tries used (1)." }, "ads": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "LinkedIn Ad Library ad id." }, "adLibraryUrl": { "type": "string", "description": "Public detail page for this ad." }, "advertiser": { "type": "object", "properties": { "name": { "description": "Advertiser name shown on the preview.", "type": [ "string", "null" ] }, "url": { "description": "Advertiser's LinkedIn page, when linked.", "type": [ "string", "null" ] } }, "required": [ "name", "url" ], "additionalProperties": false, "description": "The advertiser shown on the ad." }, "creativeType": { "description": "Raw creative type LinkedIn publishes in its preview markup.", "type": [ "string", "null" ] }, "format": { "description": "Human-readable ad format shown by LinkedIn, when available.", "type": [ "string", "null" ] }, "text": { "description": "Visible ad copy. Search previews may truncate it; use ad details for the full public copy.", "type": [ "string", "null" ] }, "headline": { "description": "Ad headline when the preview exposes one.", "type": [ "string", "null" ] }, "images": { "type": "array", "items": { "type": "string" }, "description": "Preview and carousel image URLs in source order. URLs can expire." }, "videos": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string", "description": "Playable video source URL." }, "bitrate": { "description": "Source bitrate in bits per second when supplied by LinkedIn.", "type": [ "number", "null" ] } }, "required": [ "url", "bitrate" ], "additionalProperties": false }, "description": "Video variants from the ad preview, or an empty list." }, "cta": { "description": "Call-to-action text shown on the preview.", "type": [ "string", "null" ] } }, "required": [ "id", "adLibraryUrl", "advertiser", "creativeType", "format", "text", "headline", "images", "videos", "cta" ], "additionalProperties": false }, "description": "Ad previews in LinkedIn's search order." }, "total": { "description": "Total matching ads, when shown on the first search page; null on fragments without a count.", "type": [ "number", "null" ] }, "paginationToken": { "description": "Token for the next page; null when LinkedIn supplies none.", "type": [ "string", "null" ] }, "isLastPage": { "type": "boolean", "description": "True when LinkedIn reports the final page or a confirmed empty search." } }, "required": [ "success", "credits_remaining", "credits_charged", "ads", "total", "paginationToken", "isLastPage" ], "additionalProperties": false } } } }, "default": { "description": "Error. Not charged, except the endpoint's own 4xx answers such as not_found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/linkedin/ad": { "get": { "operationId": "linkedin_ad", "tags": [ "LinkedIn" ], "summary": "LinkedIn ad details", "description": "One LinkedIn ad's creative, payer and public delivery disclosures.\n\nUse the adLibraryUrl from ad search. Returns the public ad preview and any payer, run-date, impression and targeting disclosures LinkedIn publishes. These may be absent outside EU-delivered ads. Counts and dates stay in LinkedIn's display format rather than guessing exact values. A restricted creative is marked restricted, while genuine delivery disclosures remain available.\n\nCost: 1 credit.", "externalDocs": { "url": "https://lurkapi.com/docs/linkedin/ad" }, "x-credits": 1, "parameters": [ { "name": "url", "in": "query", "required": true, "description": "Public LinkedIn Ad Library detail URL from the adLibraryUrl field of search ads.", "schema": { "description": "Public LinkedIn Ad Library detail URL from the adLibraryUrl field of search ads.", "type": "string" }, "example": "https://www.linkedin.com/ad-library/detail/1558746953" } ], "responses": { "200": { "description": "One LinkedIn ad's creative, payer and public delivery disclosures.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "const": true, "description": "Always true here; errors have `success: false`." }, "credits_remaining": { "type": "number", "description": "Your balance after this call. On anonymous playground calls: free tries left today." }, "credits_charged": { "type": "number", "description": "Credits this call cost; 0 on free endpoints. On anonymous playground calls: tries used (1)." }, "id": { "type": "string", "description": "LinkedIn Ad Library ad id." }, "adLibraryUrl": { "type": "string", "description": "Public detail page for this ad." }, "advertiser": { "type": "object", "properties": { "name": { "description": "Advertiser name shown on the preview.", "type": [ "string", "null" ] }, "url": { "description": "Advertiser's LinkedIn page, when linked.", "type": [ "string", "null" ] } }, "required": [ "name", "url" ], "additionalProperties": false, "description": "The advertiser shown on the ad." }, "creativeType": { "description": "Raw creative type LinkedIn publishes in its preview markup.", "type": [ "string", "null" ] }, "format": { "description": "Human-readable ad format shown by LinkedIn, when available.", "type": [ "string", "null" ] }, "text": { "description": "Visible ad copy. Search previews may truncate it; use ad details for the full public copy.", "type": [ "string", "null" ] }, "headline": { "description": "Ad headline when the preview exposes one.", "type": [ "string", "null" ] }, "images": { "type": "array", "items": { "type": "string" }, "description": "Preview and carousel image URLs in source order. URLs can expire." }, "videos": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string", "description": "Playable video source URL." }, "bitrate": { "description": "Source bitrate in bits per second when supplied by LinkedIn.", "type": [ "number", "null" ] } }, "required": [ "url", "bitrate" ], "additionalProperties": false }, "description": "Video variants from the ad preview, or an empty list." }, "cta": { "description": "Call-to-action text shown on the preview.", "type": [ "string", "null" ] }, "payer": { "description": "Organization paying for the ad, as disclosed by LinkedIn.", "type": [ "string", "null" ] }, "availability": { "description": "Ad run-date text exactly as LinkedIn shows it. Null when not disclosed.", "type": [ "string", "null" ] }, "totalImpressions": { "description": "Total impression count or range in LinkedIn's display format. Mostly disclosed for ads delivered in the EU.", "type": [ "string", "null" ] }, "impressionsByCountry": { "type": "array", "items": { "type": "object", "properties": { "country": { "type": "string", "description": "Country name or code shown in LinkedIn's breakdown." }, "impressions": { "description": "LinkedIn's displayed delivery share for this country, e.g. 100%; this is not an absolute impression count.", "type": [ "string", "null" ] } }, "required": [ "country", "impressions" ], "additionalProperties": false }, "description": "Published delivery by country; empty when not disclosed." }, "targeting": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string", "description": "Targeting category LinkedIn shows, e.g. language or location." }, "value": { "type": "string", "description": "Publicly disclosed targeting information for the category." } }, "required": [ "label", "value" ], "additionalProperties": false }, "description": "Published targeting fields, generally for EU-delivered ads; empty when not disclosed." }, "restricted": { "type": "boolean", "description": "True when LinkedIn explicitly restricts the creative preview; delivery disclosures may still be available." } }, "required": [ "success", "credits_remaining", "credits_charged", "id", "adLibraryUrl", "advertiser", "creativeType", "format", "text", "headline", "images", "videos", "cta", "payer", "availability", "totalImpressions", "impressionsByCountry", "targeting", "restricted" ], "additionalProperties": false } } } }, "404": { "description": "not_found: The endpoint, or the thing you asked for (ad, post, subreddit), doesn't exist. Charged when the platform was checked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error. Not charged, except the endpoint's own 4xx answers such as not_found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/linktree": { "get": { "operationId": "linkinbio_linktree", "tags": [ "Link-in-bio" ], "summary": "Linktree page", "description": "A public Linktree profile, its link cards and listed social accounts.\n\nPass a `linktr.ee` profile URL. Returns the profile's title, bio, picture, categories, public link cards and social links in the page's order. Link cards without a destination (such as a header or embedded shop) have `url: null`. Locked link destinations are withheld. Missing pages return 404 `not_found`; pages requiring a password or content consent return 403 `not_public`. Results are cached for up to one day. This endpoint reads the page and does not follow its outgoing links.\n\nCost: 1 credit.", "externalDocs": { "url": "https://lurkapi.com/docs/linkinbio/linktree" }, "x-credits": 1, "parameters": [ { "name": "url", "in": "query", "required": true, "description": "The creator's Linktree profile URL, such as https://linktr.ee/linktree. Tracking parameters are ignored.", "schema": { "description": "The creator's Linktree profile URL, such as https://linktr.ee/linktree. Tracking parameters are ignored.", "type": "string" }, "example": "https://linktr.ee/miguelangeles" } ], "responses": { "200": { "description": "A public Linktree profile, its link cards and listed social accounts.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "const": true, "description": "Always true here; errors have `success: false`." }, "credits_remaining": { "type": "number", "description": "Your balance after this call. On anonymous playground calls: free tries left today." }, "credits_charged": { "type": "number", "description": "Credits this call cost; 0 on free endpoints. On anonymous playground calls: tries used (1)." }, "id": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991, "description": "Linktree account id." }, "username": { "type": "string", "description": "The profile's Linktree username." }, "pageTitle": { "type": "string", "description": "Profile title; the username when no title is set." }, "profilePictureUrl": { "description": "Profile picture URL; null when no picture is set.", "type": [ "string", "null" ] }, "description": { "description": "Profile bio as plain text; null when none is set.", "type": [ "string", "null" ] }, "verticals": { "type": "array", "items": { "type": "string" }, "description": "Creator categories selected on Linktree, such as music or internet-technology." }, "linkPlatforms": { "type": "array", "items": { "type": "string" }, "description": "Social platform labels provided by Linktree, in the source order." }, "timezone": { "description": "Account timezone reported by the public page; null when absent.", "type": [ "string", "null" ] }, "links": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991, "description": "Link card id." }, "type": { "type": "string", "description": "Linktree card type, such as CLASSIC, HEADER or YOUTUBE_VIDEO." }, "title": { "description": "Link card title; null if none is set.", "type": [ "string", "null" ] }, "url": { "description": "Public destination URL; null for locked cards or cards without an outgoing URL.", "type": [ "string", "null" ] }, "thumbnailUrl": { "description": "Card thumbnail URL; null when none is set.", "type": [ "string", "null" ] }, "locked": { "type": "boolean", "description": "Linktree marks this card as locked; its destination is withheld." } }, "required": [ "id", "type", "title", "url", "thumbnailUrl", "locked" ], "additionalProperties": false }, "description": "Public top-level link cards in page order; embedded product details and nested collection contents are not returned." }, "socialLinks": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "description": "Linktree's social type, such as INSTAGRAM, TIKTOK or EMAIL_ADDRESS." }, "url": { "type": "string", "description": "The social destination or mailto URL listed on the profile." } }, "required": [ "type", "url" ], "additionalProperties": false }, "description": "Listed social destinations in their displayed order." }, "instagram": { "description": "Public Instagram social link; null if the profile does not list one.", "type": [ "string", "null" ] }, "tiktok": { "description": "Public TikTok social link; null if the profile does not list one.", "type": [ "string", "null" ] }, "spotify": { "description": "Public Spotify social link; null if the profile does not list one.", "type": [ "string", "null" ] }, "youtube": { "description": "Public YouTube social link; null if the profile does not list one.", "type": [ "string", "null" ] }, "soundcloud": { "description": "Public SoundCloud social link; null if the profile does not list one.", "type": [ "string", "null" ] }, "apple_music": { "description": "Public Apple Music social link; null if the profile does not list one.", "type": [ "string", "null" ] }, "email_address": { "description": "Email address from the public EMAIL_ADDRESS social link, without mailto or query parameters; null when none is listed.", "type": [ "string", "null" ] } }, "required": [ "success", "credits_remaining", "credits_charged", "id", "username", "pageTitle", "profilePictureUrl", "description", "verticals", "linkPlatforms", "timezone", "links", "socialLinks", "instagram", "tiktok", "spotify", "youtube", "soundcloud", "apple_music", "email_address" ], "additionalProperties": false } } } }, "403": { "description": "not_public: The platform confirmed this account or content isn't available to logged-out visitors. Use a publicly visible target.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "not_found: The endpoint, or the thing you asked for (ad, post, subreddit), doesn't exist. Charged when the platform was checked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error. Not charged, except the endpoint's own 4xx answers such as not_found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/account/credit-balance": { "get": { "operationId": "account_credit_balance", "tags": [ "Account" ], "summary": "Credit balance", "description": "Your credit balance and daily top-up. Free.\n\nUse it to check your balance before a batch of calls. It's free; every other response also carries `credits_remaining`.\n\nOnce a UTC day, a balance below 25 credits is topped up to 25 on your first call. With a playground token instead of a key, `credits_remaining` is the free tries left today.\n\nCost: Free.", "externalDocs": { "url": "https://lurkapi.com/docs/account/credit-balance" }, "x-credits": 0, "parameters": [], "responses": { "200": { "description": "Your credit balance and daily top-up. Free.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "const": true, "description": "Always true here; errors have `success: false`." }, "credits_remaining": { "type": "number", "description": "Your balance after this call. On anonymous playground calls: free tries left today." }, "credits_charged": { "type": "number", "description": "Credits this call cost; 0 on free endpoints. On anonymous playground calls: tries used (1)." }, "daily_top_up": { "type": "number", "description": "Once a UTC day, a balance below this is topped up to it on your first call." }, "next_top_up_at": { "type": "string", "description": "When the next daily top-up can apply: the coming 00:00 UTC, ISO 8601." } }, "required": [ "success", "credits_remaining", "credits_charged", "daily_top_up", "next_top_up_at" ], "additionalProperties": false } } } }, "default": { "description": "Error. Not charged, except the endpoint's own 4xx answers such as not_found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } }, "components": { "securitySchemes": { "apiKey": { "type": "apiKey", "in": "header", "name": "x-api-key" } }, "schemas": { "Error": { "type": "object", "properties": { "success": { "type": "boolean", "const": false }, "error": { "type": "string", "description": "What went wrong, in plain words." }, "code": { "type": "string", "enum": [ "invalid_params", "missing_api_key", "invalid_api_key", "invalid_token", "insufficient_credits", "not_public", "not_found", "method_not_allowed", "rate_limited", "signup_required", "upstream_error", "upstream_busy", "upstream_timeout", "internal_error" ], "description": "Stable machine-readable code." }, "docs": { "type": "string", "description": "Page that explains how to fix it." }, "issues": { "description": "One entry per invalid parameter (invalid_params only).", "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "success", "error", "code", "docs" ], "additionalProperties": false }, "RedditComment": { "type": "object", "properties": { "id": { "type": "string", "description": "Comment id, e.g. `pcrhmoe`." }, "name": { "type": "string", "description": "Fullname, `t1_` + id." }, "author": { "description": "Username, without u/; null if unknown.", "type": [ "string", "null" ] }, "author_fullname": { "description": "Author's account fullname, `t2_` + id.", "type": [ "string", "null" ] }, "body": { "type": "string", "description": "Comment text, plain." }, "body_html": { "description": "Comment text as HTML; null when the comment has no body.", "type": [ "string", "null" ] }, "score": { "type": "number", "description": "Upvotes minus downvotes." }, "ups": { "type": "number", "description": "Same as score." }, "created": { "type": "number", "description": "Posted at, Unix seconds." }, "created_utc": { "type": "number", "description": "Posted at, Unix seconds." }, "created_at_iso": { "type": "string", "description": "Posted at, ISO 8601." }, "depth": { "type": "number", "description": "0 for top-level comments, 1 for their replies, and so on." }, "parent_id": { "description": "`t3_…` for top-level comments, else the parent comment's `t1_…`.", "type": [ "string", "null" ] }, "link_id": { "description": "The post's fullname.", "type": [ "string", "null" ] }, "permalink": { "type": "string", "description": "Path to this comment on reddit.com." }, "url": { "type": "string", "description": "This comment on reddit.com." }, "subreddit": { "type": "string", "description": "Subreddit name without r/." }, "subreddit_id": { "description": "Subreddit fullname, `t5_` + id.", "type": [ "string", "null" ] }, "subreddit_name_prefixed": { "type": "string", "description": "e.g. `r/marketing`." }, "collapsed": { "type": "boolean", "description": "Collapsed by default on Reddit (low score or moderated)." }, "is_submitter": { "type": "boolean", "description": "Written by the post's author." }, "replies": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/RedditComment" }, "description": "Direct replies, each with its own replies." }, "more": { "type": "object", "properties": { "has_more": { "type": "boolean", "description": "Whether there are more comments to load here." }, "next_cursor": { "description": "Pass as `cursor` (with the same url) to load them; null when has_more is false.", "type": [ "string", "null" ] } }, "required": [ "has_more", "next_cursor" ], "additionalProperties": false, "description": "More comments that weren't loaded yet." } }, "required": [ "items", "more" ], "additionalProperties": false, "description": "Replies to this comment." } }, "required": [ "id", "name", "author", "author_fullname", "body", "body_html", "score", "ups", "created", "created_utc", "created_at_iso", "depth", "parent_id", "link_id", "permalink", "url", "subreddit", "subreddit_id", "subreddit_name_prefixed", "collapsed", "is_submitter", "replies" ], "additionalProperties": false }, "BlueskyReply": { "type": "object", "properties": { "uri": { "type": "string", "description": "The post's `at://` URI, its permanent id." }, "cid": { "type": "string", "description": "Content hash of this version of the post." }, "url": { "type": "string", "description": "The post on bsky.app." }, "text": { "type": "string", "description": "Post text. Empty for media-only posts." }, "createdAt": { "type": "string", "description": "When it was posted, ISO 8601." }, "author": { "type": "object", "properties": { "did": { "type": "string", "description": "The account's permanent id, e.g. `did:plc:z72i7hdynmk6r22z27h6tvur`." }, "handle": { "type": "string", "description": "Handle, e.g. `bsky.app`. It can change; the DID doesn't." }, "displayName": { "description": "Display name; null if not set.", "type": [ "string", "null" ] }, "avatar": { "description": "Avatar image URL; null if none.", "type": [ "string", "null" ] } }, "required": [ "did", "handle", "displayName", "avatar" ], "additionalProperties": false, "description": "Who posted it." }, "replyCount": { "type": "number", "description": "Replies." }, "repostCount": { "type": "number", "description": "Reposts." }, "likeCount": { "type": "number", "description": "Likes." }, "quoteCount": { "type": "number", "description": "Quote posts." }, "bookmarkCount": { "type": "number", "description": "Times saved to bookmarks." }, "langs": { "type": "array", "items": { "type": "string" }, "description": "Languages the author tagged, e.g. `en`." }, "images": { "type": "array", "items": { "type": "object", "properties": { "thumbnail": { "type": "string", "description": "Small image URL." }, "fullsize": { "type": "string", "description": "Full-size image URL." }, "alt": { "type": "string", "description": "Alt text; empty if none." } }, "required": [ "thumbnail", "fullsize", "alt" ], "additionalProperties": false }, "description": "Attached images, in order. Empty if none." }, "video": { "anyOf": [ { "type": "object", "properties": { "playlist": { "type": "string", "description": "HLS playlist (.m3u8) URL." }, "thumbnail": { "description": "Poster image URL; null if none.", "type": [ "string", "null" ] }, "alt": { "description": "Alt text; null if none.", "type": [ "string", "null" ] } }, "required": [ "playlist", "thumbnail", "alt" ], "additionalProperties": false }, { "type": "null" } ], "description": "Attached video; null if none." }, "external": { "anyOf": [ { "type": "object", "properties": { "uri": { "type": "string", "description": "The linked page." }, "title": { "type": "string", "description": "Link card title." }, "description": { "type": "string", "description": "Link card description." }, "thumbnail": { "description": "Link card image URL; null if none.", "type": [ "string", "null" ] } }, "required": [ "uri", "title", "description", "thumbnail" ], "additionalProperties": false }, { "type": "null" } ], "description": "Link card; null if none." }, "quote": { "anyOf": [ { "type": "object", "properties": { "uri": { "type": "string", "description": "The quoted post's `at://` URI. Pass it as `url` to the post endpoint." }, "url": { "type": "string", "description": "The quoted post on bsky.app." }, "text": { "description": "Its text; null when it was deleted or its author blocks viewers.", "type": [ "string", "null" ] }, "createdAt": { "description": "When it was posted, ISO 8601; null when unavailable.", "type": [ "string", "null" ] }, "author": { "anyOf": [ { "type": "object", "properties": { "did": { "type": "string", "description": "The account's permanent id, e.g. `did:plc:z72i7hdynmk6r22z27h6tvur`." }, "handle": { "type": "string", "description": "Handle, e.g. `bsky.app`. It can change; the DID doesn't." }, "displayName": { "description": "Display name; null if not set.", "type": [ "string", "null" ] }, "avatar": { "description": "Avatar image URL; null if none.", "type": [ "string", "null" ] } }, "required": [ "did", "handle", "displayName", "avatar" ], "additionalProperties": false, "description": "Who posted it." }, { "type": "null" } ], "description": "Who posted it; null when unavailable." } }, "required": [ "uri", "url", "text", "createdAt", "author" ], "additionalProperties": false }, { "type": "null" } ], "description": "The post this one quotes; null if none or hidden from logged-out visitors. Embedded lists, feeds and starter packs aren't returned." }, "links": { "type": "array", "items": { "type": "string" }, "description": "Links in the text." }, "mentions": { "type": "array", "items": { "type": "string" }, "description": "Handles mentioned in the text, without @." }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Hashtags in the text, without #." }, "replyTo": { "description": "`at://` URI of the post this replies to; null for top-level posts.", "type": [ "string", "null" ] }, "replies": { "type": "array", "items": { "$ref": "#/components/schemas/BlueskyReply" }, "description": "Replies to this reply." } }, "required": [ "uri", "cid", "url", "text", "createdAt", "author", "replyCount", "repostCount", "likeCount", "quoteCount", "bookmarkCount", "langs", "images", "video", "external", "quote", "links", "mentions", "tags", "replyTo", "replies" ], "additionalProperties": false } } } }