Apollo

The Apollo skill connects Maestro to Apollo.io, a B2B prospecting database with 275M+ contacts. Use it to find leads matching your ICP and enrich the contacts + companies you already have.

What this skill does

What you’ll set up

Connecting Apollo to Maestro is much simpler than Gmail — there’s no OAuth, just an API key.

1. Sign up at app.apollo.io (free tier available).
2. Generate an API key.
3. Paste it into Maestro’s secrets vault.

That’s it. About 2 minutes the first time.

Step 1 — Create an Apollo account

1. Open app.apollo.io and sign up. You can start on the free tier — no credit card required.
2. Verify your email if Apollo asks.

The free tier includes a limited number of email reveals per month and full access to the API for searching. For production cold-outreach workloads, the Basic plan ($59/mo) unlocks 200 email credits/month plus mobile numbers; the Professional plan ($99/mo) unlocks 2,400. Most active workloads outgrow the free tier within a week of running cold-leads.

Step 2 — Generate an API key

1. In Apollo, click your avatar (top right) → Settings.
2. Sidebar → Integrations → API.
3. Click Generate API Key. Apollo shows it once — copy it now.

Treat the key like a password. Anyone with this key can run searches against your Apollo account, consuming your monthly credits. If it leaks, regenerate from the same screen — old keys are invalidated immediately.

Step 3 — Add the key to Maestro

1. Open Maestro and navigate to Secrets.
2. Click + Add secret:
   • Name: apollo_api_key
   • Kind: api_key
   • Description: optional, e.g. “Apollo · production workspace”
   • Value: paste the API key
3. Save.

The value is encrypted with AES-256-GCM before it hits the database. See Secrets for the threat model.

Step 4 — Verify

Navigate to Skills → Apollo and click Test next to find_leads. Try a small search:

• titles: VP Engineering, CTO
• company_size_bands: 11,50 (means 11–50 headcount)
• per_page: 5

You should get back five candidates with names, titles, companies, and (sometimes) emails.

Working with results

Why some emails are empty

Apollo’s email visibility depends on your plan. On the free tier, most search results show metadata (name, title, company) but the email field is empty — Apollo’s reveals are credit-gated. The Basic plan ($59/mo) unlocks 200 reveals/month; Professional ($99/mo) unlocks 2,400.

Empty email is a real signal, not a bug. The cold-leads agent treats those candidates as needing an enrichment pass — call enrich_person with their email-less identity (name + company domain) to attempt a reveal, which costs one credit on most plans.

Recommended cold-leads flow

1. find_leads with your ICP filters → bulk metadata, mostly free
2. For candidates that look promising but lack an email, enrich_person to attempt the reveal → one credit each
3. enrich_domain on the company before drafting → frame the opener with funding stage, tech stack, headcount

This pattern minimizes credit spend on prospects that turn out to be unfit. The compose.draft_personalized_opener skill (when shipped) consumes the enrichment data to ground its drafts.

Common ICP filter values

Seniorities (Apollo’s canonical values): owner, founder, c_suite, partner, vp, head, director, manager, senior, entry, intern

Company size bands (Apollo expects “min,max” comma-separated strings): 1,10, 11,50, 51,200, 201,500, 501,1000, 1001,5000, 5001,10000, 10001 (10K+)

Industries: free-text matched against Apollo’s tagged industry data. Common tags include Software, SaaS, Information Technology, Marketing & Advertising, Computer Software, Internet, Financial Services, Healthcare. Try a few — Apollo’s matching is fuzzy.

Locations: full strings like United States, San Francisco, California, US, London, United Kingdom. Apollo geocodes loosely.

Permissions & data handling

The Apollo API key gives Maestro the same access you have through Apollo’s web app — searching their contact database, enriching records, and consuming your account’s credits.

Maestro does not:

• Push your contacts back to Apollo (no two-way sync).
• Send any data to Apollo beyond the search filters and enrichment identifiers you pass.
• Store Apollo records as the source of truth — once a candidate is added to a Pipeline, the contact lives in Maestro’s database, not Apollo’s.

Apollo records flow into Maestro’s Pipeline as contacts rows; the Apollo person ID is preserved in enrichment_json for future reference. Removing the Apollo skill or rotating the key doesn’t affect contacts already in the Pipeline.

Troubleshooting

“Apollo rejected the API key” The key is invalid or revoked. Regenerate from app.apollo.io → Settings → Integrations → API and rotate the secret in Maestro (Secrets page → click the apollo_api_key entry → paste the new value).

find_leads returns 0 results Apollo’s filters are AND’d across categories. Common gotcha: combining a narrow industries list with a narrow company_size_bands list can over-constrain. Start with one filter category, verify you’re getting results, then layer more.

Most results have empty emails Expected on the free tier. See “Why some emails are empty” above. Run enrich_person on individual prospects to attempt the reveal, or upgrade your Apollo plan.

Apollo HTTP 422 Apollo rejected an input parameter. The error message includes Apollo’s field-level explanation. Most common cause: company_size_bands values formatted wrong — they’re comma-separated min/max strings ("11,50"), not arrays of arrays.

Hit rate limit (Apollo HTTP 429) Apollo throttles per API key. The runtime retries automatically with exponential backoff. If you’re consistently rate-limited, reduce per_page or pace your runs further apart in the agent’s cron schedule.

Why Apollo

Apollo is one of the most established B2B prospecting databases — 275M+ contacts, 10+ years of data refinement, and an API that’s central to their product. It’s the fastest path to high-quality leads for cold-outreach use cases, which is why it’s the v1 default.

A future native prospect-from-web skill is on the roadmap for customers who prefer to source leads directly from public web data (Google Business Profiles, company websites). Apollo and the native prospector are designed to compose: Apollo for volume + data quality, native for niche, local, or specialized targeting.

Related

• Skills overview — how skills work in general.
• Secrets — encryption + key handling.
• Pipelines — where Apollo-sourced contacts land.
• Gmail — the other half of the cold-leads pipeline (sending the outreach).