gentic

Gentic Social — Documentation

Give any AI agent the public TikTok posts of any profile — captions, like, comment and view counts, post URLs and dates. Point it at a list of competitor or creator handles and it pulls their recent posts, so you can see what they're publishing and what's landing — or search TikTok for a keyword, phrase or #hashtag to find every public video talking about it, whoever made it. No account to connect: Gentic fetches the public data for you, and you pay only for the posts delivered.

1. Getting Started

Sign Up & Get Your API Key

Before you can use Gentic Social, you need an API key to authenticate your requests.

  1. Go to gentic.co/social and create an account.
  2. Create an organization from your dashboard. API keys and billing are scoped to the organization.
  3. Generate an API key and use it as a Bearer token in your MCP client.

2. Connecting to the MCP Server

The server is available at https://mcp.gentic.co/social. For Claude Code:

claude mcp add gentic-social \
  --transport http \
  https://mcp.gentic.co/social \
  --header "Authorization: Bearer YOUR_API_KEY"

For Claude Web and ChatGPT you can also connect via OAuth — no API key needed. See the connect section on the landing page for other MCP clients (n8n, OpenClaw).

3. Agent Skill

For the best results, pair the MCP server with the Gentic Social agent skill. The MCP server gives your agent tool access; the skill teaches it the optimal workflow order. Both the raw SKILL.md and a ready-to-upload .skill bundle are generated on demand from the live manifest, so they always reflect the current tools and pricing.

Add the skill directly via URL:

https://gentic.co/social/SKILL.md

Or upload a .skill bundle to Claude Managed Agents:

https://gentic.co/social/gentic-social.skill

Download this file and upload it wherever Claude Managed Agents asks for a .skill file. It's a zip bundle generated on demand from the latest SKILL.md.

4. Tool Reference

2 tools, rendered live from the Gentic MCP manifest. Parameter tables come directly from each tool's JSON Schema.

get_tiktok_posts

1¢ / result

Get recent posts for one or more TikTok profiles — captions, like/comment/view counts, post URLs and dates. Accepts profile URLs or bare handles (@nike or nike). Runs asynchronously: the first call returns a job_id, then call again with that job_id to collect the posts (typically ready in 1-3 minutes). Billed per post delivered; a call that returns no posts is not billed.

ParameterTypeDescription
urlsstring[]

TikTok profiles to fetch, as full profile URLs or bare handles. 1-20 per call. Required unless you are continuing with job_id.

num_of_postsinteger

Recent posts to fetch per profile. Default 10, max 50.

1 – 50

sincestring

Only return posts published on or after this ISO date (filtered after fetch).

job_idstring

Continue a job started by an earlier call. Pass the job_id you were given; omit urls.

social_search_posts

1¢ / result

Social listening on TikTok or Instagram: find public posts matching a keyword, phrase or #hashtag, whoever made them. Returns caption, likes, comments, views, URL, date, the author's @handle and which query matched. Ordering depends on where you search: TikTok is ranked by relevance, NOT newest-first; an Instagram #hashtag returns the newest posts first (mostly images); an Instagram phrase returns top/relevant reels. `since` only trims what was fetched, so for recent coverage raise num_of_posts rather than narrowing since (on Instagram, search a #hashtag). The stored raw record also keeps comments, queryable later: up to 20 top comments per TikTok video, about 10 latest per Instagram phrase result. TikTok is asynchronous: the first call returns a job_id; call again with it to collect results (typically 3-10 minutes). Instagram returns the posts in the first call, usually within seconds, and its job_id re-reads the same results. matched_input_url is always null here. Billed per distinct post delivered; nothing found, nothing billed.

ParameterTypeDescription
platformstring

Where to search: "tiktok" (default) or "instagram". On Instagram a query starting with # searches that hashtag (newest first); anything else searches by keyword (top reels).

enum: tiktok, instagram

queriesstring[]

Keywords, phrases, brand names or #hashtags to search for. 1-10 per call. On Instagram, a hashtag is one word and the only punctuation allowed is a leading #. Required unless you are continuing with job_id.

num_of_postsinteger

Posts to fetch per query. Default 20, max 50.

1 – 50

sincestring

Only return posts published on or after this ISO date. Filtered after fetch, so it can return far fewer than num_of_posts.

job_idstring

Continue a job started by an earlier call. Pass the job_id you were given; omit queries.

5. Pricing

Pricing is pulled live from the Gentic MCP manifest. All prices are per call and deducted from your Gentic credits.

ToolCost
get_tiktok_posts1¢ / result
social_search_posts1¢ / result

6. Notes

  • No connection needed: public TikTok data is fetched through Gentic's own account. No credential is ever passed to the tools.
  • Async: the first call returns a `job_id`; call the same tool again with it (and no `urls` or `queries`) to collect the posts — typically 1–3 minutes for `get_tiktok_posts`, 3–5 for `social_search_posts`.
  • Cost: billed per post delivered (per distinct video for `social_search_posts`); a call that returns no posts, a failed job, or a still-pending check is not billed. Pricing is pulled live from the Gentic MCP manifest.
  • `since` filters after the fetch: it can't return posts older than the `num_of_posts` most recent ones per profile.
  • `social_search_posts` is relevance-ranked, not newest-first: `since` only trims what was fetched, so raise `num_of_posts` for recent coverage rather than narrowing `since`.
  • Posts land in `social_posts` under the pull's `job_id`; repeated pulls of the same profile add rows rather than replacing them.

7. When to Apply

  • User wants to see what a competitor, creator, or brand has recently posted on TikTok.
  • User wants like, comment, or view counts for a TikTok profile's recent posts.
  • User wants to compare several TikTok profiles' recent posts or engagement.
  • User wants TikTok posts published since a given date for a list of profiles.
  • User wants to find TikTok videos about a keyword, phrase, brand name or #hashtag, from any account (social listening).
  • User wants to know who on TikTok is talking about their brand, product or category.
  • User wants to analyze TikTok posts already collected, with query_data over social_posts.

8. Workflow

  1. 1. No connection needed

    The Social server fetches public data through Gentic's own account, so there is nothing for the user to connect and no credential to pass. Don't send the user to the dashboard for TikTok.

  2. 2. Watch competitors with `get_tiktok_posts`

    `get_tiktok_posts` gets recent posts for one or more TikTok profiles — captions, like/comment/view counts, post URLs and dates. Pass `urls`: profile URLs or bare handles (`@nike` or `nike`), 1–20 per call. `num_of_posts` sets how many recent posts per profile (default 10, max 50), and `since` keeps only posts published on or after an ISO date — it is applied after the fetch, so it narrows what you get back rather than reaching further into the past. It is billed per post delivered, and a call that returns no posts is not billed.

  3. 3. Collect the posts with the `job_id`

    It runs asynchronously. The first call returns `{ status: 'pending', job_id }`; call `get_tiktok_posts` again with only that `job_id` (omit `urls`) to collect the posts — typically ready in 1–3 minutes. While the job is still running the answer is `status: 'pending'`: wait a minute and call again. `status: 'ready'` returns `records_returned` and `posts` (`platform`, `profile_url`, `matched_input_url`, `post_url`, `posted_at`, `caption`, `likes`, `comments`, `views`). `status: 'failed'` means the scrape did not complete and nothing was billed — say so rather than retrying in a loop.

  4. 4. Listen for a keyword or #hashtag with `social_search_posts`

    `social_search_posts` is social listening on TikTok: it finds public videos matching a keyword, phrase or #hashtag, whoever made them, and returns the caption, likes, comments, views, URL, date, the author's @handle and which query matched. Pass `queries`: keywords, phrases, brand names or #hashtags, 1–10 per call (each up to 100 characters). A `#hashtag` is a search, not a tag filter. `num_of_posts` is per query (default 20, max 50). Results are ranked by relevance, NOT newest-first, and `since` only trims what was fetched — so it can return far fewer than `num_of_posts`. For recent coverage, raise `num_of_posts` rather than narrowing `since`. It runs asynchronously the same way: the first call returns `{ status: 'pending', job_id }`; call `social_search_posts` again with only that `job_id` (omit `queries`) — typically ready in 3–5 minutes. A `job_id` only continues with the tool that started it. `status: 'ready'` returns `queries_requested`, `records_returned` and `posts` with the same fields as `get_tiktok_posts` plus `search_query` (the query that found it) and `author` (the @handle); `matched_input_url` is always null here. A video found by several queries is returned and billed once, attributed to the query listed first. It is billed per distinct video delivered; nothing found, nothing billed.

  5. 5. Analyze with `query_data` over `social_posts`

    Delivered posts are also stored in the org's `social_posts` table (`job_id`, `platform`, `profile_url`, `post_url`, `posted_at`, `caption`, `likes`, `comments`, `views`, `search_query`, `author`, `raw`, `scraped_at`), so you can compare profiles, rank posts by views, track a competitor over several pulls, or see which authors keep turning up for a keyword with `query_data` instead of fetching again. `search_query` is null for profile pulls. `raw` keeps the full source record; for keyword searches it includes up to 20 top comments per video, so you can read what people are saying without paying for another search. Each pull adds rows under its own `job_id`, so a profile or query fetched twice appears twice — filter by the latest `scraped_at` or dedupe on `post_url` when counting.

  6. 6. Present results clearly

    Don't dump raw JSON. Lead with the answer — which profiles posted what, which posts drew the most views or engagement — and link the `post_url`s. Say which date range and how many posts per profile the numbers cover. For keyword searches, say the results are the most relevant matches TikTok returned, not every post — never present them as a complete count of mentions.