MoltSets API: Tools, Auth, Fair Use Limits and Examples

The MoltSets API is a JSON REST API where every tool (email lookup, mobile lookup, people search, company search and more) is a POST to https://api.moltsets.com/api/v1/tools/<tool_name> with a Bearer key that starts with ms_. Batch tools take up to 100 LinkedIn URLs or emails per call, misses come back as HTTP 200 with status: "not_found" at no record cost, and usage is capped by rolling 5-hour and weekly Fair Use windows rather than credits. If you are comfortable writing a few HTTP calls, it is one of the cheapest ways to get verified B2B emails into your own code.

Some tool links here are affiliate links (disclosure). You need an account to get a key: sign up for MoltSets (free tier, no card). For the product as a whole, including data claims and weaknesses, read our MoltSets review.

Nerdy Joe is a certified Apollo.io Managed Services Partner and a PlusVibe Certified Silver Partner, and we are a MoltSets affiliate. We did not call the MoltSets API for this guide. Everything below comes from MoltSets' API page, its developer docs (developer.moltsets.com) and its changelog, checked November 9, 2026, and request examples appear only in the shapes MoltSets documents.

MoltSets API quick facts

Authentication and headers

Every call carries three headers. MoltSets' API page shows them in its curl example, and the docs explain the User-Agent rule.

Authorization: Bearer ms_XXXXXXXXXXX
Content-Type: application/json
User-Agent: my-app/1.0

Keys start with ms_ and are created under API keys in the MoltSets app. MoltSets suggests one per environment or agent, so you can revoke one without breaking the rest.

Since September 16, 2026, MoltSets returns 403 to connections without a non-empty User-Agent, per its changelog and docs. Some minimal HTTP clients and serverless runtimes send none by default, so set it explicitly.

The MCP server uses separate OAuth credentials (Client ID and Client Secret), not your ms_ key; see our MoltSets MCP server guide. The CLI uses the API key (--api-key, MOLTSETS_API_KEY or moltsets login). Limits are shared across every key and connector, so more keys do not mean more headroom.

The documented request example

This is the example on MoltSets' API page: find the best email for one LinkedIn profile.

curl -X POST https://api.moltsets.com/api/v1/tools/linkedin_to_best_email \
  -H "Authorization: Bearer ms_XXXXXXXXXXX" \
  -H "Content-Type: application/json" \
  -H "User-Agent: my-app/1.0" \
  -d '{"linkedin_url": "https://linkedin.com/in/example"}'

The documented response (trimmed by MoltSets itself with ...):

200 OK
{ "results": { "email": "sam@example.com", "type": "business", "risk_score": "A", ... },
  "status": "ok", "metadata": { ... } }

Note the risk_score field: every returned email carries an A to F send-safety grade plus a last-validated date.

The response envelope and not_found

Every response uses the same envelope: results, status and metadata. The rule to build around is that a miss is not an error.

• Found: HTTP 200, status: "ok", data in results.
• No match: HTTP 200, status: "not_found". Nothing is charged against your record cap.
• Batch calls: each item carries its own status, so one call can mix hits and misses.
• 404: only for an unknown tool (tool_not_found), never for a miss.

MoltSets used to return 404 on misses. Its docs warn that Clay tables (and, by extension, any script) that relied on the old behavior must now check status instead of the HTTP code. If you wrote error handling that treats 404 as "no data," update it.

Failed email addresses never reach you. MoltSets says addresses that fail validation are dropped before delivery, and a lookup whose only address was dropped returns not_found with no charge.

Tool reference

REST and MCP share the same tool set. These are the tools listed on MoltSets' API page and in its docs index.

Enrichment tools

Personal email tools return US records only.

Search tools

Account tools (free)

get_account, get_billing and get_usage use no tokens and do not count against rate limits. get_usage accepts the periods today, week, month and billing_cycle, which makes it the right call before and during a large job.

Ad audience tools (plan-gated)

business_email_to_sha256, linkedin_to_sha256 (SHA256 and MD5) and email_to_maid (AAIDs and IDFAs) build ad audiences. Since September 29, 2026 they are available on Free, Solo ($27) and Pro ($97) but not on Team ($397) or Max ($997), per MoltSets' FAQ and changelog. A restricted plan gets plan_restricted (403).

Coming soon (not live)

validate_emails (up to 1,000 addresses per call) and scrape_website (homepage only, structured JSON) are documented and priced but do not work yet, with no launch date. Their planned prices are in our MoltSets pricing guide.

Batching: up to 100 per call

Batch tools take a linkedin_urls or emails array of up to 100 items, per MoltSets' docs. Three rules come with it:

1. Each item counts as one request toward your Fair Use request cap. A batch of 100 is 100 requests, not one.
2. You cannot mix single and batch parameters in one call (for example linkedin_url and linkedin_urls together).
3. Read per-item status. The response carries a status per item, so loop through results rather than checking the top-level code alone.

For mobile batches, running out of phone tokens mid-batch does not fail the whole call. MoltSets says the batch returns what your tokens can cover and drops the rest, with insufficient_phone_tokens (402) once the balance is empty.

For one-off CSV jobs, the MoltSets CLI sends batches of 100 and resumes on rerun, which can be simpler than your own loop.

Search filters and pagination

search_people is the main list-building tool. These are the filters in MoltSets' API reference.

• Lists: positive filters accept lists since September 22, 2026.
• Exclusions need a positive filter. They cannot be the only filter in a call.
• Pagination: offset plus limit; limit defaults to 10 and maxes out at 25 per call.
• Concurrency: 3 simultaneous searches on Free and Solo, 5 on Pro, 8 on Team and Max. Going over returns search_concurrency_exceeded (429) with Retry-After: 1.

The docs we read do not state the maximum total results a search can page through, the full search_companies filter list, or whether one search record means one returned profile or one call (per profile is the likely reading).

Fair Use limits (what the API can actually do)

MoltSets plans are sold as "unlimited data," but every plan has rolling caps. These figures are from MoltSets' rate limits docs and Fair Use Policy, as of November 2026.

Enrichment caps

Search caps

How the counting works, per MoltSets:

• Records are deducted only when a real contact is returned.
• Requests are deducted whether or not a contact is returned. The request cap is 5x the record cap, so a list with a low match rate can hit the request cap first.
• Windows roll. Your first request opens a 5-hour window; weekly windows work the same way.
• The weekly cap binds first. On Solo you could do 1,000 records per 5 hours, but only 5,000 per week. The same 5x pattern holds on every paid plan.
• Personal emails count toward enrichment limits. On Team and Max they are also capped at 15,000 per 5 hours and 75,000 per week.

The Terms bar opening multiple self-serve accounts to get around limits, so plan your volume inside one account's caps. For more than Max allows, MoltSets sells custom flat files priced per record. Our in-depth MoltSets review weighs these caps against what competitors charge.

Error codes

Errors use {"error": {"code", "message"}}, and MoltSets says nothing is charged on an error.

Handling 429s in your code

MoltSets' CLI waits and retries up to four times on a 429, and waits for a Fair Use reset when a window is exhausted. Our recommendations for custom code follow the same idea.

• Split 429s by code. Concurrency and rate errors are short waits (respect Retry-After); the two fair_use codes can mean hours until the window rolls.
• Check headroom first with get_usage (free).
• Cap search workers at your plan's concurrency (3, 5 or 8).
• Treat 402 as a stop, not a retry loop.

What the API costs per record

These are our calculations from MoltSets' published prices, as of November 2026. The ceilings assume you use the full weekly enrichment cap every week (4 weeks per month).

Real cost is higher if you use less. A Solo user who enriches 2,000 contacts in a month still pays $27, about $0.0135 per record. Mobiles are a flat $0.15 per number returned, on a separate monthly phone token subscription that requires a paid plan.

For comparison, our Findymail API guide covers a credit-based API at about $0.0198 per found email on its Starter credit plan, with a bounce guarantee MoltSets does not offer.

Common MoltSets API use cases

Feed a cold email tool

MoltSets has no native integration with Instantly, Smartlead, PlusVibe or lemlist. Write the results to a CSV (or use the CLI's --out), then import it, or call the sequencer's own add-lead API from the same script. Our MoltSets to Instantly workflow walks through it, and our cold email infrastructure guide covers the sending side.

Call it from Clay

MoltSets is not a native Clay data provider.

Its docs show the setup: an HTTP API column, method POST, the tool URL, headers Content-Type, Authorization: Bearer and User-Agent: Clay, and "Response values to return" set to results. Then add Formula columns for nested fields (such as results.email, since Clay only traverses one level) and for status. Our Apollo vs Clay comparison covers where Clay fits in a stack.

Enrich inbound leads and CRM records

Use reverse_email_lookup on form fills and ip_to_company on site visitors. The CRM write-back (HubSpot, Attio, Salesforce) is done by your scripts or an agent, not a native sync product.

What the docs do not cover

• The contents of the OpenAPI spec at /openapi.json (referenced; not reviewed by us).
• Webhooks for async API results (none documented).
• A published accuracy percentage, database size or bounce guarantee.

MoltSets is also young: its changelog shows many changes to limits, tool names and responses in September and October 2026, so recheck the docs before each release.

Final take

The MoltSets API is simple to call: Bearer key, one POST per tool, batches of 100, and a clean ok versus not_found status that never charges you for a miss. The constraints to design around are the weekly Fair Use caps, the request cap that counts misses, 25 results per search call, and the required User-Agent header.

If your team works in code or agents rather than a dashboard, it is worth testing. Start with the free tier from a MoltSets account, run a few hundred lookups from your own list, then pick a MoltSets plan whose weekly cap fits.

For the bigger picture, including where MoltSets falls short, see the full MoltSets review, and if you need a UI as well, compare options in our best B2B data providers roundup. When you are ready, start on MoltSets.

Rather not build the list yourself?

Nerdy Joe is owned by Agency Growth Partners (AGP). AGP builds verified lead lists and runs outbound for agencies, including the enrichment scripts and grade filtering described here. If you would rather hand it off, book a call with David.

Sources

• MoltSets API page: https://moltsets.com/how-it-works/api/
• MoltSets developer docs index (llms.txt): https://developer.moltsets.com/llms.txt
• MoltSets API reference: https://developer.moltsets.com/api-reference/
• MoltSets rate limits: https://developer.moltsets.com/getting-started/rate-limits
• MoltSets email risk scores: https://developer.moltsets.com/moltsets-data/email-risk-scores
• MoltSets Clay integration docs: https://developer.moltsets.com/integrations/clay
• MoltSets validate emails reference: https://developer.moltsets.com/api-reference/get-valid-emails/validate-emails
• MoltSets scrape website reference: https://developer.moltsets.com/api-reference/get-company/scrape-website
• MoltSets Fair Use Policy: https://moltsets.com/fair-use-policy-enrichment/
• MoltSets pricing: https://moltsets.com/pricing/
• MoltSets mobile numbers pricing: https://moltsets.com/pricing/mobile-numbers/
• MoltSets FAQ: https://moltsets.com/faq/
• MoltSets features: https://moltsets.com/features/
• MoltSets CLI: https://moltsets.com/how-it-works/cli/
• MoltSets terms of service: https://moltsets.com/terms-of-service/
• MoltSets changelog: https://support.moltsets.com/en/articles/15424421-changelog