Using the API

Polling and status

There are no webhooks. Poll a running scrape every 30 to 60 seconds until it is complete.

A scrape searches Google Maps live and takes minutes to hours. Every call answers at once: create_scrape returns while the scrape starts, and nothing is pushed to you when it ends.

Leadity does not send webhooks. To learn that a scrape finished, poll it.

Poll the status, not the scrape

get_scrape_status reads only the scrape's own record, which makes it the cheap call to repeat. Poll it every 30 to 60 seconds, never faster, until complete is true.

{
  "id": "Vb7nW3xQ9k",
  "status": "running",
  "complete": false,
  "targetLeads": 1000,
  "leadsDelivered": null,
  "creditsUsed": null,
  "stoppedByUser": false,
  "startedAt": "2026-10-03T16:40:05.000Z",
  "settledAt": null
}

When complete turns true the scrape has settled: leadsDelivered and creditsUsed are final and any unused credits are back on the balance. For a live count while it runs, read get_scrape, which costs more.

Python

import os
import time

import requests

headers = {"Authorization": f"Bearer {os.environ['LEADITY_API_KEY']}"}
scrape_id = "Vb7nW3xQ9k"

while True:
    status = requests.get(f"https://api.leadity.io/v1/scrapes/{scrape_id}/status", headers=headers).json()
    if status["complete"]:
        break
    time.sleep(45)

print(f"Delivered {status['leadsDelivered']} leads for {status['creditsUsed']} credits")

Validations

A validation run is watched the same way: poll get_validation every 30 to 60 seconds until its status is final. A few thousand items take a minute or two.

For agents

An MCP client is told the same cadence in the server's instructions and in each tool's description. A model told to poll without being told how often polls as fast as the rate limit allows, which only burns its own allowance.