POST

stats

Search Stats

curl --request POST \
  --url https://api.leadmagic.io/v3/search/stats \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "products": [
    "jobs",
    "company",
    "people"
  ],
  "sections": [
    "coverage",
    "top"
  ],
  "limit": 10
}
'

import requests

url = "https://api.leadmagic.io/v3/search/stats"

payload = {
    "products": ["jobs", "company", "people"],
    "sections": ["coverage", "top"],
    "limit": 10
}
headers = {
    "X-API-Key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'X-API-Key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    products: ['jobs', 'company', 'people'],
    sections: ['coverage', 'top'],
    limit: 10
  })
};

fetch('https://api.leadmagic.io/v3/search/stats', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.leadmagic.io/v3/search/stats"

	payload := strings.NewReader("{\n  \"products\": [\n    \"jobs\",\n    \"company\",\n    \"people\"\n  ],\n  \"sections\": [\n    \"coverage\",\n    \"top\"\n  ],\n  \"limit\": 10\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-API-Key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.leadmagic.io/v3/search/stats",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'products' => [
        'jobs',
        'company',
        'people'
    ],
    'sections' => [
        'coverage',
        'top'
    ],
    'limit' => 10
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "X-API-Key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

{
  "success": false,
  "errors": [
    {
      "type": "https://api.leadmagic.io/errors/validation_error",
      "title": "Request validation failed. Check your input parameters.",
      "status": 400,
      "code": "validation_error",
      "param": [
        "email"
      ],
      "detail": "Email format is invalid. Expected format: user@domain.com",
      "action": "Provide a valid email address in the 'email' field.",
      "docs": "https://leadmagic.io/docs/api-reference/errors"
    }
  ],
  "meta": {
    "request_id": "ea6e3248-f4d2-437d-bca3-20881b529129",
    "timestamp": "2024-02-01T12:00:00.000Z"
  }
}

{
  "success": false,
  "errors": [
    {
      "type": "https://api.leadmagic.io/errors/missing_authentication",
      "title": "Authentication required. Provide a valid API key in the X-API-Key header (case-insensitive).",
      "status": 401,
      "code": "missing_authentication",
      "docs": "https://leadmagic.io/docs/api-reference/authentication"
    }
  ],
  "meta": {
    "request_id": "ea6e3248-f4d2-437d-bca3-20881b529129",
    "timestamp": "2024-02-01T12:00:00.000Z"
  }
}

{
  "success": false,
  "errors": [
    {
      "type": "https://api.leadmagic.io/errors/rate_limit_exceeded",
      "title": "Rate limit exceeded: 300 requests per 1 minute. Wait and try again.",
      "status": 429,
      "code": "rate_limit_exceeded",
      "detail": "You have exceeded the maximum allowed request rate. Please wait before making additional requests.",
      "action": "Wait 42 seconds before retrying. Consider implementing exponential backoff.",
      "docs": "https://leadmagic.io/docs/api-reference/rate-limits",
      "context": {
        "limit": 300,
        "window": "1 minute",
        "remaining": 0,
        "reset_at": 1706745642,
        "retry_after_seconds": 42
      }
    }
  ],
  "meta": {
    "request_id": "ea6e3248-f4d2-437d-bca3-20881b529129",
    "timestamp": "2024-02-01T12:00:00.000Z"
  }
}

Search Stats

POST /v3/search/stats is a free helper endpoint that summarizes what is available across Jobs, Company, and People Search. Use it to power filter builders, capability cards, onboarding screens, or “what can I target?” UI. The endpoint returns cached, high-level metrics only. It does not return records, contacts, or jobs.

Quick Example

curl -X POST 'https://api.leadmagic.io/v3/search/stats' \
  -H 'X-API-Key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "products": ["jobs", "company", "people"],
    "sections": ["coverage", "top"],
    "limit": 3
  }'

const response = await fetch('https://api.leadmagic.io/v3/search/stats', {
  method: 'POST',
  headers: {
    'X-API-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    products: ['jobs', 'company', 'people'],
    sections: ['coverage', 'top'],
    limit: 3
  })
});

const data = await response.json();
console.log(data.company?.coverage, data.jobs?.top);

Request Body

string[]

default:"[\"jobs\",\"company\",\"people\"]"

Product families to include. Allowed values: jobs, company, people.

string[]

default:"[\"coverage\",\"top\",\"capabilities\"]"

Sections to include. Allowed values: coverage, top, capabilities.

integer

default:"3"

Number of top values to return for each dimension. Defaults to 3; maximum is 25.

Request Examples

Coverage only:

{
  "products": ["jobs", "company", "people"],
  "sections": ["coverage"]
}

Top company and people dimensions:

{
  "products": ["company", "people"],
  "sections": ["top"],
  "limit": 3
}

Jobs capabilities and filter counts:

{
  "products": ["jobs"],
  "sections": ["coverage", "capabilities", "top"]
}

Response

number

Always 0.

object

Jobs coverage metrics such as open jobs, total indexed jobs, companies, and title embeddings.

object

Supported Jobs Search capabilities and filter families.

object

Top jobs dimensions such as common titles, specialties, role families, industries, company types, and countries.

object

Company coverage metrics such as estimated companies, company records with technology data, and contact coverage rollups.

object

Top company dimensions such as industries, countries, regions, size ranges, revenue ranges, funding types, SIC/NAICS, and each technology category.

object

People/contact coverage metrics, including estimated contacts and email/phone availability rollups.

object

Top people/contact coverage dimensions by company.

object

Cache status for each backend stats source.

Job Search

Search jobs using the capabilities shown here.

Company Search

Search companies using the company dimensions shown here.

People Search

Search contacts using the people coverage shown here.

Job Search Helpers

Resolve concrete filter values for Jobs Search.

Authorizations

X-API-Key

string

header

required

Your LeadMagic API key. Header name is case-insensitive (X-API-Key, X-API-KEY, x-api-key all work).

Body

application/json

products

enum<string>[]

Available options:

jobs,

company,

people

sections

enum<string>[]

Available options:

coverage,

top,

capabilities

limit

integer

default:10

Required range: 1 <= x <= 25

Response

Search stats results

Search Stats

curl --request POST \
  --url https://api.leadmagic.io/v3/search/stats \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "products": [
    "jobs",
    "company",
    "people"
  ],
  "sections": [
    "coverage",
    "top"
  ],
  "limit": 10
}
'

import requests

url = "https://api.leadmagic.io/v3/search/stats"

payload = {
    "products": ["jobs", "company", "people"],
    "sections": ["coverage", "top"],
    "limit": 10
}
headers = {
    "X-API-Key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'X-API-Key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    products: ['jobs', 'company', 'people'],
    sections: ['coverage', 'top'],
    limit: 10
  })
};

fetch('https://api.leadmagic.io/v3/search/stats', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.leadmagic.io/v3/search/stats"

	payload := strings.NewReader("{\n  \"products\": [\n    \"jobs\",\n    \"company\",\n    \"people\"\n  ],\n  \"sections\": [\n    \"coverage\",\n    \"top\"\n  ],\n  \"limit\": 10\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-API-Key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.leadmagic.io/v3/search/stats",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'products' => [
        'jobs',
        'company',
        'people'
    ],
    'sections' => [
        'coverage',
        'top'
    ],
    'limit' => 10
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "X-API-Key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

{
  "success": false,
  "errors": [
    {
      "type": "https://api.leadmagic.io/errors/validation_error",
      "title": "Request validation failed. Check your input parameters.",
      "status": 400,
      "code": "validation_error",
      "param": [
        "email"
      ],
      "detail": "Email format is invalid. Expected format: user@domain.com",
      "action": "Provide a valid email address in the 'email' field.",
      "docs": "https://leadmagic.io/docs/api-reference/errors"
    }
  ],
  "meta": {
    "request_id": "ea6e3248-f4d2-437d-bca3-20881b529129",
    "timestamp": "2024-02-01T12:00:00.000Z"
  }
}

{
  "success": false,
  "errors": [
    {
      "type": "https://api.leadmagic.io/errors/missing_authentication",
      "title": "Authentication required. Provide a valid API key in the X-API-Key header (case-insensitive).",
      "status": 401,
      "code": "missing_authentication",
      "docs": "https://leadmagic.io/docs/api-reference/authentication"
    }
  ],
  "meta": {
    "request_id": "ea6e3248-f4d2-437d-bca3-20881b529129",
    "timestamp": "2024-02-01T12:00:00.000Z"
  }
}

{
  "success": false,
  "errors": [
    {
      "type": "https://api.leadmagic.io/errors/rate_limit_exceeded",
      "title": "Rate limit exceeded: 300 requests per 1 minute. Wait and try again.",
      "status": 429,
      "code": "rate_limit_exceeded",
      "detail": "You have exceeded the maximum allowed request rate. Please wait before making additional requests.",
      "action": "Wait 42 seconds before retrying. Consider implementing exponential backoff.",
      "docs": "https://leadmagic.io/docs/api-reference/rate-limits",
      "context": {
        "limit": 300,
        "window": "1 minute",
        "remaining": 0,
        "reset_at": 1706745642,
        "retry_after_seconds": 42
      }
    }
  ],
  "meta": {
    "request_id": "ea6e3248-f4d2-437d-bca3-20881b529129",
    "timestamp": "2024-02-01T12:00:00.000Z"
  }
}

Get Started

API Endpoints

MCP Server

CLI

Search Stats

Search Stats

Quick Example

Request Body

Request Examples

Response

Job Search

Company Search

People Search

Job Search Helpers

Authorizations

Body

Response

​Search Stats

​Quick Example

​Request Body

​Request Examples

​Response

​Related endpoints

Job Search

Company Search

People Search

Job Search Helpers

Authorizations

Body

Response

Search Stats

Quick Example

Request Body

Request Examples

Response

Related endpoints