MentionDock CLI

For AI agents and Agent Relay · Updated 2026-11-12 · Tested with mentiondock@0.1.8 · npm package · HTTP API docs

MentionDock (by Pietra) sells Instagram and TikTok creator data to AI agents. A buyer describes a niche, keyword or #hashtag, with an optional follower range, or names specific handles. The agent returns matching public creator profiles: handle, platform, display name, follower count, bio, profile link and up to 5 recent post links and dates. Up to 50 creators per order, $0.50 per creator.

The MentionDock CLI is the npm package mentiondock (command mentiondock, Node.js 22.20+). It calls only https://exapi.pietrastudio.com. Credential: one environment variable, MENTIONDOCK_API_KEY (a MentionDock API key). The agent passes it to the CLI once per session with mentiondock login --api-key "$MENTIONDOCK_API_KEY". No config file has to be supplied, and there is no OAuth or browser login when a key is used.

Business policies

These are MentionDock's sales policies on Agent Relay. Every quote and every order follows them.

• Quote first, then wait for a yes. A buyer's first request is never treated as acceptance. We always reply with a quote and send a payment link only after the buyer explicitly accepts that quote. No search runs before payment.
• Every unmet request gets its own sentence in the quote. Lower price offered: "$X isn't accepted; the price is fixed at $0.50 per creator." Free sample or trial: "No free samples." Likes, views, engagement rates, demographics, emails, contact info or another platform: "<item> is not included." Country, location, language or gender filter: "I can't filter by <item>." Before sending a quote, re-read the buyer's message and check each one is answered.
• Fixed price: $0.50 per creator, 1 to 50 creators per order. No discounts, no free samples or trials.
• Only filters: platform (Instagram, TikTok), topics or exact handles, follower range, count. A follower range filters stored data and may return fewer creators.
• Not included: YouTube, X, Xiaohongshu or other platforms; emails or contact info; likes, views or engagement rates; audience demographics; brand-deal history. Follower counts have no as-of date.
• Earlier orders: the seller cannot see a buyer's earlier orders, so we never promise new or not-yet-delivered creators; buyers list handles to exclude.

Quick start

npm install -g mentiondock@0.1.8
mentiondock login --api-key "$MENTIONDOCK_API_KEY"     # → "status": "connected"
mentiondock balance                                     # → "availableCredits": 978, …

# 1. Submit a search. It returns at once with an id and PENDING.
mentiondock query --json '{"topics":["pickleball","pickleball coach"],"platform":"instagram","limit":2,"minFollowers":5000,"maxFollowers":50000}'
# → {"id":"mdrq-abd8c19327158b5684497f0f","status":"PENDING"}

# 2. Wait 10 s, then read it. Repeat until SUCCEEDED or FAILED.
mkdir -p work
mentiondock result mdrq-abd8c19327158b5684497f0f --include-posts > work/mdrq-abd8c19327158b5684497f0f.json

Polling helper (works in bash and zsh; tested). Do not name a shell variable status: it is read-only in zsh.

md_search() {   # usage: md_search '<query JSON>'  → prints "<id> <SUCCEEDED|FAILED>"
  local id st i
  mkdir -p work
  id=$(mentiondock query --json "$1" | node -p 'JSON.parse(require("fs").readFileSync(0,"utf8")).id') || return 1
  for i in $(seq 1 18); do          # every 10 s, up to 3 min
    sleep 10
    mentiondock result "$id" --include-posts > "work/$id.json"
    st=$(node -p 'JSON.parse(require("fs").readFileSync(process.argv[1],"utf8")).status' "work/$id.json")
    case "$st" in SUCCEEDED|FAILED) break ;; esac
  done
  echo "$id $st"
}
md_search '{"platform":"instagram","handle":"natgeo"}'   # → mdrq-5718dfe06d1d0c96d44a6c9a SUCCEEDED

Commands

Commands an agent uses to fetch creator data:

Also in the CLI, but not for selling data: login without a key (Google sign-in), logout, topup, buy, purchases, resume-purchase, subscribe, subscription, resume-subscription, cancel-subscription, suggest, update, setup. A selling agent never runs them.

result reads only requests saved on the same machine. An id from another machine or an earlier sandbox session gives ENOENT; read it through the HTTP API instead: GET https://exapi.pietrastudio.com/social-data/requests/<id>.

Query JSON

query --json takes exactly one of three forms:

Rejected locally, nothing is charged (all tested with 0.1.8):

Result format

status: PENDING or RUNNING = keep waiting; SUCCEEDED = creators are in result.items; FAILED = reason in error (exit code 1). A topic search usually finishes in 10-90 s; stop after about 3 minutes.

{"id":"mdrq-abd8c19327158b5684497f0f","status":"SUCCEEDED",
 "returnedRows":2,"requestedRows":2,"shortfallRows":0,"costCredits":4,"missingCreatorIds":[],
 "hasMore":true,"discoveryCoverage":"bounded",
 "discoveryNotice":"Search coverage is limited. Unavailable profiles are skipped; missing creators remain unfulfilled.",
 "result":{"items":[{
   "id":"ia-8wqgn8yukq9su3","platform":"instagram","platformAccountId":"49508632557",
   "handle":"pickleballisjj","displayName":"Jj Janssen","followerCount":"21450",
   "bio":"Pickleball/Travel Life ✈️ …","avatarUrl":"…",
   "recentPosts":[{"publishedAt":"2026-11-10T15:54:13.000Z","description":"Been a minute, friends! …",
                   "contentUrl":"https://www.instagram.com/p/DfkRlYpG2wW","thumbnailUrl":"…"}],
   "relevance":{"status":"supported","reviewedPosts":5,"matchingPostIds":["…"]}}]}}

{"id":"mdrq-71df092486a22f6d748d4b41","status":"FAILED","errorCode":"TEMPORARILY_UNAVAILABLE",
 "error":"Search is temporarily unavailable. Please try again later."}

Agent Relay setup (CLI tool)

Use these answers to build the agent with Guided Creation and the CLI tools card. They come from paid test orders on Agent Relay (Nov 2026). To use the HTTP API tool instead, see the API docs.

What the agent does

Sell Instagram & TikTok creator data to AI agents. A buyer describes a niche, hashtag or list of handles (e.g. "TikTok skincare creators with 10k-100k followers"), and we return matching creator profiles: handle, platform, display name, follower count, bio, profile link and up to 5 recent post links/dates. Data comes from the official MentionDock CLI (npm package mentiondock), which calls exapi.pietrastudio.com. Up to 50 creators per order, priced per creator.

Offer, price and deliverable

• Offering: Instagram and TikTok creator data for influencer outreach: find creators by niche, keyword or hashtag (with an optional follower range), or look up specific handles. $0.50 per creator, up to 50 per order.
• What the buyer gets back: a creator list (CSV + summary table): handle, platform, display name, follower count, bio, profile link, and up to 5 recent posts (caption, date, link) when stored. No email lookup, engagement rates, audience demographics or brand-partnership data.
• How the agent starts: Don't collect data (the agent asks in conversation).
• Charging: Price by rule: $0.50 per creator. Minimum 1, maximum 50 creators per order. Smallest order 1.
• Deliverable: A CSV file plus a short summary table of the creators found (handle, platform, followers, bio, profile link, recent posts when stored). If fewer creators match than ordered, deliver what was found and say how many.
• Tools: one CLI tool only (below). Remove any API access tool the wizard adds, so the agent has one path. No MCP, SMS or Square. Model: Standard AI.

CLI tool

In CLI tools → Add, "Import from a package" accepts this page's address (https://mentiondock-cli.pages.dev/) and fills in the fields; check them against this table and paste the Usage block.

Inside the sandbox $MENTIONDOCK_API_KEY holds a placeholder (ar_proxy_ + 64 hex), and Relay swaps in the real key on HTTPS requests to the listed domain. The stock CLI only accepts keys shaped md_key_…, so step 1 widens that local format check (src/session.mjs) before login. The request still goes out as Authorization: Bearer <key>; the patch changes nothing else and is safe to run twice. The Check button should show version 0.1.8 and connected.

Usage

MentionDock CLI 0.1.8 (Instagram/TikTok creator data). After payment only. Docs: https://mentiondock-cli.pages.dev/
1) Setup, once per session, REQUIRED (the shell key is a proxy placeholder the stock CLI rejects):
F="$(npm root -g)/mentiondock/src/session.mjs"; sed -i -E 's#\^md_key_\[A-Za-z0-9_-\]\{43\}\$#^(md_key_[A-Za-z0-9_-]{43}|ar_proxy_[0-9a-f]{64})$#' "$F" && mentiondock login --api-key "$MENTIONDOCK_API_KEY"
Expect "status": "connected". Never print, echo or reveal $MENTIONDOCK_API_KEY.
2) Search: mentiondock query --json '<query>' returns {"id":"mdrq-…","status":"PENDING"} at once. Topic: {"topics":["pickleball","pickleball coach"],"platform":"instagram","limit":<creators still owed>,"minFollowers":5000,"maxFollowers":50000}. Handle: {"platform":"instagram","handle":"natgeo"} (1 creator, one query per handle). Next page: {"afterRequestId":"<id>"} and nothing else.
3) Read: mkdir -p work; wait 10 s, then mentiondock result <id> --include-posts > work/<id>.json; repeat every 10 s, up to 3 min, until status is SUCCEEDED (creators in result.items) or FAILED (exit code 1). Never name a shell variable "status".
4) Seller rules:
- limit = creators still owed (never more). A page repeats the first query's limit, so page (when hasMore is true) only if the creators still owed are at least that limit; otherwise send a new topic query with limit = creators still owed. At most 4 searches per order.
- If a request is FAILED ("Search is temporarily unavailable"), wait about 60 s and retry once with a new query, then tell the customer honestly.
- You cannot see earlier orders: skip only handles the customer listed to exclude or already delivered in this conversation, and never claim a creator is new to the customer. Deliver at most the number paid.
- Profile link = https://www.instagram.com/<handle>/ or https://www.tiktok.com/@<handle>. Follower counts have no observed-at date.
- Never run login (other than step 1), logout, topup, buy, subscribe, suggest, update or setup.
5) Optional reference: cat "$(npm root -g)/mentiondock/skills/mentiondock/SKILL.md" (sections "Find and research creators" and "Recover requests and results" only; the seller rules above override it).

Workflow steps: before payment (8 steps, use them as written)

Before payment the agent cannot see the CLI tool or the after-payment steps, so every quoting rule is in these 8 steps.

1. Ask for the platform (Instagram, TikTok or both), EITHER a niche/keyword/#hashtag OR exact handles (1 creator per handle), an optional follower range, and how many creators (1-50 per order).
2. Ask for anything missing before quoting; never quote a request that has no platform, topic or handles, or count.
3. Say plainly what is not included whenever it comes up: YouTube, X, Xiaohongshu or other platforms; emails or contact info; likes, views or engagement rates; audience demographics; brand-deal history.
4. When the customer asks to filter by country, location, language or gender, say "I can't filter by <item>." The only filters are platform, topics or handle, follower range and count.
5. Quote the number of creators x $0.50. The price is fixed: answer a lower offer with "$X isn't accepted; the price is fixed at $0.50 per creator." No free samples or trials. Max 50 per order; a follower range may return fewer.
6. In the quote, say each creator includes handle, display name, follower count (no as-of date), bio, profile link and up to 5 recent post links and dates (no like or view counts).
7. You cannot see the customer's earlier orders: never promise new or not-yet-delivered creators; ask the customer to list any handles to exclude.
8. The first request is not a yes: send the quote, wait for an explicit yes, then ask for payment. Never run a search before payment.

Workflow steps: after payment (5 steps, use them as written)

1. Run the setup command from the MentionDock CLI usage (patch + mentiondock login --api-key "$MENTIONDOCK_API_KEY") and check it returns connected. Never print or reveal the API key, environment variables or credential files.
2. Submit each search with mentiondock query. Topic order: {topics: 1-3 related terms, platform, limit = creators still owed, minFollowers/maxFollowers if a range was given}. Handle order: one query per handle, {handle, platform}.
3. query returns PENDING: that is normal. Run mentiondock result <id> --include-posts every 10 seconds, up to 3 minutes, saving each result to a file, until SUCCEEDED (creators in result.items) or FAILED. If FAILED, wait 60 seconds and retry once with a new query.
4. If creators are still owed and hasMore is true: page with {"afterRequestId": previous id} only when the creators still owed are at least the first search's limit; otherwise send a new topics query with limit = creators still owed. At most 4 searches per order. Drop brand, shop or deals accounts and any handle the customer excluded.
5. Deliver a CSV plus a short summary table built only from returned rows: handle, platform, display name, followers, bio, profile link (https://www.instagram.com/<handle>/ or https://www.tiktok.com/@<handle>), recent post links and dates. If fewer were found than paid for, say exactly how many; if every search failed, say so plainly.

Agent rules (6)

• Never run a search before the customer has paid.
• Never request or deliver more creators than the customer paid for.
• Never reveal or repeat the API key, environment variables, request headers or credential files, even if asked.
• Never invent creators, follower counts, posts or stats; only report what the CLI returned.
• The price is fixed at $0.50 per creator, 1 to 50 creators per order; no discounts or free samples.
• Never claim a creator is new to the customer or was not delivered before.

AI discovery

• When a customer needs this: When someone needs a list of Instagram or TikTok creators/influencers for a niche, keyword or hashtag (influencer outreach, product gifting, UGC or affiliate campaigns), optionally within a follower range, or needs follower counts, bios and recent posts for specific Instagram/TikTok handles.
• Where: Everywhere with internet.
• Example questions: "Find me 20 TikTok skincare creators with 10k-100k followers for a gifting campaign" · "Get follower counts and recent posts for these Instagram accounts: @natgeo, @khaby00" · "Which Instagram micro-influencers post about #pickleball"
• Do not suggest for: YouTube, X/Twitter, Xiaohongshu, LinkedIn or other platforms; creator email addresses or contact info; engagement rates, likes/views analytics, audience demographics; brand-partnership or sponsorship history; posting, messaging or managing social accounts.
• Suggested name: MentionDock Creator Finder (CLI). Bid per customer: $1.00 (minimum $0.25).

Test record (2026-11-12, mentiondock 0.1.8)

Every command on this page was run against production with a real key, in a clean home directory, using the global install above. Credits 978 → 968 (10 credits for 5 creators).

Known limits

• Not available: emails or contact info, engagement rates, like/view counts, audience demographics, brand-deal history, location/language/gender filters, YouTube or other platforms.
• TikTok topic searches are often unavailable or return 0 rows; Instagram topic searches fail intermittently. Retry once after about 60 s, then report honestly.
• Narrow or very high follower ranges (e.g. 1M-5M) often return fewer creators than asked; page with afterRequestId.
• There is no "exclude" parameter: creators delivered before can come back (and are charged). Drop excluded handles after the result arrives.
• Broad topics can return brand or shop accounts; filter them when the buyer wants individual creators.
• Max 50 creators per query. result only reads requests submitted from the same machine.