--- name: api.portalsprotocol.com description: api.portalsprotocol.com provides social media data retrieval across TikTok, Twitter/X, Reddit, and Instagram. It supports user profile lookups, video/tweet fetching by user or keyword, hashtag-based video retrieval, and subreddit discovery. All endpoints return structured metadata and engagement metrics for downstream analysis. host: api.portalsprotocol.com --- # api.portalsprotocol.com Portals Protocol is a multi-platform social data API serving agents that need to query public content and profile metadata across TikTok, Twitter/X, Instagram, and Reddit in a single integration. It covers the most common read-side social intelligence tasks: profile resolution, content search, user feed retrieval, and community discovery. It does not provide write operations, real-time streaming, private account data, or aggregate platform-level analytics. ## When to use this host Use this host when an agent needs structured public social data from TikTok, Twitter/X, Instagram, or Reddit without building separate integrations per platform. It is well-suited for influencer research, content trend analysis, community discovery, and cross-platform profile comparison. Do not use it for real-time streaming or webhook-based tweet/video feeds; use Twitter's Filtered Stream API or TikTok's live APIs instead. Do not use it for private account data, write operations (posting, liking, following), aggregate hashtag-level statistics, or fetching a specific tweet by ID. Reddit subscriber counts are unreliable from this host (returns 0). For financial or crypto-specific social signals, a dedicated on-chain or crypto-social API would be more appropriate. ## Capabilities ### Profile & Account Lookup Resolves public user profiles on Twitter/X and Instagram, returning structured account metadata such as follower counts, bios, verification status, and account timestamps. - **`fetch-twitter-user-profile`** — Returns a public Twitter/X user profile including ID, display name, bio, location, follower/following counts, verification status, and account timestamps for a given username. - **`fetch-instagram-profile`** — Fetches public Instagram profile data for a given username, including bio, follower/following counts, post count, avatar URL, and verification status. ### User Content Retrieval Fetches recent content posted by a specific user on TikTok or Twitter/X, including per-item engagement metrics and author metadata. - **`fetch-tiktok-user-videos`** — Fetches a TikTok user's videos and associated metadata including engagement metrics, author info, hashtags, and music details. - **`fetch-twitter-tweets`** — Fetches recent public tweets for a given Twitter/X username, returning tweet text, metrics, author info, and URLs via a paid Solana-based API. ### Keyword & Topic Search Searches TikTok and Twitter/X for content matching a query string, returning ranked video or tweet results with engagement data and author details. - **`search-tiktok-videos`** — Searches TikTok and returns a list of matching videos with metadata including engagement metrics, author info, hashtags, and music details. - **`search-twitter-content`** — Searches Twitter for tweets matching a query string and returns structured tweet objects with text, author, metrics, and timestamps. ### Hashtag & Community Discovery Surfaces TikTok videos associated with a specific hashtag and discovers Reddit subreddits matching a keyword, enabling topic-level content and community mapping. - **`fetch-tiktok-hashtag-videos`** — Returns a list of TikTok videos tagged with a given hashtag, including per-video play/like/comment/share/save counts, author profile, and post URL. - **`search-reddit-communities`** — Searches Reddit communities (subreddits) by keyword query and returns matching community metadata including title, description, and creation date. ## Workflows ### Cross-Platform Influencer Profile Check *Use when an agent needs to assess a creator's public presence across multiple platforms given a known username.* 1. **`fetch-twitter-user-profile`** — Resolve the Twitter/X username to get follower count, verification status, and bio. 2. **`fetch-instagram-profile`** — Resolve the same or equivalent Instagram username to get follower count, post count, and bio for comparison. 3. **`fetch-tiktok-user-videos`** — Retrieve the user's TikTok video feed to gauge posting frequency and aggregate engagement metrics. ### Topic Trend Mapping *Use when an agent needs to understand how a topic or keyword is performing across TikTok and Twitter/X simultaneously.* 1. **`search-twitter-content`** — Search Twitter/X for recent tweets matching the topic to capture text-based discourse and engagement. 2. **`search-tiktok-videos`** — Search TikTok for videos matching the same topic to capture video-format engagement and author reach. 3. **`fetch-tiktok-hashtag-videos`** — Retrieve TikTok videos under the topic's primary hashtag to surface additional content not caught by keyword search. ### Reddit Community Discovery to Twitter Validation *Use when an agent needs to find active communities around a niche topic and then verify whether key figures in those communities have a Twitter/X presence.* 1. **`search-reddit-communities`** — Search Reddit for subreddits related to the topic to identify community names and descriptions. 2. **`search-twitter-content`** — Search Twitter/X using the subreddit name or topic keywords to find related discourse and prominent accounts. 3. **`fetch-twitter-user-profile`** — Look up identified Twitter/X accounts to confirm follower counts and account legitimacy. ## Skill reference ### `fetch-tiktok-user-videos` **TikTok User Videos** — Fetches a TikTok user's videos and associated metadata including engagement metrics, author info, hashtags, and music details. *Use when:* Use when an agent needs to retrieve a list of TikTok videos posted by a specific username, along with per-video play/like/comment/share/save counts and author metadata. *Not for:* Do not use for searching TikTok content by keyword or hashtag; this endpoint is scoped to a single user's video feed only. **Inputs:** - `username` (string, required) — TikTok username whose videos should be fetched. - `limit` (integer) — Maximum number of videos to return per request. - `cursor` (string) — Pagination cursor for fetching the next page of results; pass null for the first page. - `include_metadata` (boolean) — Whether to include additional metadata fields in the response. **Returns:** Returns a videos array where each element contains the video caption, engagement metrics (plays, likes, comments, shares, saves), author info (id, username, nickname, verified, followers), hashtags, and music metadata. **Example:** `{"username": "vitalikbuterin", "limit": 12, "cursor": null, "include_metadata": true}` --- ### `fetch-twitter-user-profile` **Twitter User Lookup** — Returns a public Twitter/X user profile including ID, display name, bio, location, follower/following counts, verification status, and account timestamps for a given username. *Use when:* Use when an agent needs to resolve a Twitter/X username to structured profile metadata such as follower count, verification status, account creation date, or bio text. *Not for:* Do not use for fetching tweets, timelines, or engagement metrics; use a tweet search or timeline API instead. Not suitable for private or suspended accounts. **Inputs:** - `username` (string, required) — Twitter/X username (handle without @) to look up. **Returns:** Returns a user object with numeric ID, handle, display name, bio, location, follower/following counts, Blue verification status, account creation timestamp, tweet count, and media count. **Example:** `{"username": "vitalikbuterin"}` --- ### `search-reddit-communities` **Reddit Communities Search** — Searches Reddit communities (subreddits) by keyword query and returns matching community metadata including title, description, and creation date. *Use when:* Use when an agent needs to discover relevant Reddit subreddits for a given topic, keyword, or interest area, especially to surface community names, descriptions, and metadata for further analysis or linking. *Not for:* Do not use for fetching posts, comments, or user data within a subreddit; use a Reddit posts or content API instead. Not suitable for real-time subscriber counts as the API returns 0 for all communities. **Inputs:** - `query` (string, required) — Search term used to find matching Reddit communities. - `sort` (string) — Sort order for results. Known value: 'relevance'. - `limit` (integer) — Maximum number of communities to return per page. - `cursor` (string) — Pagination cursor for fetching the next page of results. Pass null for the first page. - `include_nsfw` (boolean) — Whether to include NSFW communities in results. - `subreddit_type` (string) — Filter by subreddit visibility type. Known value: 'public'. **Returns:** Returns a communities array where each entry contains the subreddit id, t5_-prefixed name, title, description, subscribers (always 0), isNSFW flag, and createdAt timestamp. **Example:** `{"query": "ethereum staking", "sort": "relevance", "limit": 25, "cursor": null, "include_nsfw": false, "subreddit_type": "public"}` --- ### `fetch-twitter-tweets` **Twitter Tweets Fetcher** — Fetches recent public tweets for a given Twitter/X username, returning tweet text, metrics, author info, and URLs via a paid Solana-based API. *Use when:* Use when an agent needs to retrieve recent tweets from a specific Twitter/X user, including engagement metrics (likes, retweets, views, replies) and author metadata. *Not for:* Do not use for real-time streaming tweet feeds or keyword/hashtag search queries; this endpoint is suited for user timeline retrieval. **Inputs:** - `username` (string, required) — Twitter/X username (without @) whose tweets should be fetched. - `query_type` (string, required) — Type of query to perform. Use 'user' to fetch tweets from a specific user's timeline. - `sort` (string) — Sort order for returned tweets. Use 'recent' to get the most recent tweets first. - `limit` (integer) — Maximum number of tweets to return in the response. **Returns:** Returns a tweets array where each item includes tweet id, url, full text, createdAt timestamp, language, engagement metrics (retweets/replies/likes/views), isReply flag, and an author object with username, display name, verification status, and follower count. **Example:** `{"username": "vitalikbuterin", "query_type": "user", "sort": "recent", "limit": 10}` --- ### `search-tiktok-videos` **Portals TikTok Search** — Searches TikTok and returns a list of matching videos with metadata including engagement metrics, author info, hashtags, and music details. *Use when:* Use when an agent needs to find TikTok videos matching a keyword or topic query, and requires structured data such as play counts, likes, comments, shares, author follower counts, and associated hashtags. *Not for:* Do not use for searching TikTok users or hashtags directly; this endpoint returns video results only. Not suitable for real-time trending feeds or live streaming data. **Inputs:** - `query` (string, required) — Search query string used to find matching TikTok videos. - `limit` (integer) — Maximum number of video results to return. **Returns:** Returns a videos array where each item includes the video ID, URL, caption text, creation timestamp, engagement metrics (plays, likes, comments, shares, saves), music info, author profile, and hashtags. **Example:** `{"query": "solana defi", "limit": 10}` --- ### `search-twitter-content` **Portals Twitter Search** — Searches Twitter for tweets matching a query string and returns structured tweet objects with text, author, metrics, and timestamps. *Use when:* Use when an agent needs to retrieve recent or relevant tweets for a given topic, keyword, or hashtag, including author details and engagement metrics, to inform analysis or display. *Not for:* Do not use for real-time streaming tweet feeds or for fetching a specific tweet by ID; this is a query-based batch search returning up to a limited number of results per call. **Inputs:** - `query` (string, required) — Search query string (keywords, hashtags, or phrases) to match against tweets. - `sort` (string) — Sort order for results. Known value: 'relevance'. - `limit` (integer) — Maximum number of results to return. - `include` (object) — Object specifying which content types to include in results. Fields: users (boolean), tweets (boolean), threads (boolean). - `language` (string) — ISO 639-1 language code to filter results by language. **Returns:** Returns a tweets array where each element contains the tweet id, url, text, createdAt timestamp, lang, isReply flag, engagement metrics (retweets/replies/likes/views), and an author object with userName, name, isBlueVerified, followers, description, and location. **Example:** `{"query": "solana defi", "sort": "relevance", "limit": 10, "include": {"users": true, "tweets": true, "threads": true}, "language": "en"}` --- ### `fetch-tiktok-hashtag-videos` **TikTok Hashtag Insights** — Returns a list of TikTok videos tagged with a given hashtag, including per-video play/like/comment/share/save counts, author profile, and post URL. *Use when:* Use when an agent needs to retrieve recent or trending TikTok videos associated with a specific hashtag, including engagement metrics and author details for content research or trend analysis. *Not for:* Do not use for aggregate hashtag-level statistics (total views, total posts for a tag); this returns individual video records, not rolled-up hashtag summary data. **Inputs:** - `tag` (string, required) — The TikTok hashtag to look up, without the leading # symbol. **Returns:** Returns a videos array where each element contains the video ID, URL, caption, createdAt timestamp, engagement metrics (plays/likes/comments/shares/saves), music info, author profile with follower count, and associated hashtags. **Example:** `{"tag": "viral"}` --- ### `fetch-instagram-profile` **IG Profile Lookup** — Fetches public Instagram profile data for a given username, including bio, follower/following counts, post count, avatar URL, and verification status. *Use when:* Use when an agent needs to look up a public Instagram profile by username to retrieve account metadata such as follower counts, bio, profile picture, or privacy status. *Not for:* Do not use for private accounts (isPrivate=true profiles will not return full data). Not suitable for fetching post content, stories, or real-time engagement metrics. **Inputs:** - `username` (string, required) — Instagram username to look up (without the @ symbol). **Returns:** Returns a profile object with id, username, fullName, bio, url, externalUrl, verified, isPrivate, followers, following, posts, and profilePicUrl fields. **Example:** `{"username": "vitalikbuterin"}` ---