Find Twitter Influencers

Setup

Read your credentials from ~/.gooseworks/credentials.json:

export GOOSEWORKS_API_KEY=$(python3 -c "import json;print(json.load(open('$HOME/.gooseworks/credentials.json'))['api_key'])")
export GOOSEWORKS_API_BASE=$(python3 -c "import json;print(json.load(open('$HOME/.gooseworks/credentials.json')).get('api_base','https://api.gooseworks.ai'))")

If ~/.gooseworks/credentials.json does not exist, tell the user to run: npx gooseworks login

All endpoints use Bearer auth: -H "Authorization: Bearer $GOOSEWORKS_API_KEY"

Discover, score, and enrich Twitter/X influencers relevant to a company, product, or niche. Returns a ranked list with engagement metrics, relevance reasoning, and contact info.

Workflow

1. Parse the Request

Extract from the user's query:

• Company name or domain (required) — the brand seeking influencers
• Niche/vertical (optional) — e.g., "fintech Twitter", "AI/ML creators", "DTC beauty"
• Size preference (optional) — mid-tier (10K-100K), macro (100K+), or mixed (default: 10K+ minimum)
• Max results (optional, default 20 — scale up or down if the user asks)

2. Resolve the Company

Use Brand.dev to get domain, industry, description, target audience, and keywords. This context drives all subsequent searches.

curl -s -X POST $GOOSEWORKS_API_BASE/v1/proxy/orthogonal/run \
  -H "Authorization: Bearer $GOOSEWORKS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"api":"brand-dev","path":"/v1/brand/retrieve-by-name","query":{"name":"Acme","Corp":""}}'

If a domain is provided directly:

curl -s -X POST $GOOSEWORKS_API_BASE/v1/proxy/orthogonal/run \
  -H "Authorization: Bearer $GOOSEWORKS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"api":"brand-dev","path":"/v1/brand/retrieve","query":{"domain":"acme.com"}}'

From the result, build a company context string: company name, domain, industry, description, and target audience keywords. Example: "Acme Corp acme.com developer tools API platform engineering teams". Use this in all search queries.

3. Discover Candidates

Run three strategies in parallel to maximize coverage:

Strategy A — Exa search for curated influencer lists (primary, highest signal):

IMPORTANT: x.com and twitter.com profiles are NOT in Exa's search index, so includeDomains: ["x.com"] will return zero Twitter results. Instead, search for curated list pages, blog posts, and articles about influencers in the niche. Use contents.text to get the page content so you can extract Twitter handles from it.

Run 5+ query variations to maximize coverage. Include the core niche AND adjacent niches — many influencers span related topics. Each query returns 10 results with text content:

# Query 1: Core niche — curated lists
curl -s -X POST $GOOSEWORKS_API_BASE/v1/proxy/orthogonal/run \
  -H "Authorization: Bearer $GOOSEWORKS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"api":"exa","path":"/search"}'
  "query": "best {niche} Twitter accounts to follow",
  "numResults": 10,
  "contents": {"text": {"maxCharacters": 5000}}
}'

# Query 2: Core niche — different phrasing
curl -s -X POST $GOOSEWORKS_API_BASE/v1/proxy/orthogonal/run \
  -H "Authorization: Bearer $GOOSEWORKS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"api":"exa","path":"/search"}'
  "query": "top {industry} influencers on X Twitter must follow",
  "numResults": 10,
  "contents": {"text": {"maxCharacters": 5000}}
}'

# Query 3: Core niche — thought leaders
curl -s -X POST $GOOSEWORKS_API_BASE/v1/proxy/orthogonal/run \
  -H "Authorization: Bearer $GOOSEWORKS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"api":"exa","path":"/search"}'
  "query": "{niche} thought leaders creators Twitter handles",
  "numResults": 10,
  "contents": {"text": {"maxCharacters": 5000}}
}'

# Query 4: Adjacent niche 1 (e.g., if niche is "identity verification", try "fraud prevention")
curl -s -X POST $GOOSEWORKS_API_BASE/v1/proxy/orthogonal/run \
  -H "Authorization: Bearer $GOOSEWORKS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"api":"exa","path":"/search"}'
  "query": "top {adjacent_niche_1} influencers Twitter accounts to follow",
  "numResults": 10,
  "contents": {"text": {"maxCharacters": 5000}}
}'

# Query 5: Adjacent niche 2 (e.g., "cybersecurity", "regtech", "biometrics")
curl -s -X POST $GOOSEWORKS_API_BASE/v1/proxy/orthogonal/run \
  -H "Authorization: Bearer $GOOSEWORKS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"api":"exa","path":"/search"}'
  "query": "best {adjacent_niche_2} experts creators on X Twitter",
  "numResults": 10,
  "contents": {"text": {"maxCharacters": 5000}}
}'

Choosing adjacent niches: From the company context (Step 2), identify 2-3 related verticals. Examples:

• Identity verification → fraud prevention, cybersecurity, regtech, biometrics
• Fintech → banking, payments, DeFi, financial regulation
• AI/ML → data science, MLOps, developer tools
• DTC beauty → skincare, wellness, lifestyle, clean beauty

These queries return listicle pages (e.g., "Top 60 Fintech Influencers", "FinTwit Accounts to Follow") whose text content contains Twitter handles, bios, and follower counts. Parse these in Step 4.

Strategy B — Exa findSimilar (expand from strong listicle finds):

After Strategy A returns results, pick 1-2 of the best curated list URLs and find similar pages:

curl -s -X POST $GOOSEWORKS_API_BASE/v1/proxy/orthogonal/run \
  -H "Authorization: Bearer $GOOSEWORKS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"api":"exa","path":"/findSimilar"}'
  "url": "https://example.com/top-fintech-twitter-influencers",
  "numResults": 5,
  "contents": {"text": {"maxCharacters": 5000}}
}'

This surfaces additional curated lists that keyword search may miss. Do NOT use Twitter/X profile URLs for findSimilar — they are not in Exa's index and will return empty results.

Strategy C — Fiber natural-language-search (catch LinkedIn-heavy professionals):

Some influencers are better indexed on LinkedIn but have active Twitter accounts. Fiber can surface these. Run 2-3 queries covering the core niche and adjacent topics:

# Core niche
curl -s -X POST $GOOSEWORKS_API_BASE/v1/proxy/orthogonal/run \
  -H "Authorization: Bearer $GOOSEWORKS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"api":"fiber","path":"/v1/natural-language-search/profiles"}'
  "query": "{niche} thought leader content creator with Twitter presence at {industry} companies",
  "pageSize": 20
}'

# Adjacent niche — broader coverage
curl -s -X POST $GOOSEWORKS_API_BASE/v1/proxy/orthogonal/run \
  -H "Authorization: Bearer $GOOSEWORKS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"api":"fiber","path":"/v1/natural-language-search/profiles"}'
  "query": "{adjacent_niche} influencer expert with large social media following",
  "pageSize": 20
}'

Cross-reference Fiber results with Twitter in Step 5 — only keep people with active Twitter accounts. Also extract LinkedIn URLs from Fiber results — these are critical for contact enrichment in Step 7.

4. Extract & Deduplicate Usernames

From the text content of Exa listicle pages, parse Twitter handles using multiple patterns:

• @username mentions in the article text
• URLs matching x.com/username or twitter.com/username
• Strip trailing URL paths (e.g., /status/123, /followers) — only keep base profile usernames
• Discard non-profile patterns (search pages, hashtag pages, x.com/home, x.com/search)
• Deduplicate by username (case-insensitive)
• Flag and remove obvious brand/company accounts (e.g., @stripe, @shopify) — focus on individual creators

From Fiber results, extract any Twitter/X URLs from social profiles. Add new handles to the candidate pool.

Also extract LinkedIn URLs mentioned alongside Twitter handles in listicle pages — save these for contact enrichment in St