Catalog

Get coverage

See which areas you have already swept for each niche.

GETapi.leadity.io/v1/coverage

Scope readMCP tool get_coverage

Answers, per niche, the ZIP or postal codes this account has already swept. A swept area is never swept again for the same niche, so it adds nothing to a new order: estimate_scrape counts it as covered. found is how many businesses the sweep found there, before any filter.

Example request

curl "https://api.leadity.io/v1/coverage?niches=plumber" \
  -H "Authorization: Bearer $LEADITY_API_KEY"

Example response

{
  "niches": [
    {
      "id": "plumber",
      "covered": [
        {
          "country": "US",
          "code": "78701",
          "found": 61
        }
      ],
      "states": [
        {
          "country": "US",
          "state": "TX",
          "coveredCodes": 1,
          "found": 61
        }
      ]
    }
  ]
}

Headers

Authorizationstringrequired

Bearer, a space, then an API key: Bearer lk_api_... An MCP key is refused here with wrong_key_kind.

Query parameters

nichesstringrequired

One to ten niche ids, comma-separated, e.g. plumber,electrician.

1 to 1,100 characters.

Response

nichesobject[]required

Show child attributes

idstringrequired

The niche id.

coveredobject[]required

Every code swept for this niche.

Show child attributes

countrystringrequired

codestringrequired

The ZIP or postal code swept.

foundintegerrequired

Businesses the sweep found on it.

statesobject[]required

The same, rolled up per state.

Show child attributes

countrystringrequired

statestringrequired

coveredCodesintegerrequired

Codes swept in this state.

foundintegerrequired

Businesses found across them.

Errors

Every refusal answers { error, message } with the status below. The full list is on the Errors page.

Code	Status	Meaning	Extra fields
unauthorized	401	The API key is missing, malformed, revoked or expired.	-
wrong_key_kind	401	This key opens the other surface: an API key works on the HTTP API, an MCP key on the MCP server.	-
account_suspended	403	The account is suspended.	-
email_not_verified	403	The account's email address is not verified yet.	-
invalid_body	400	The request does not match the operation's schema.	`issues`: The problems found, each with path (the field as a dotted path, led by the part of the request it travels in: path, query or body, such as body.items.1) and message (what is wrong there).
rate_limited	429	Too many requests. Wait for the Retry-After seconds and try again.	`retryAfterSeconds`: The seconds to wait, the same number as the Retry-After header.
try_again	503	Leadity could not answer just now. Retry in a moment, with the same Idempotency-Key on a spending call.	`retryAfterSeconds`: When a request with this Idempotency-Key is still being processed: the seconds to wait before retrying with the same key, as the Retry-After header says.
internal_error	500	Something failed on our side. Nothing was charged twice.	`body`: On the MCP server, when Leadity answered in a shape the tool does not publish: that answer as it came.