Enrichments
Searches
Concurrent searches
Each account can run a limited number ofsearch_people and search_companies calls at the same time. The limit is per account, shared across every API key and connector.
A search that would go over the limit returns
429 with search_concurrency_exceeded and a Retry-After: 1 header. Wait 1 second and retry, and keep fewer searches running in parallel. If your agent fans out searches — for example, one search_people call per company — cap its parallelism at your plan’s limit.
Phone tokens
linkedin_to_mobile_phone spends phone tokens. They’re separate from your regular token balance and from the Fair Use windows above. One phone token is spent per returned result; a miss costs nothing.
Phone tokens aren’t included in any plan. You buy them through a phone token subscription, a monthly add-on billed separately from your main plan. You must be on a paid plan to buy one — the free plan has no phone tokens.
To subscribe, log into app.moltsets.com and go to Pricing.
How the subscription works:
- Billing follows your main plan. The phone token subscription renews on the same date as your main plan.
- Mid-cycle purchases are prorated. If you subscribe partway through a cycle, both the first charge and the first month’s tokens are prorated to the days left until your renewal date.
- Unused tokens roll over. Tokens you don’t spend carry into the next month.
- You keep tokens only while subscribed. If you cancel your phone token subscription, you lose any unused phone tokens.
- Cancelling your main plan cancels both. Your phone token subscription ends with your main plan, and you lose any unused phone tokens.
- No one-off purchases. You can’t buy phone tokens individually. The subscription is the only way to get them.
402 with insufficient_phone_tokens; a batch drops the items it can’t cover and returns the rest. Each call reports phone_tokens_used and phone_tokens_remaining in metadata.
To check your phone tokens without spending any, call get_account. It returns phone_token_balance, your monthly phone_token_allowance, and your subscription in phone_plan. Without a subscription, the counts are 0 and phone_plan is null.
How the window works
This works as a rolling window, not a fixed daily reset. The moment you make your first request, a 5-hour window opens. Everything you use for the next 5 hours draws from the same pool — the figure in your plan’s row above. When the window closes, the limit resets, and your next request kicks off a fresh 5-hour window. A $97 account can therefore spend all 15k enrichment records in the first minute and then wait out the rest of that window, or spread the same 15k evenly across the five hours. The weekly window works the same way — it rolls from your first request rather than resetting on a calendar day. Nothing is scheduled, so there’s no reset hour to plan around.get_account reports resets_at for each window, which is the exact moment your current pool refills — see Check where you stand.
What counts as a request
Every API call counts toward the rate limit, regardless of whether it returns data — anot_found is still a request. Each item of a batch counts separately, so a batch of 100 counts as 100 requests. The account tools (get_account, get_billing, get_usage) don’t count toward the enrichment or search Fair Use limits.
What counts as a miss
A lookup that finds nothing still counts as a request, but consumes no records and no tokens. It returns HTTP200 with status: "not_found" — see Reading an outcome. Records are only consumed when data is actually returned, and are handed back if a later cap drops the result.
Check where you stand
Before assuming you’ve hit a wall, check your current position.get_account, get_billing, and get_usage are free — they never cost tokens.
get_account — live rate-limit standing
get_account returns a fair_use object that mirrors the tables above: enrich and search, each split into records and requests, over the 5h and 1w windows. Each window reports limit, used, remaining, and resets_at — so you can see exactly how much headroom is left and when the window rolls over.
resets_at of null means the window hasn’t started counting yet (nothing used); once you make calls it carries the ISO 8601 timestamp when that window resets.
get_usage — consumption history
get_usage shows how many calls you’ve actually made over a period, broken out by day plus a totals block — calls, with_data, without_data, and failed. Use it to spot bursts that are pushing you toward the 5-hour caps and to confirm which runs are driving your volume.
Ask your connected agent “check my MoltSets rate-limit headroom” and it will read these for you.
Staying within the limit
A few approaches to keep your usage within bounds:Spread your automations out
If you’re running scheduled tasks, split them across 2–4 runs per day rather than one large burst. Because the 5-hour window rolls from your first request, spacing runs at least five hours apart gives each one a fresh pool to draw from.Use batching with pauses between batches
For high-volume operations — say, updating 10,000 leads — don’t fire all requests at once. Instead:- Group your calls into batches of 100
- Wait 2 seconds between each batch
- Continue until all requests are processed
Rate limit errors
When you exceed a limit, the API returns429 Too Many Requests with one of four codes:
429s carry metadata.retry_after — seconds until the binding window unlocks — and the same value in a Retry-After header. Wait that long rather than guessing a backoff.
The exception is a limit that is a plan condition rather than a window: an exhausted free-tier search trial returns fair_use_limit_exceeded with an upgrade message and no Retry-After, because that grant never refreshes. Retrying will not clear it.
The request is not retried automatically — your client is responsible for handling 429 responses.
Batches return partial results, not a 429
When a batch runs past a Fair Use window, the items beyond your allowance are dropped unprocessed and the call still returns200 with the results it did produce, plus an error block naming the cap that fired. That 200 carries metadata.retry_after and a Retry-After header, exactly like the single-call 429 — a half-succeeded batch is the response most likely to be retried in a tight loop, so read the header before resending. Resend only the items that were dropped.
Handling rate limits
When a429 carries Retry-After, honour it — it is the exact number of seconds until the binding window unlocks, and retrying sooner just burns request quota. For search_concurrency_exceeded, wait 1 second and lower the number of searches you run in parallel. Where there is no header, fall back to exponential backoff:
linkedin_to_mobile_phone supports up to 100 linkedin_urls per call) cut the number of HTTP calls you make — but not your request count. Each item in a batch still counts as one request, so a batch of 100 draws 100 requests from your Fair Use requests limit.