{"openapi":"3.1.0","info":{"title":"ListenX by TagX — Social Listening API","description":"**ListenX by TagX** is a social listening API for pulling public data from\nInstagram, Facebook, TikTok, LinkedIn and Reddit.\n\nThis release covers **Instagram** and **TikTok**:\n\n* `GET /v1/instagram/search` — keyword/hashtag search (Instagram's native\n  relevance search), paginated ~18 posts per page.\n* `GET /v1/instagram/post/{post_id}` — full post/reel details with **all\n  engagement metrics** (likes, comments, shares, saves, and play/view counts).\n* `GET /v1/tiktok/search` — keyword search across videos, users, or hashtags\n  (TikTok's native relevance search), paginated per page.\n* `GET /v1/tiktok/post/{video_id}` — full post details with **all engagement\n  metrics** (plays, likes, comments, shares, saves, and reposts).\n\nAuthenticate every request with your API key in the `X-API-Key` header.\nBilling is metered per account and per endpoint — see `GET /v1/account/pricing`.","contact":{"name":"TagX","url":"https://listenx.tagxdata.com/"},"license":{"name":"Proprietary — ListenX by TagX"},"version":"0.1.0"},"paths":{"/":{"get":{"tags":["Meta"],"summary":"Service banner","operationId":"root__get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/health":{"get":{"tags":["Meta"],"summary":"Liveness probe","operationId":"health_health_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/v1/instagram/search":{"get":{"tags":["Instagram"],"summary":"Search Instagram posts by keyword or hashtag","description":"Search Instagram and return matching posts.\n\nThe query is sent to Instagram's native search, which is relevance-ranked\nand does **not** support boolean operators. Pagination follows Instagram:\none page ≈ 18 posts, and `max_pages` controls how many pages to fetch.\n\nBilling: charged per **page fetched** (1 unit = 1 page).","operationId":"instagram_search_v1_instagram_search_get","security":[{"ListenX API key":[]}],"parameters":[{"name":"query","in":"query","required":true,"schema":{"type":"string","description":"Keyword or hashtag to search, e.g. `#dentist` or `dentist teeth whitening`. Passed to Instagram's native search (relevance-ranked); boolean operators are not supported.","examples":["#dentist","dentist teeth whitening"],"title":"Query"},"description":"Keyword or hashtag to search, e.g. `#dentist` or `dentist teeth whitening`. Passed to Instagram's native search (relevance-ranked); boolean operators are not supported."},{"name":"max_pages","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Number of Instagram pages to fetch (max 100). Each page returns ~18 posts as returned by Instagram. Billed per page fetched.","default":1,"title":"Max Pages"},"description":"Number of Instagram pages to fetch (max 100). Each page returns ~18 posts as returned by Instagram. Billed per page fetched."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/instagram/post/{post_id}":{"get":{"tags":["Instagram"],"summary":"Fetch a single Instagram post with all engagement metrics","description":"Fetch one post/reel by shortcode (e.g. `DcghxSFtjRB`) or URL.\n\nReturns a structured object including every engagement metric we can find —\nlikes, comments, shares/reshares, saves, and **play/view counts for reels**.\n\nBilling: charged per **request** (1 unit).","operationId":"instagram_post_v1_instagram_post__post_id__get","security":[{"ListenX API key":[]}],"parameters":[{"name":"post_id","in":"path","required":true,"schema":{"type":"string","title":"Post Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PostResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/tiktok/search":{"get":{"tags":["TikTok"],"summary":"Search TikTok by keyword (videos, users, or hashtags)","description":"Search TikTok and return matching videos, users, or hashtags.\n\nResults come back in TikTok's own relevance order, deduplicated across\npages. Billing: charged per **page fetched** (1 unit = 1 page).","operationId":"tiktok_search_v1_tiktok_search_get","security":[{"ListenX API key":[]}],"parameters":[{"name":"query","in":"query","required":true,"schema":{"type":"string","description":"Keyword to search on TikTok's native web search (relevance-ranked). Boolean operators are not supported.","examples":["dental care","looksmaxxing"],"title":"Query"},"description":"Keyword to search on TikTok's native web search (relevance-ranked). Boolean operators are not supported."},{"name":"type","in":"query","required":false,"schema":{"type":"string","description":"Search vertical: `video` (default), `user`, or `hashtag`.","default":"video","title":"Type"},"description":"Search vertical: `video` (default), `user`, or `hashtag`."},{"name":"count","in":"query","required":false,"schema":{"type":"integer","maximum":30,"minimum":1,"description":"Results requested per TikTok page (max 30).","default":20,"title":"Count"},"description":"Results requested per TikTok page (max 30)."},{"name":"max_pages","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Number of TikTok pages to fetch (max 100). Billed per page fetched.","default":1,"title":"Max Pages"},"description":"Number of TikTok pages to fetch (max 100). Billed per page fetched."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TikTokSearchResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/tiktok/post/{video_id}":{"get":{"tags":["TikTok"],"summary":"Fetch a single TikTok post with all engagement metrics","description":"Fetch one TikTok post by numeric video id or URL.\n\nReturns a structured object including every engagement metric TikTok exposes\n— plays, likes (diggs), comments, shares, saves (collects), and reposts.\n\nBilling: charged per **request** (1 unit).","operationId":"tiktok_post_v1_tiktok_post__video_id__get","security":[{"ListenX API key":[]}],"parameters":[{"name":"video_id","in":"path","required":true,"schema":{"type":"string","title":"Video Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TikTokPostResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/account/me":{"get":{"tags":["Account"],"summary":"Current account & credit balance","operationId":"me_v1_account_me_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}},"security":[{"ListenX API key":[]}]}},"/v1/account/pricing":{"get":{"tags":["Account"],"summary":"Your effective per-endpoint pricing","operationId":"pricing_v1_account_pricing_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}},"security":[{"ListenX API key":[]}]}},"/v1/account/usage":{"get":{"tags":["Account"],"summary":"Recent usage / billing history","operationId":"usage_v1_account_usage_get","security":[{"ListenX API key":[]}],"parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":500,"minimum":1,"default":50,"title":"Limit"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}},"components":{"schemas":{"Author":{"properties":{"id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Id"},"username":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Username"},"full_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Full Name"},"is_verified":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Is Verified"}},"type":"object","title":"Author"},"BillingInfo":{"properties":{"endpoint":{"type":"string","title":"Endpoint"},"units":{"type":"integer","title":"Units"},"unit_price":{"type":"string","title":"Unit Price"},"amount":{"type":"string","title":"Amount"},"balance_after":{"type":"string","title":"Balance After"},"request_id":{"type":"string","title":"Request Id"}},"type":"object","required":["endpoint","units","unit_price","amount","balance_after","request_id"],"title":"BillingInfo"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"PostEngagement":{"properties":{"like_count":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Like Count"},"comment_count":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Comment Count"},"play_count":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Play Count"},"ig_play_count":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Ig Play Count"},"view_count":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"View Count"},"views":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Views"},"reshare_count":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Reshare Count"},"share_count":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Share Count"},"save_count":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Save Count"},"fb_like_count":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Fb Like Count"},"fb_play_count":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Fb Play Count"},"top_likers":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Top Likers"},"like_and_view_counts_disabled":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Like And View Counts Disabled"},"comments_disabled":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Comments Disabled"}},"type":"object","title":"PostEngagement"},"PostResponse":{"properties":{"id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Id"},"shortcode":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Shortcode"},"url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Url"},"type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Type"},"product_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Product Type"},"is_video":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Is Video"},"taken_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Taken At"},"caption":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Caption"},"hashtags":{"items":{"type":"string"},"type":"array","title":"Hashtags"},"mentions":{"items":{"type":"string"},"type":"array","title":"Mentions"},"accessibility_caption":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Accessibility Caption"},"author":{"type":"object","title":"Author"},"coauthors":{"items":{"type":"object"},"type":"array","title":"Coauthors"},"location":{"anyOf":[{"type":"object"},{"type":"null"}],"title":"Location"},"music":{"anyOf":[{"type":"object"},{"type":"null"}],"title":"Music"},"engagement":{"$ref":"#/components/schemas/PostEngagement"},"media":{"type":"object","title":"Media"},"tagged_users":{"items":{"type":"object"},"type":"array","title":"Tagged Users"},"billing":{"$ref":"#/components/schemas/BillingInfo"}},"type":"object","required":["author","engagement","media","billing"],"title":"PostResponse"},"SearchEngagement":{"properties":{"like_count":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Like Count"},"comment_count":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Comment Count"},"play_count":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Play Count"},"view_count":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"View Count"}},"type":"object","title":"SearchEngagement"},"SearchResponse":{"properties":{"query":{"type":"string","title":"Query"},"pages_requested":{"type":"integer","title":"Pages Requested","description":"Pages requested (max_pages)."},"pages_fetched":{"type":"integer","title":"Pages Fetched","description":"Instagram pages actually fetched (also the billed unit count)."},"returned":{"type":"integer","title":"Returned","description":"Number of posts returned (deduplicated across pages)."},"results":{"items":{"$ref":"#/components/schemas/SearchResult"},"type":"array","title":"Results"},"billing":{"$ref":"#/components/schemas/BillingInfo"}},"type":"object","required":["query","pages_requested","pages_fetched","returned","results","billing"],"title":"SearchResponse"},"SearchResult":{"properties":{"id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Id"},"shortcode":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Shortcode"},"url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Url"},"type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Type"},"taken_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Taken At"},"caption":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Caption"},"author":{"$ref":"#/components/schemas/Author"},"engagement":{"$ref":"#/components/schemas/SearchEngagement"},"thumbnail_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Thumbnail Url"}},"type":"object","required":["author","engagement"],"title":"SearchResult"},"TikTokPostResponse":{"properties":{"id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Id"},"url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Url"},"type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Type"},"desc":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Desc"},"created_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Created At"},"hashtags":{"items":{"type":"string"},"type":"array","title":"Hashtags"},"mentions":{"items":{"type":"string"},"type":"array","title":"Mentions"},"author":{"anyOf":[{"type":"object"},{"type":"null"}],"title":"Author"},"engagement":{"anyOf":[{"type":"object"},{"type":"null"}],"title":"Engagement"},"music":{"anyOf":[{"type":"object"},{"type":"null"}],"title":"Music"},"media":{"anyOf":[{"type":"object"},{"type":"null"}],"title":"Media"},"challenges":{"items":{"type":"object"},"type":"array","title":"Challenges"},"is_ad":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Is Ad"},"region":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Region"},"metadata":{"anyOf":[{"type":"object"},{"type":"null"}],"title":"Metadata"},"billing":{"$ref":"#/components/schemas/BillingInfo"}},"type":"object","required":["billing"],"title":"TikTokPostResponse"},"TikTokSearchResponse":{"properties":{"query":{"type":"string","title":"Query"},"type":{"type":"string","title":"Type","description":"Search vertical: video | user | hashtag."},"pages_requested":{"type":"integer","title":"Pages Requested","description":"Pages requested (max_pages)."},"pages_fetched":{"type":"integer","title":"Pages Fetched","description":"TikTok pages actually fetched (also the billed unit count)."},"returned":{"type":"integer","title":"Returned","description":"Number of results returned (deduplicated across pages)."},"results":{"items":{"type":"object"},"type":"array","title":"Results"},"billing":{"$ref":"#/components/schemas/BillingInfo"}},"type":"object","required":["query","type","pages_requested","pages_fetched","returned","results","billing"],"title":"TikTokSearchResponse"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}},"securitySchemes":{"ListenX API key":{"type":"apiKey","description":"Your ListenX API key (e.g. lx_live_...).","in":"header","name":"X-API-Key"}}}}