Maestro
Apply for beta

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

OperationPurposeCostStatus
find_leadsSearch Apollo’s database for people matching ICP filters. Returns identity stubs only — first name, obfuscated last name (e.g. Hu***n), title, company name, plus boolean has_email/has_direct_phone flags. No email, no full last name, no linkedin/location/company-domain — those require enrichment.FreeShipped
bulk_enrich_leadsEnrich many leads in one call. Returns full PersonRecords with email, full last name, linkedin, location, and company firmographics. Up to 10 details per call.~1 credit per matched recordShipped
enrich_personEnrich one lead by email, name + organization, or LinkedIn URL. Same data as bulk_enrich_leads but for a single person — useful for one-off lookups.~1 creditShipped
enrich_domainLook up a company by domain. Returns headcount, industry, funding stage, technologies, and other firmographics.~1 creditShipped

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 and upgrade to a paid plan (see plan note below — the free tier doesn’t include API access).
  2. Generate an API key.
  3. Paste it into Maestro’s secrets vault.

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

Apollo’s free plan does NOT include API access. Apollo gates mixed_people/api_search, people/match, and organizations/enrich to the Basic plan ($59/mo) and above. If you try to use this skill on a free key, Apollo returns 403 with API_INACCESSIBLE and Maestro will surface “Apollo’s /endpoint requires a paid plan” — that’s not a key problem, it’s a plan problem. Upgrade at app.apollo.io → Settings → Billing.

Step 1 — Create an Apollo account

  1. Open app.apollo.io and sign up.
  2. Verify your email if Apollo asks.
  3. Upgrade to a paid plan before generating the API key. The free tier lets you use Apollo’s web UI but blocks the API endpoints this skill calls. Plan tiers as of v1:
    • Basic ($59/mo): 200 email reveals/month + API access. Required minimum for cold-outreach workloads.
    • Professional ($99/mo): 2,400 reveals/month + API. Recommended for running cold-leads at >50 contacts/week.

Most cold-outreach workloads outgrow Basic within a few weeks; start there and upgrade when you hit the credit ceiling.

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 search results have no email

Apollo’s mixed_people/api_search endpoint deliberately returns only identity stubs — first name, obfuscated last name (Hu***n), title, company name, plus boolean has_email/has_direct_phone flags that predict whether enrichment will reveal contact data. This isn’t a free-tier limitation; it’s how Apollo’s API is designed to bill: search costs nothing, enrichment costs ~1 credit per record.

So find_leads always shows last_name_obfuscated instead of a real last name and never includes an email. If a stub has has_email: true, that’s Apollo’s prediction that enrichment will succeed for that record. Use bulk_enrich_leads to spend the credits and get the full data.

  1. find_leads with your ICP filters → identity stubs (free).
  2. Filter the stubs in-agent — drop anything where has_email is false or the title doesn’t fit your ICP. No API call here, just LLM reasoning over the stub data.
  3. bulk_enrich_leads with the surviving IDs → full PersonRecords with email, linkedin, location, company domain (~1 credit each).
  4. enrich_domain on the company before drafting → frame the opener with funding stage, tech stack, headcount.
  5. compose.draft_personalized_opener to ground a draft in the enrichment data.

The shipped cold-leads agent script implements this flow with a hard cap of 3 enrichments per run, bounding spend at ~3 credits per cron tick while you tune. Raise the cap once you’re confident in the agent’s filtering quality.

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).

“Apollo’s /endpoint requires a paid plan” The key is valid but your Apollo plan doesn’t include API access. Free tier blocks mixed_people/api_search, people/match, and organizations/enrich. Upgrade to Basic ($59/mo) or higher at app.apollo.io → Settings → Billing. The same key works after the plan upgrade — no need to regenerate.

Quick way to confirm whether it’s the key or the plan: hit Apollo directly with PowerShell. A valid key on a free plan returns 403 with API_INACCESSIBLE; an invalid key returns 401.

$key = "YOUR_APOLLO_KEY"
Invoke-RestMethod -Uri https://api.apollo.io/api/v1/mixed_people/api_search `
  -Method POST -Headers @{"X-Api-Key" = $key} `
  -ContentType "application/json" `
  -Body (@{per_page=1; person_titles=@("VP Engineering")} | ConvertTo-Json)

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.

  • 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).