MyLeadFox API

The three scopes (permissions)

A call that needs a scope the key does not carry is refused with 403 insufficient_scope (the body names it in required_scope). A key that only counts searches should not carry the scopes that spend download or enrichment credits.

Rotating and revoking

Rotating a key issues a new secret and stops the old one at once; the name, scopes and allowlist stay the same. Revoking stops the key for good. The account owner is emailed whenever a key is created, rotated or revoked (the email never contains the key). Keys belong to the account, not to a person. The full guide: Create and rotate API keys.

Who gets the API

Access is checked on every call, against the account that pays (the team owner’s, for a team member). A key keeps working only while the plan does: access is re-checked on every call, so a key made on a plan that later lapses is refused with 402 no_active_plan on its very next call.

Common mistakes, and what you will see

From a terminal (curl), Python or JavaScript

The same call in three languages: pick one in the bar above the code. The Python uses the requests package; the JavaScript uses fetch and is meant for a server (Node.js 18 or later), never a web page, because the key must stay secret.

curl -X POST https://go.myleadfox.com/api/v1/search \
  -H 'Authorization: Bearer mlf_live_YOUR_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "filters": [
    { "kind": "dropdown", "col": "country", "values": ["US"] }
  ]
}'

From Zapier, Make, n8n or any HTTP tool

Use the tool’s generic HTTP request module (not a form or webhook trigger) with these settings:

The response

A real reply. total is how many shops match, search_id names this search, and credits shows what the call spent and what you have left.

{
  "search_id": "de11cac33c3da5df",
  "search_url": "/grid/de11cac33c3da5df",
  "total": 1281396,
  "pages": 12814,
  "page_size": 100,
  "filters": [
    {
      "kind": "dropdown",
      "col": "country",
      "values": [
        "US"
      ]
    }
  ],
  "search": null,
  "sort": [],
  "global_search": false,
  "credits": {
    "search_remaining": 4999,
    "download_remaining": 200000,
    "enrich_remaining": 500,
    "charged": 1,
    "charged_unit": "searches"
  }
}

Next: get the rows

Send the search_id to https://go.myleadfox.com/api/v1/rows and ask for page 1. Each row delivered costs 1 download credit.

curl -X POST https://go.myleadfox.com/api/v1/rows \
  -H 'Authorization: Bearer mlf_live_YOUR_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"search_id": "de11cac33c3da5df", "page": 1, "columns": ["domain", "name", "country"]}'

When a balance is smaller than the call

The credits block

Balances live in the JSON body, in a credits object. The balances are read after the charge, so they already include this call.

"credits": {
  "search_remaining": 4993,
  "download_remaining": 199900,
  "enrich_remaining": 500,
  "charged": 100,
  "charged_unit": "leads"
}

• null is not zero. A null balance means the account has no defined allowance of that kind, or the balances could not be read for a moment after the call (charged and charged_unit are still filled in then). It never means 0.
• Present on every successful call, and on every refusal made after your key and account were accepted: 429 rate_limited, 402 insufficient_credits, the 400s, the 404s search_not_found and page_out_of_range, 403 feature_disabled, and 500.
• Absent on the key and account refusals (401 missing_api_key and invalid_api_key; 403 ip_not_allowed, account_inactive, free_trial_no_api and insufficient_scope; 402 no_active_plan and account_frozen), and on 405, 404 Not Found and 422 schema errors.

Export a grid search into a spreadsheet

1. Build the search in the app’s grid. The address in your browser becomes https://go.myleadfox.com/grid/<id>. Copy the id: the 16 characters after /grid/. Any grid link works, including one a teammate shared.
2. Ask for page 1: POST https://go.myleadfox.com/api/v1/rows with {"search_id": "<id>", "page": 1, "columns": [...]}. Add "include_total": true on page 1 if you want to know how many pages there are. If the order matters, send the same sort on every page: sort is not stored in the id.
3. Turn each object in rows into a spreadsheet row. Use the columns array as your header row and read each value by its name.
4. Ask for page 2, 3 and so on until you reach the last page. The page after the last one answers 404 page_out_of_range, free, with the real page count: that is your signal to stop.
5. If truncated_by_credits is true:
   • truncated_by_credits is decided BEFORE the page is read: it is true whenever your balance was smaller than limit. That includes a short LAST page that came back complete.
   • So read credits.download_remaining on the same response. If it is 0 (or null), the balance ran out and this page may be cut: top up and ask for the SAME page again — that call delivers and charges the whole page again, including the rows you already received (limit only caps from the start of a page; it cannot skip rows). If you sent include_total, you can confirm first: the page can hold min(limit, total − (page − 1) × 100) rows; if returned equals that, nothing is missing.
   • If download_remaining is above 0, this page almost certainly had fewer rows than limit because it was the last page. Do NOT ask for it again (that would charge it twice); carry on — the next page answering 404 page_out_of_range confirms it. If the next page returns rows instead, your balance was topped up or reset during that call and the earlier page really was cut: ask for that earlier page again.
6. If a page answers 402 insufficient_credits, your download balance is 0 and nothing was delivered or charged. Top up, then carry on from that same page.

Each row costs 1 download credit. The id stores the search, not a copy of the rows, so every page is read live: if the data changes while you page, the result can change with it.

Kept in Download History.

• Every successful /rows and /lookup call writes one entry to Download History in the app — one entry per call, so 15 pages make 15 entries, grouped by their search_id. Each entry shows the time, the leads charged and the last 6 characters of the key that made the call.
• The response body is kept for 100 days and can be downloaded again there, as JSON, at no charge and as often as you like. The saved copy is the response as it was delivered, without its credits block — not a re-run of the query.
• API entries cannot be sent to Google Sheets (that export is for CSV downloads made in the app).
• The response does not carry a history id: find the entry by its time and lead count. There is no API endpoint for listing or fetching history; it is in the app.
• /enrich calls are not saved in Download History, so store their results on your side.

import csv, time, requests

URL = "https://go.myleadfox.com/api/v1/rows"
HEADERS = {"Authorization": "Bearer mlf_live_YOUR_KEY", "Content-Type": "application/json"}
SEARCH_ID = "de11cac33c3da5df"            # the id from https://go.myleadfox.com/grid/<id>
COLUMNS = ["domain", "name", "country", "products"]
START_PAGE = 1                            # to resume, set this to the page the script printed
TRIES = 3                                 # attempts per page on a 500 from the API (refunded, safe)
WAITS = 10                                # most 429 waits per page before giving up


def fetch(page):
    """Ask for one page. Returns (HTTP status, JSON body or None)."""
    failures = waits = 0
    while True:
        r = requests.post(URL, headers=HEADERS, timeout=60,
                          json={"search_id": SEARCH_ID, "page": page, "columns": COLUMNS})
        is_json = r.headers.get("Content-Type", "").startswith("application/json")
        if not is_json:                           # not from the API (e.g. a gateway page), any status:
            return r.status_code, None            # the page MAY already be delivered and charged
        if r.status_code == 429 and waits < WAITS:  # the API's own 429: never charged, wait as told
            waits += 1
            try:
                wait = int(r.headers.get("Retry-After", "5"))
            except ValueError:
                wait = 5
            time.sleep(max(1, wait))
            continue
        if r.status_code != 500:
            return r.status_code, r.json()
        failures += 1                             # a 500 from the API is refunded: safe to retry
        if failures >= TRIES:
            return r.status_code, r.json()
        time.sleep(5 * failures)                  # a short wait, then the SAME page again


page = START_PAGE
maybe_last = None                                 # a short page that looked complete (see below)
with open("shops.csv", "w" if START_PAGE == 1 else "a", newline="") as f:
    w = csv.DictWriter(f, fieldnames=COLUMNS)     # read values by NAME, not by position
    if START_PAGE == 1:
        w.writeheader()
    while True:
        try:
            status, body = fetch(page)
        except requests.RequestException as e:    # no answer at all, e.g. a timeout on your side
            print(f"No answer for page {page} ({e}). Before resuming from page {page}, look for it "
                  "in Download History: if it is there, it was delivered and charged.")
            break
        if body is None:                          # not an API reply: do NOT retry blindly
            print(f"Page {page}: HTTP {status} without a JSON body. Before resuming from page {page}, "
                  "look for it in Download History: if it is there, it was delivered and charged.")
            break
        if status == 404 and body.get("error") == "page_out_of_range":
            break                                 # past the last page: done
        if status == 402 and body.get("error") == "insufficient_credits":
            # download balance is 0: nothing delivered, nothing charged
            print(f"Download balance used up. Top up, then resume with START_PAGE = {page}")
            break
        if status != 200:
            print(f"Page {page}: HTTP {status} {body.get('error')}: {body.get('message')}")
            break
        if maybe_last is not None:
            # The short page before this one was NOT the last page after all: your balance was
            # topped up (or reset) during that call, so it really was cut. Get it again first.
            print(f"Page {maybe_last} was cut short after all. Resume with START_PAGE = {maybe_last} "
                  "(that page is delivered and charged again in full).")
            break
        w.writerows(body["rows"])                 # saved the moment it arrives
        f.flush()
        left = (body.get("credits") or {}).get("download_remaining")
        if body["truncated_by_credits"] and left in (0, None):
            # The balance ran out inside this page. Asking for the SAME page again delivers and
            # charges the WHOLE page again, including the rows just saved: remove those duplicates.
            print(f"Balance ran out at page {page} ({len(body['rows'])} rows saved). If fewer than 100 "
                  "rows came back this may simply have been the LAST page, complete: check the shop "
                  "total before resuming. Otherwise top up, then resume with START_PAGE = "
                  f"{page} (that page is delivered and charged again in full).")
            break
        # truncated_by_credits with a balance still left = almost certainly a short LAST page,
        # complete: carry on. The next page answering 404 confirms it; if it returns rows instead,
        # the check above stops and names the cut page. Never re-ask blindly: it charges twice.
        if body["truncated_by_credits"]:
            maybe_last = page
        page += 1

Each page is written to the file the moment it arrives, so nothing you have paid for is lost when the loop stops early. It stops cleanly on a 402 insufficient_credits and when a page is cut short by your balance (truncated_by_credits with download_remaining at 0), and prints the page to resume from; any other refusal stops with its error code and message. It waits and retries the API’s own JSON 429 as its Retry-After says (a limited number of times), and retries a JSON 500 from the API (never charged) a few times with a short wait. If a short page looked complete but the next page still returns rows, it stops and names the page to fetch again (your balance was topped up during that call). It does NOT retry a reply that is not JSON (a gateway error or challenge page), or a call that got no answer at all: either may already have been delivered and charged. It stops and tells you to check Download History first — see Retries and timeouts below.

Retries and timeouts

• There is no idempotency key. A retry that reaches the server is a new call: it does the work again and charges again.
• A retried /rows or /lookup call is charged again, even if the first one was delivered and you never saw its answer.
• After a client-side timeout on /rows or /lookup, look in Download History in the app before you retry: if the call is there (match it by time and leads charged), it was delivered and charged, and you can download that response again for free instead of paying for it twice.
• A JSON 429, a JSON 500 and any other JSON refusal from the API cost nothing, so retrying those never double-charges.
• A reply that is NOT JSON (a gateway error, a timeout page or a challenge page, whatever its status) did not come from the API, and it can arrive after the call was already delivered and charged. Never retry it blindly: treat it like a timeout and check Download History first.
• /enrich: Resending a batch never charges twice for one domain: every domain the first call finished as enriched or no_contact_found comes back as already, free — even if you never saw the first response. Domains that came back error, or that were cut off when the call died, were refunded; on a resend they are checked again and charged only if contacts are found.

Enrich a list of domains

1. Split your domains into batches of at most 100. In an automation tool with a short time limit per step, send smaller batches.
2. POST https://go.myleadfox.com/api/v1/enrich with {"domains": ["a.com", "b.com"]}. Raise your tool's timeout to its maximum: each domain is checked live, and a call with 100 domains can take over a minute.
3. For each entry in results, read outcome first. enriched and already carry the top 5 contacts per domain (best first) in people; write one spreadsheet row per listed person. people_count is how many were found in total and can be larger than the list. not_in_grid and no_contact_found are final — do not resend them.
4. Collect the domains that came back not_attempted (the call ran out of time) and send them again. Send error domains again later. Send skipped_no_credit domains again after topping up your enrichment credits.
5. Resending a batch never charges twice for one domain: every domain the first call finished as enriched or no_contact_found comes back as already, free — even if you never saw the first response. Domains that came back error, or that were cut off when the call died, were refunded; on a resend they are checked again and charged only if contacts are found.
6. Only enriched costs an enrichment credit. /enrich calls are not saved in Download History, so store the results on your side.

All seven outcomes are explained under Enrich.

Copy-paste filters

{"filters": [{"kind": "dropdown", "col": "country", "values": ["US"]}]}

{"filters": [{"kind": "dropdown", "col": "has_email", "values": ["yes"]}]}

{"filters": [{"kind": "dropdown", "col": "actual_platform", "values": ["Shopify"]}]}

{"filters": [{"kind": "tags", "col": "google_category", "mode": "branch", "values": ["Apparel & Accessories > Clothing"]}]}

{"filters": [
  {"kind": "dropdown", "col": "country", "values": ["US"]},
  {"kind": "dropdown", "col": "has_email", "values": ["yes"]},
  {"kind": "dropdown", "col": "actual_platform", "values": ["Shopify"]}
]}

Dropdown values are matched exactly as stored: US, yes, Shopify.

The five kinds

Which kind each column takes is shown beside its name in the Columns section.

{"filters": [
{"kind": "dropdown", "col": "country", "values": ["US"], "conn": "or"},
{"kind": "dropdown", "col": "country", "values": ["GB"], "conn": "or"},
{"kind": "numeric",  "col": "products", "op": "gte", "min": 50},
{"kind": "text",     "col": "tagline",  "mode": "contains", "value": "coffee", "not": true}
]}

{"kind": "text", "col": "tagline", "mode": "regex", "parts": [
  {"term": "coffee"},
  {"term": "roaster", "conn": "or"},
  {"term": "wholesale", "conn": "not"},
  {"term": "beans"}
]}

Every operator, with the count it matched

Each example below was run against the real dataset when these docs were generated (12-Oct-2026); the count is what that exact example returned. The dataset changes every day, so your count will differ.

Date bounds and includeNull

These options were not part of the measured run, so they have no count. What each one does:

A missing value is not a zero.

• In /rows and /lookup, a value that was never measured comes back as an empty string "" — for every column type: text, numbers and dates alike. A row never contains null. One exception: country holds the value "Unknown" (never "") when the country is not known — a text filter with mode empty / not_empty on country treats "Unknown" as blank.
• A number column therefore holds either a number or "". The API never turns a missing value into 0, so 0 is a real measured zero and "" means "not measured".
• For a text column, "" means there is no value: never measured and measured-as-empty are the same thing. Treat "" as unknown, not as evidence that something is absent.

Two notes specific to est_monthly_visits: it is a third-party estimate of monthly traffic rather than a figure we measure, and it is empty ("" in the API) for a little under half of all shops. Where a shop sits on a subdomain, the estimate is usually the traffic of its parent domain — so an unusually large number on a subdomain may belong to the parent site rather than to the shop.

Beside each name is the filter kind it takes (see Filters). Hover a name for its type.

What an error body looks like

{
  "error": "insufficient_credits",
  "message": "Not enough download credits: this call needs 1 and 0 remain.",
  "pool": "download",
  "needed": 1,
  "remaining": 0,
  "credits": {
    "search_remaining": 4997,
    "download_remaining": 0,
    "enrich_remaining": 500,
    "charged": 0,
    "charged_unit": "none"
  }
}

{
  "error": "invalid_api_key",
  "message": "That API key is not valid."
}

HTTP 429
Retry-After: <whole seconds to wait>

{
  "error": "rate_limited",
  "message": "Rate limit exceeded. Retry after the interval in the `Retry-After` header.",
  "reason": "per_key",
  "retry_after": <the same number>,
  "credits": { … }
}

HTTP 405 Method Not Allowed
Allow: POST

{"detail": "Method Not Allowed"}

{"detail": [{"type": "greater_than_equal", "loc": ["body", "page"], "msg": "Input should be greater than or equal to 1", "input": 0, "ctx": {"ge": 1}}]}

{"detail": [{"type": "missing", "loc": ["body"], "msg": "Field required", "input": null}]}

In a 422, loc says where the problem is (["body", "page"]) and msg says what is wrong. The exact wording of msg comes from the framework and can change between versions; branch on the status code.

What each call counts against the limit

Each call uses a number of units out of the key’s 60. Filters alone always use 1. A call with global text search uses more: that means a non-empty search text, or a search_id whose saved search has search text. Calls of different kinds add up within the same 60.

Units are not credits. Units only pace how fast a key may call; credits are what a call spends.

When you hit a limit

• The reply is 429 rate_limited with a Retry-After header: the whole number of seconds to wait (at least 1, at most 60). The body repeats it as retry_after.
• reason says which limit: per_key (the key used its units), too_many_concurrent (2 calls already in flight on the key; Retry-After is 1), or server_busy / fair_share (the service is busy — wait and retry).
• Wait the number of seconds given, then send the same call again.

Speed

• Filtered calls are fast, including deep pages.
• A global text search is slower on its first call and quicker on the pages after it.
• /enrich checks each domain live while the call runs and can take over a minute for 100 domains. Raise your tool’s timeout to its maximum, or send smaller batches. Domains the call had no time for come back not_attempted, free: send them again.

No account yet? Get started — the API comes with every paid plan and pass. Already have one? Create your key below.