tinyfish-io/tinyfish-social-listening

TinyFish Social Listening

Find TinyFish mentions across X, LinkedIn, Reddit, and Hacker News for the last 24 hours. Default output is all discovered posts/comments, not a summary.

Preflight

Run:

[ -n "$TINYFISH_API_KEY" ] && echo "TINYFISH_API_KEY is set" || tinyfish auth status | jq '{authenticated, source}'
node --version

The runner uses TINYFISH_API_KEY first, then TinyFish CLI auth config execution-only. Do not inspect, print, or summarize real secret files.

Default Run

Use bundled runner:

npm run listen -- --hours=24 --sentiment

Default behavior:

1. Run TinyFish Search for X/LinkedIn discovery.
2. Run TinyFish Fetch on discovered X/LinkedIn URLs.
3. Run public Reddit/HN APIs for posts and comments.
4. Report coverage gaps when Search/Fetch cannot verify content, comments, or timestamps.

Run the local self-test:

npm test

JSON output:

npm run listen -- --hours=24 --sentiment --json

Enable Agent fallback after credits/auth are available:

npm run listen -- --hours=24 --sentiment --agent-fallback --max-agent-runs=2

Default Agent fallback is targeted: it opens exact unresolved X/LinkedIn URLs from Search+Fetch and tries to verify content or timestamps. If Search/Fetch fails before producing exact URLs, it can run one capped search_recovery job. It does not run broad social search otherwise unless explicitly requested:

npm run listen -- --hours=24 --sentiment --agent-fallback --agent-search-fallback --max-agent-runs=2

Use authenticated Agent fallback with TinyFish Vault credentials:

npm run listen -- --hours=24 --sentiment --agent-fallback --use-vault --linkedin-credential-item-id=cred:...:item-linkedin

If one credential should be available to every Agent fallback platform:

npm run listen -- --hours=24 --sentiment --agent-fallback --use-vault --credential-item-id=cred:...:item-shared

For deeper Search pagination, throttle Search to avoid rate limits:

npm run listen -- --hours=24 --sentiment --max-pages=10 --search-delay-ms=12500

Conservative defaults stay within the lower public free-plan limits seen on TinyFish pricing/blog pages: Search 5 req/min and Fetch 25 url/min. If your account has higher limits from the API reference or a paid plan, lower --search-delay-ms / --fetch-delay-ms or increase --fetch-batch-size.

Save a report:

mkdir -p reports
npm run listen -- --hours=24 --sentiment > reports/tinyfish-social-listening-$(date -u +%Y%m%dT%H%M%SZ).md

Coverage Rules

• Include every discovered item whose author is not an official TinyFish account.
• Include posts and comments/replies.
• Treat TinyFish Search as URL discovery only. A Search title/snippet is not proof that the actual post mentions TinyFish.
• For X/LinkedIn, TinyFish Fetch must confirm the fetched page title/body mentions TinyFish before an item can be counted as verified.
• If Fetch returns a readable page but the fetched title/body does not mention TinyFish, treat the Search hit as a false positive.
• If Fetch returns a blocked/login/JavaScript shell, keep Search-matched items under Needs verification with verification_type: content; do not count them as verified.
• For X status URLs, decode the status ID timestamp when Fetch cannot expose published_date; still require Agent/browser verification for blocked content.
• X results must resolve to status URLs; profile/search pages are treated as discovery noise.
• X/Twitter status URLs are deduped by status ID so legacy twitter.com and current x.com hosts do not double-count one post.
• Last 24 hours is strict when source timestamp is available.
• If X/LinkedIn only expose search-snippet results without exact content or timestamps, keep them under Needs verification; do not pretend they are proven last-24-hour items.
• Keep needs_time_verification only for items whose timestamp cannot be proven. Do not put X snowflake-decoded timestamps there.
• If Agent fallback runs, include the exact fallback reason, target URL, mode, run ID, status, and step count when the API returns it.
• If Agent fallback is disabled or unavailable, include the exact coverage gap in the report.
• In Search+Fetch-only mode, always report that X/LinkedIn comments and logged-in content are not fully enumerable until Agent/browser verification is available.
• Report source failures and blocked pages explicitly.
• Do not summarize away items. Sentiment buckets are optional grouping only.

Official Account Exclusions

Default exclusions:

• X: @Tiny_Fish, x.com/Tiny_Fish
• X legacy host: twitter.com/Tiny_Fish
• X operator/insider: @sudheenair
• LinkedIn: linkedin.com/company/tinyfish-ai
• LinkedIn operator/insider: Sudheesh Nair, linkedin.com/in/sudheenair, linkedin.com/posts/sudheenair_
• Reddit/HN: no known official account by default

Override or add exclusions:

npm run listen -- --exclude-author=Tiny_Fish --exclude-url=https://www.linkedin.com/company/tinyfish-ai

Exclude known irrelevant brand collisions:

npm run listen -- --exclude-phrase="other product phrase"

Data Strategy

Grounding from TinyFish docs:

• TinyFish docs: https://docs.tinyfish.ai/
• Search reference: https://docs.tinyfish.ai/search-api/reference
• Fetch reference: https://docs.tinyfish.ai/fetch-api/reference
• Agent overview/reference: https://docs.tinyfish.ai/agent-api and https://docs.tinyfish.ai/agent-api/reference
• Vault setup: https://docs.tinyfish.ai/vault-setup
• Anti-bot guide: https://docs.tinyfish.ai/anti-bot-guide
• TinyFish docs list four public surfaces: Agent, Search, Fetch, Browser; Search and Fetch are free, Agent and Browser use credits.
• Search docs say Search is for ranked search results, snippets, and URLs.
• Fetch docs say Fetch is for known URLs and clean extracted page content; Fetch renders pages in a real browser and returns extracted text.
• Public TinyFish pricing/blog pages list lower free-plan limits than the current API reference, so the runner defaults to the conservative lower numbers to avoid surprise 429s.
• Agent docs say Agent is for natural-language goals where TinyFish decides browser actions, especially multi-step workflows.
• Vault docs say Agent runs can use use_vault: true and credential_item_ids from GET /v1/vault/items; scoped credential IDs prevent the wrong login when multiple accounts exist on one domain.

Operational strategy:

• X and LinkedIn: Search first for discovery, then Fetch every discovered URL for content/timestamps.
• Agent fallback: opt-in via --agent-fallback for X/LinkedIn when Search/Fetch hits bot_blocked, timeout, empty_content, other fetch failures, search API failures, or timestamp/content-incomplete results that may hide comments/replies.
• Default Agent fallback verifies exact unresolved URLs first and is capped by --max-agent-runs to avoid burning steps. If Search/Fetch fails before producing exact URLs, it can run a capped search_recovery job. Broad Agent search is otherwise behind --agent-search-fallback or --force-agent-fallback.
• Authenticated Agent fallback: use --use-vault plus platform-specific --linkedin-credential-item-id=... or --x-credential-item-id=... when public Search/Fetch cannot see logged-in comments/posts.
• Reddit: public Reddit JSON search for posts/comments, then thread JSON for comments.
• Hacker News: Algolia HN API by date for stories and comments.
• Browser API is not used.

Known Search/Fetch/Agent Gaps

• Search snippets can mention TinyFish because of sidebars, author bios, or adjacent comments; readable Fetch body/title is the source of truth for verified items.
• Fetch can return X or LinkedIn JavaScript/login shells. Agent can open the exact URL to verify visible content, but without Vault it may still hit login, CAPTCHA, or access walls.
• LinkedIn logged-in comments and private/limited-visibility posts are not fully provable with public Search+Fetch. Vault credentials should help later by letting Agent use the right LinkedIn account.
• X replies and LinkedIn comments are not exhaustively enumerable unless Agent can access the live page. Keep these as coverage gaps when Agent is disabled, capped, blocked, or unauthenticated.
• Agent endpoint failures seen during testing: 403 when output_schema was not enabled, 403 when credits were empty, and 429 RATE_LIMIT_EXCEEDED when stale pending runs exceeded the active-run limit. These are source failures, not verified mentions.

Cron

Run once or twice daily from this skill directory:

0 8,20 * * * cd /path/to/tinyfish-social-listening && /usr/bin/env bash -lc 'npm run listen -- --hours=24 --sentiment >> reports/cron-social-listening.md'

For production cron, write one timestamped report per run instead of appending if downstream tooling needs immutable artifacts.